在ArkUI框架中，@State装饰器用于管理组件内的状态，使得状态变化能够触发UI的更新。以下将详细介绍@State的使用方法。
一、概述
1. 定义与作用
@State装饰的变量，即状态变量，是私有的，只能在组件内部访问。它是大部分状态变量的数据源，一旦其值发生改变，就可以触发直接绑定UI组件的刷新，从而实现UI与数据状态的同步更新。
2. 支持的版本
- 从API version 9开始，该装饰器支持在ArkTS卡片中使用。
- 从API version 11开始，该装饰器支持在元服务中使用。
3. 变量特点
-
单向/双向数据同步：与子组件中的
@Prop装饰变量之间建立单向数据同步，与@Link、@ObjectLink装饰变量之间建立双向数据同步。 - 生命周期：其生命周期与其所属自定义组件的生命周期相同。
二、装饰器使用规则
1. 装饰器参数
无参数。
2. 同步类型
不与父组件中任何类型的变量同步。
3. 允许装饰的变量类型
-
Object、class、string、number、boolean、enum类型，以及这些类型的数组。 - 支持
Date类型。 - API 11及以上支持
Map、Set类型。 - 支持
undefined和null类型（建议显式指定类型）。 - 支持ArkUI框架定义的联合类型
Length、ResourceStr、ResourceColor类型。 - API 11及以上支持上述支持类型的联合类型，如
string | number、string | undefined或者ClassA | null等。不支持any类型。
4. 被装饰变量的初始值
必须本地初始化，也可选择使用命名参数机制从父组件完成初始化（从父组件初始化将会覆盖本地初始化）。
三、变量的传递/访问规则
1. 从父组件初始化
支持父组件中常规变量（常规变量对@State赋值只是数值初始化，其变化不会触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量来初始化子组件的@State。
2. 用于初始化子组件
@State装饰的变量支持初始化子组件的常规变量、@State、@Link、@Prop、@Provide。
3. 是否支持组件外访问
不支持，只能在组件内访问。
四、观察变化和行为表现
1. 观察变化
- 简单类型（boolean、string、number）：可以观察到数值的变化。例如：
@State count: number = 0;
this.count = 1; // 可观察到变化
-
class或Object类型：可以观察到自身的赋值变化和其属性赋值的变化（
Object.keys(observedObject)返回的所有属性），但嵌套属性的赋值观察不到。例如：
class ClassA {
public value: string;
constructor(value: string) {
this.value = value;
}
}
class Model {
public value: string;
public name: ClassA;
constructor(value: string, a: ClassA) {
this.value = value;
this.name = a;
}
}
@State title: Model = new Model('Hello', new ClassA('World'));
this.title = new Model('Hi', new ClassA('ArkUI')); // 可观察到变化
this.title.value = 'Hi'; // 可观察到变化
this.title.name.value = 'ArkUI'; // 嵌套属性赋值观察不到
- array类型：可以观察到数组本身的赋值和添加、删除、更新数组元素的变化，但数组元素中属性的赋值观察不到。例如：
class Model {
public value: number;
constructor(value: number) {
this.value = value;
}
}
@State title: Model[] = [new Model(11), new Model(1)];
this.title = [new Model(2)]; // 可观察到变化
this.title[0] = new Model(2); // 可观察到变化
this.title.pop(); // 可观察到变化
this.title.push(new Model(12)); // 可观察到变化
this.title[0].value = 6; // 数组元素属性赋值观察不到
-
Date类型：可以观察到Date整体的赋值，同时可通过调用Date的接口（如
setFullYear、setMonth等）更新Date的属性。 -
Map类型（API 11及以上）：可以观察到Map整体的赋值，同时可通过调用Map的接口（如
set、clear、delete）更新Map的值。 -
Set类型（API 11及以上）：可以观察到Set整体的赋值，同时可通过调用Set的接口（如
add、clear、delete）更新Set的值。
2. 框架行为
当状态变量被改变时，框架会执行以下操作：
- 查询依赖该状态变量的组件。
- 执行依赖该状态变量的组件的更新方法，组件更新渲染。
- 和该状态变量不相关的组件或者UI描述不会发生重新渲染，从而实现页面渲染的按需更新。
五、使用场景
1. 装饰简单类型的变量
示例：
@Entry
@Component
struct MyComponent {
@State count: number = 0;
build() {
Button(`click times: ${this.count}`)
.onClick(() => {
this.count += 1;
})
}
}
当count改变时，只有关联它的Button组件会刷新。
2. 装饰class对象类型的变量
示例：
class Model {
public value: string;
constructor(value: string) {
this.value = value;
}
}
@Entry
@Component
struct EntryComponent {
build() {
Column() {
MyComponent({ count: 1, increaseBy: 2 })
.width(300)
MyComponent({ title: new Model('Hello World 2'), count: 7 })
}
}
}
@Component
struct MyComponent {
@State title: Model = new Model('Hello World');
@State count: number = 0;
private increaseBy: number = 1;
build() {
Column() {
Text(`${this.title.value}`)
.margin(10)
Button(`Click to change title`)
.onClick(() => {
this.title.value = this.title.value === 'Hello ArkUI'? 'Hello World' : 'Hello ArkUI';
})
.width(300)
.margin(10)
Button(`Click to increase count = ${this.count}`)
.onClick(() => {
this.count += this.increaseBy;
})
.width(300)
.margin(10)
}
}
}
如果count或title的值发生变化，会查询MyComponent中使用该状态变量的UI组件并重新渲染。
3. 装饰Map类型变量（API 11及以上）
示例：
@Entry
@Component
struct MapSample {
@State message: Map<number, string> = new Map([[0, "a"], [1, "b"], [3, "c"]]);
build() {
Row() {
Column() {
ForEach(Array.from(this.message.entries()), (item: [number, string]) => {
Text(`${item[0]}`).fontSize(30)
Text(`${item[1]}`).fontSize(30)
Divider()
})
Button('init map').onClick(() => {
this.message = new Map([[0, "a"], [1, "b"], [3, "c"]]);
})
Button('set new one').onClick(() => {
this.message.set(4, "d");
})
Button('clear').onClick(() => {
this.message.clear();
})
Button('replace the first one').onClick(() => {
this.message.set(0, "aa");
})
Button('delete the first one').onClick(() => {
this.message.delete(0);
})
}
.width('100%')
}
.height('100%')
}
}
点击按钮改变message的值，视图会随之刷新。
4. 装饰Set类型变量（API 11及以上）
示例：
@Entry
@Component
struct SetSample {
@State message: Set<number> = new Set([0, 1, 2, 3, 4]);
build() {
Row() {
Column() {
ForEach(Array.from(this.message.entries()), (item: [number]) => {
Text(`${item[0]}`).fontSize(30)
Divider()
})
Button('init set').onClick(() => {
this.message = new Set([0, 1, 2, 3, 4]);
})
Button('set new one').onClick(() => {
this.message.add(5);
})
Button('clear').onClick(() => {
this.message.clear();
})
Button('delete the first one').onClick(() => {
this.message.delete(0);
})
}
.width('100%')
}
.height('100%')
}
}
点击按钮改变message的值，视图会随之刷新。
5. State支持联合类型实例
示例：
@Entry
@Component
struct EntryComponent {
build() {
Column() {
MyComponent()
}
}
}
@Component
struct MyComponent {
@State count: number | undefined = 0;
build() {
Column() {
Text(`count(${this.count})`)
Button('change')
.onClick(() => {
this.count = undefined;
})
}
}
}
点击按钮改变count的属性或者类型，视图会随之刷新。
六、常见问题及解决方法
1. 使用箭头函数改变状态变量未生效
原因：箭头函数体内的this对象指向定义该函数时所在的作用域，而不是使用时所在的作用域。
解决方法：将当前this传入，调用代理状态变量的属性赋值。
2. 状态变量的修改放在构造函数内未生效
原因：在状态管理中，类会被一层“代理”包装。在构造函数中修改状态变量时，this指向未被代理封装的原始对象，后续触发事件无法响应变化。
解决方法：将状态变量的修改放在类的普通方法中，在对象初始化和代理封装完成后进行修改。
3. 状态变量只能影响其直接绑定的UI组件的刷新
示例说明：
- 简单类型值拷贝情况（如
string），改变父组件中简单类型状态变量的值，不会影响子组件中同名但不同引用的简单类型状态变量。 - 对于对象类型，当在组件间传递对象引用时，改变对象的一层属性会触发相关组件刷新，但改变嵌套属性（观测能力仅有一层）时，可能无法触发某些组件的刷新。
理解这些@State的使用方法和特点，有助于在ArkUI开发中更好地管理组件状态，构建出响应式的用户界面。同时，注意常见问题的避免和解决，能够提高开发效率和代码质量。
