目录
1 V2所属装饰器
1.1 @ObservedV2装饰器和@Trace装饰器：类属性变化观测
1、概述
2、装饰器说明
3、使用限制
1.2 @ComponentV2装饰器：自定义组件
1、概述
1.3 @Local装饰器：组件内部状态
1、概述
2、装饰器说明
3、变量传递
4、@Local与@State对比
1.4 @Param：组件外部输入
1、概述
2、装饰器说明
3、变量传递
4、限制条件
1.5 @Once：初始化同步一次
1、概述
2、装饰器使用规则说明
3、限制条件
1.6 @Event装饰器：规范组件输出
1、概述
2、装饰器说明
3、限制条件
1.7 @Provider装饰器和@Consumer装饰器：跨组件层级双向同步
1、概述
2、@Provider和@Consumer vs @Provide和@Consume能力对比
3、装饰器说明
基本规则
aliasName和属性名
4、变量传递
5、使用限制
6、使用场景
@Provider和@Consumer双向同步
1.8 @Monitor装饰器：状态变量修改监听
1、概述
2、装饰器说明
3、接口说明
IMonitor类型
4、监听变化
在@ComponentV2装饰的自定义组件中使用@Monitor
5、限制条件
@Monitor与@Watch对比
1.9 @Computed装饰器：计算属性
1、概述
2、装饰器说明
3、使用限制
1.10 @Type装饰器：标记类属性的类型
1、概述
2、装饰器说明
3、使用限制
2 其他状态管理
2.1 AppStorageV2: 应用全局UI状态存储
1、概述
2、使用说明
connect：创建或获取储存的数据
remove：删除指定key的储存数据
keys：返回所有AppStorageV2中的key
3、使用限制
2.2 PersistenceV2: 持久化储存UI状态
1、概述
2、使用说明
connect：创建或获取储存的数据
remove：删除指定key的储存数据
keys：返回所有PersistenceV2中的key
save：手动持久化数据
notifyOnError：响应序列化或反序列化失败的回调
3、使用限制
2.3 !!语法：双向绑定
1、概述
2、使用限制
3、使用场景
自定义组件间双向绑定
1 V2所属装饰器
- @ObservedV2装饰器和@Trace装饰器：类属性变化观测
- @ComponentV2装饰器：自定义组件
- @Local装饰器：组件内部状态
- @Param：组件外部输入
- @Once：初始化同步一次
- @Event装饰器：规范组件输出
- @Provider装饰器和@Consumer装饰器：跨组件层级双向同步
- @Monitor装饰器：状态变量修改监听
- @Computed装饰器：计算属性
- @Type装饰器：标记类属性的类型
1.1 @ObservedV2装饰器和@Trace装饰器：类属性变化观测
1、概述
@ObservedV2装饰器与@Trace装饰器用于装饰类以及类中的属性，使得被装饰的类和属性具有深度观测的能力：
- @ObservedV2装饰器与@Trace装饰器需要配合使用，单独使用@ObservedV2装饰器或@Trace装饰器没有任何作用。
- 被@Trace装饰器装饰的属性property变化时，仅会通知property关联的组件进行刷新。
- 在嵌套类中，嵌套类中的属性property被@Trace装饰且嵌套类被@ObservedV2装饰时，才具有触发UI刷新的能力。
- 在继承类中，父类或子类中的属性property被@Trace装饰且该property所在类被@ObservedV2装饰时，才具有触发UI刷新的能力。
- 未被@Trace装饰的属性用在UI中无法感知到变化，也无法触发UI刷新。
- @ObservedV2的类实例目前不支持使用JSON.stringify进行序列化。
2、装饰器说明
| @ObservedV2类装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 类装饰器 | 装饰class。需要放在class的定义前，使用new创建类对象。 |
| @Trace成员变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 可装饰的变量 | class中成员属性。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。 |
3、使用限制
@ObservedV2与@Trace装饰器存在以下使用限制：
- 非@Trace装饰的成员属性用在UI上无法触发UI刷新。
- @ObservedV2仅能装饰class，无法装饰自定义组件
- @Trace不能用在没有被@ObservedV2装饰的class上。
- @Trace是class中属性的装饰器，不能用在struct中。
- @ObservedV2、@Trace不能与@Observed、@Track混合使用
- 使用@ObservedV2与@Trace装饰的类不能和@State等V1的装饰器混合使用，编译时报错。
- 继承自@ObservedV2的类无法和@State等V1的装饰器混用，运行时报错。
- @ObservedV2的类实例目前不支持使用JSON.stringify进行序列化。
1.2 @ComponentV2装饰器：自定义组件
1、概述
和@Component装饰器一样，@ComponentV2装饰器用于装饰自定义组件：
在@ComponentV2装饰的自定义组件中，开发者仅可以使用全新的状态变量装饰器，包括@Local、@Param、@Once、@Event、@Provider、@Consumer等。
@ComponentV2装饰的自定义组件暂不支持组件复用、LocalStorage等现有自定义组件的能力。
无法同时使用@ComponentV2与@Component装饰同一个struct结构。
@ComponentV2支持一个可选的boolean类型参数freezeWhenInactive，来实现组件冻结功能。
一个简单的@ComponentV2装饰的自定义组件应具有以下部分：
@ComponentV2 // 装饰器
struct Index { // struct声明的数据结构
build() { // build定义的UI
}
}1.3 @Local装饰器：组件内部状态
1、概述
@Local表示组件内部的状态，使得自定义组件内部的变量具有观测变化的能力：
被@Local装饰的变量无法从外部初始化，因此必须在组件内部进行初始化。
当被@Local装饰的变量变化时，会刷新使用该变量的组件。
@Local支持观测number、boolean、string、Object、class等基本类型以及Array、Set、Map、Date等内嵌类型。
@Local的观测能力仅限于被装饰的变量本身。当装饰简单类型时，能够观测到对变量的赋值；当装饰对象类型时，仅能观测到对对象整体的赋值；当装饰数组类型时，能观测到数组整体以及数组元素项的变化；当装饰Array、Set、Map、Date等内嵌类型时，可以观测到通过API调用带来的变化。详见观察变化。
@Local支持null、undefined以及联合类型。
2、装饰器说明
| @Local变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 可装饰的变量类型 | Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。 |
| 装饰变量的初始值 | 必须本地初始化，不允许外部传入初始化。 |
3、变量传递
| 传递规则 | 说明 |
|---|---|
| 从父组件初始化 | @Local装饰的变量仅允许本地初始化，无法从外部传入初始化。 |
| 初始化子组件 | @Local装饰的变量可以初始化子组件中@Param装饰的变量。 |
4、@Local与@State对比
@Local与@State的用法、功能对比如下：
| @State | @Local | |
|---|---|---|
| 参数 | 无。 | 无。 |
| 从父组件初始化 | 可选。 | 不允许外部初始化。 |
| 观察能力 | 能观测变量本身以及一层的成员属性，无法深度观测。 | 能观测变量本身，深度观测依赖@Trace装饰器。 |
| 数据传递 | 可以作为数据源和子组件中状态变量同步。 | 可以作为数据源和子组件中状态变量同步。 |
1.4 @Param：组件外部输入
@Param不仅可以接受组件外部输入，还可以接受@Local的同步变化。在阅读本文档前，建议提前阅读：@Local。
1、概述
@Param表示组件从外部传入的状态，使得父子组件之间的数据能够进行同步：
@Param装饰的变量支持本地初始化，但是不允许在组件内部直接修改变量本身。
被@Param装饰的变量能够在初始化自定义组件时从外部传入，当数据源也是状态变量时，数据源的修改会同步给@Param。
@Param可以接受任意类型的数据源，包括普通变量、状态变量、常量、函数返回值等。
@Param装饰的变量变化时，会刷新该变量关联的组件。
@Param支持观测number、boolean、string、Object、class等基本类型以及Array、Set、Map、Date等内嵌类型。
对于复杂类型如类对象，@Param会接受数据源的引用。在组件内可以修改类对象中的属性，该修改会同步到数据源。
@Param的观测能力仅限于被装饰的变量本身。当装饰简单类型时，对变量的整体改变能够观测到；当装饰对象类型时，仅能观测对象整体的改变；当装饰数组类型时，能观测到数组整体以及数组元素项的改变；当装饰Array、Set、Map、Date等内嵌类型时，可以观测到通过API调用带来的变化。详见观察变化。
@Param支持null、undefined以及联合类型。
2、装饰器说明
| @Param变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 能否本地修改 | 否，修改值需使用@Event装饰器的能力。 |
| 同步类型 | 由父到子单向同步。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum等基本类型以及Array、Date、Map、Set等内嵌类型。支持null、undefined以及联合类型。 |
| 被装饰变量的初始值 | 允许本地初始化，若不在本地初始化，则需要和@Require装饰器一起使用，要求必须从外部传入初始化。 |
3、变量传递
| 传递规则 | 说明 |
|---|---|
| 从父组件初始化 | @Param装饰的变量允许本地初始化，若无本地初始化则必须从外部传入初始化。当同时存在本地初始值与外部传入值时，会优先使用外部传入值进行初始化。 |
| 初始化子组件 | @Param装饰的变量可以初始化子组件中@Param装饰的变量。 |
| 同步 | @Param可以和父组件传入的状态变量数据源（即@Local或@Param装饰的变量）进行同步，当数据源发生变化时，会将修改同步给子组件的@Param。 |
4、限制条件
@Param装饰器存在以下使用限制：
@Param装饰器只能在@ComponentV2装饰器的自定义组件中使用。
@Param装饰的变量表示组件外部输入，需要被初始化。支持使用本地初始值做初始化。当存在外部传入值时，将优先使用外部传入的值初始化。既不使用本地初始值，也不使用外部传入值是不允许的。
@Param装饰的变量在子组件中无法进行修改。但当装饰的变量类型为对象时，在子组件中修改对象中属性是允许的。
1.5 @Once：初始化同步一次
为了实现仅从外部初始化一次、不接受后续同步变化的能力，开发者可以使用@Once装饰器搭配@Param装饰器使用
1、概述
@Once装饰器仅在变量初始化时接受外部传入值进行初始化，当后续数据源更改时，不会将修改同步给子组件：
- @Once必须搭配@Param使用，单独使用或搭配其他装饰器使用都是不允许的。
- @Once不影响@Param的观测能力，仅针对数据源的变化做拦截。
- @Once与@Param装饰变量的先后顺序不影响实际功能。
- @Once与@Param搭配使用时，可以在本地修改@Param变量的值。
2、装饰器使用规则说明
@Once装饰器作为辅助装饰器，本身没有对装饰类型的要求以及对变量的观察能力。
| @Once变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 使用条件 | 无法单独使用，必须配合@Param装饰器使用。 |
3、限制条件
@Once只能用在@ComponentV2装饰的自定义组件中且仅能与@Param搭配使用。
@Once与@Param的先后顺序无关，可以写成@Param @Once也可以写成@Once @Param。
1.6 @Event装饰器：规范组件输出
为了实现子组件向父组件要求更新@Param装饰变量的能力，开发者可以使用@Event装饰器。使用@Event装饰回调方法是一种规范，表明子组件需要传入更新数据源的回调。
@Event主要配合@Param实现数据的双向同步。在阅读本文档前，建议提前阅读：@Param。
1、概述
由于@Param装饰的变量在本地无法更改，使用@Event装饰器装饰回调方法并调用，可以实现更改数据源的变量，再通过@Local的同步机制，将修改同步回@Param，以此达到主动更新@Param装饰变量的效果。
- @Event用于装饰组件对外输出的方法：
@Event装饰的回调方法中参数以及返回值由开发者决定。
@Event装饰非回调类型的变量不会生效。当@Event没有初始化时，会自动生成一个空的函数作为默认回调。
当@Event未被外部初始化，但本地有默认值时，会使用本地默认的函数进行处理。
- @Param标志着组件的输入，表明该变量受父组件影响，而@Event标志着组件的输出，可以通过该方法影响父组件。使用@Event装饰回调方法是一种规范，表明该回调作为自定义组件的输出。父组件需要判断是否提供对应方法用于子组件更改@Param变量的数据源。
2、装饰器说明
| @Event属性装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 允许装饰的变量类型 | 回调方法，例如()=>void、(x:number)=>boolean等。回调方法是否含有参数以及返回值由开发者决定。 |
| 允许传入的函数类型 | 箭头函数。 |
3、限制条件
-
@Event只能用在@ComponentV2装饰的自定义组件中。当装饰非方法类型的变量时，不会有任何作用。
1.7 @Provider装饰器和@Consumer装饰器：跨组件层级双向同步
@Provider和@Consumer用于跨组件层级数据双向同步，可以使得开发者不用拘泥于组件层级。
@Provider和@Consumer属于状态管理V2装饰器，所以只能在@ComponentV2中才能使用，在@Component中使用会编译报错。
@Provider和@Consumer提供了跨组件层级数据双向同步的能力。在阅读本文档前，建议提前阅读：@ComponentV2。
1、概述
@Provider，即数据提供方，其所有的子组件都可以通过@Consumer绑定相同的key来获取@Provider提供的数据。
@Consumer，即数据消费方，可以通过绑定同样的key获取其最近父节点的@Provider的数据，当查找不到@Provider的数据时，使用本地默认值。
@Provider和@Consumer装饰数据类型需要一致。
开发者在使用@Provider和@Consumer时要注意：
- @Provider和@Consumer强依赖自定义组件层级，@Consumer会因为所在组件的父组件不同，而被初始化为不同的值。
- @Provider和@Consumer相当于把组件粘合在一起了，从组件独立角度，要减少使用@Provider和@Consumer。
2、@Provider和@Consumer vs @Provide和@Consume能力对比
在状态管理V1版本中，提供跨组件层级双向的装饰器为@Provide和@Consume，当前文档介绍的是状态管理V2装饰器@Provider和@Consumer。虽然两者名字和功能类似，但在特性上还存在一些差异。
| 能力 | V2装饰器@Provider和@Consumer | V1装饰器@Provide和@Consume |
|---|---|---|
| @Consume(r) | 允许本地初始化，当找不到@Provider的时候使用本地默认值。 | 禁止本地初始化，当找不到对应的的@Provide时候，会抛出异常。 |
| 支持类型 | 支持function。 | 不支持function。 |
| 观察能力 | 仅能观察自身赋值变化，如果要观察嵌套场景，配合@Trace一起使用。 | 观察第一层变化，如果要观察嵌套场景，配合@Observed和@ObjectLink一起使用。 |
| alias和属性名 | alias是唯一匹配的key，如果缺省alias，则默认属性名为alias。 | alias和属性名都为key，优先匹配alias，匹配不到可以匹配属性名。 |
| @Provide(r) 从父组件初始化 | 禁止。 | 允许。 |
| @Provide(r)支持重载 | 默认开启，即@Provider可以重名，@Consumer向上查找最近的@Provider。 | 默认关闭，即在组件树上不允许有同名@Provide。如果需要重载，则需要配置allowOverride。 |
3、装饰器说明
基本规则
@Provider语法：
@Provider(alias?: string) varName : varType = initValue
| @Provider属性装饰器 | 说明 |
|---|---|
| 装饰器参数 | aliasName?: string，别名，缺省时默认为属性名。 |
| 支持类型 | 自定义组件中成员变量。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。支持装饰箭头函数。 |
| 从父组件初始化 | 禁止。 |
| 本地初始化 | 必须本地初始化。 |
| 观察能力 | 能力等同于@Trace。变化会同步给对应的@Consumer。 |
@Consumer语法：
@Consumer(alias?: string) varName : varType = initValue
| @Consumer属性装饰器 | 说明 |
|---|---|
| 装饰器参数 | aliasName?: string，别名，缺省时默认为属性名，向上查找最近的@Provider。 |
| 可装饰的变量 | 自定义组件中成员变量。属性的类型可以为number、string、boolean、class、Array、Date、Map、Set等类型。支持装饰箭头函数。 |
| 从父组件初始化 | 禁止。 |
| 本地初始化 | 必须本地初始化。 |
| 观察能力 | 能力等同于@Trace。变化会同步给对应的@Provider。 |
aliasName和属性名
@Provider和@Consumer可接受可选参数aliasName，如果开发者没有配置参数，则使用属性名作为默认的aliasName。注意：aliasName是用于@Provider和@Consumer进行匹配的唯一指定key。
4、变量传递
| 传递规则 | 说明 |
|---|---|
| 从父组件初始化 | @Provider和@Consumer装饰的变量仅允许本地初始化，无法从外部传入初始化。 |
| 初始化子组件 | @Provider和@Consumer装饰的变量可以初始化子组件中@Param装饰的变量。 |
5、使用限制
- @Provider和@Consumer为自定义组件的属性装饰器，仅能装饰自定义组件内的属性，不能装饰class的属性。
- @Provider和@Consumer为状态管理V2装饰器，只能在@ComponentV2中使用，不能在@Component中使用。
- @Provider和@Consumer仅支持本地初始化，不支持外部传入初始化。
6、使用场景
@Provider和@Consumer双向同步
建立双向绑定
- 自定义组件Parent和Child初始化:
- Child中@Consumer() str: string = 'world'向上查找，查找到Parent中声明的@Provider() str: string = 'hello'。
- @Consumer() str: string = 'world'初始化为其查找到的@Provider的值，即‘hello’。
- 两者建立双向同步关系。
- 点击Parent中的Button，改变@Provider装饰的str，通知其对应的@Consumer，对应UI刷新。
- 点击Child中Button，改变@Consumer装饰的str，通知其对应的@Provider，对应UI刷新。
@Entry
@ComponentV2
struct Parent {
@Provider() str: string = 'hello';
build() {
Column() {
Button(this.str)
.onClick(() => {
this.str += '0';
})
Child()
}
}
}
@ComponentV2
struct Child {
@Consumer() str: string = 'world';
build() {
Column() {
Button(this.str)
.onClick(() => {
this.str += '0';
})
}
}
}未建立双向绑定
下面的例子中，@Provider和@Consumer由于aliasName值不同，无法建立双向同步关系。
- 自定义组件Parent和Child初始化:
- Child中@Consumer() str: string = 'world'向上查找，未查找到其数据提供方@Provider。
- @Consumer() str: string = 'world'使用其本地默认值为‘world’。
- 两者未建立双向同步关系。
- 点击Parent中的Button，改变@Provider装饰的str1，仅刷新@Provider关联的Button组件。
- 点击Child中Button，改变@Consumer装饰的str，仅刷新@Consumer关联的Button组件。
@Entry
@ComponentV2
struct Parent {
@Provider() str1: string = 'hello';
build() {
Column() {
Button(this.str1)
.onClick(() => {
this.str1 += '0';
})
Child()
}
}
}
@ComponentV2
struct Child {
@Consumer() str: string = 'world';
build() {
Column() {
Button(this.str)
.onClick(() => {
this.str += '0';
})
}
}
}1.8 @Monitor装饰器：状态变量修改监听
为了增强状态管理框架对状态变量变化的监听能力，开发者可以使用@Monitor装饰器对状态变量进行监听。
@Monitor提供了对V2状态变量的监听。在阅读本文档前，建议提前阅读：@ComponentV2，@ObservedV2和@Trace，@Local。
1、概述
@Monitor装饰器用于监听状态变量修改，使得状态变量具有深度监听的能力：
@Monitor装饰器支持在@ComponentV2装饰的自定义组件中使用，未被状态变量装饰器@Local、@Param、@Provider、@Consumer、@Computed装饰的变量无法被@Monitor监听到变化。
@Monitor装饰器支持在类中与@ObservedV2、@Trace配合使用，不允许在未被@ObservedV2装饰的类中使用@Monitor装饰器。未被@Trace装饰的属性无法被@Monitor监听到变化。
当观测的属性变化时，@Monitor装饰器定义的回调方法将被调用。判断属性是否变化使用的是严格相等（===），当严格相等为false的情况下，就会触发@Monitor的回调。当在一次事件中多次改变同一个属性时，将会使用初始值和最终值进行比较以判断是否变化。
单个@Monitor装饰器能够同时监听多个属性的变化，当这些属性在一次事件中共同变化时，只会触发一次@Monitor的回调方法。
@Monitor装饰器具有深度监听的能力，能够监听嵌套类、多维数组、对象数组中指定项的变化。对于嵌套类、对象数组中成员属性变化的监听要求该类被@ObservedV2装饰且该属性被@Trace装饰。
在继承类场景中，可以在父子组件中对同一个属性分别定义@Monitor进行监听，当属性变化时，父子组件中定义的@Monitor回调均会被调用。
和@Watch装饰器类似，开发者需要自己定义回调函数，区别在于@Watch装饰器将函数名作为参数，而@Monitor直接装饰回调函数。@Monitor与@Watch的对比可以查看@Monitor与@Watch的对比。
2、装饰器说明
| @Monitor属性装饰器 | 说明 |
|---|---|
| 装饰器参数 | 字符串类型的对象属性名。可同时监听多个对象属性，每个属性以逗号隔开，例如@Monitor("prop1", "prop2")。可监听深层的属性变化，如多维数组中的某一个元素，嵌套对象或对象数组中的某一个属性。详见监听变化。 |
| 装饰对象 | @Monitor装饰成员方法。当监听的属性发生变化时，会触发该回调方法。该回调方法以IMonitor类型的变量作为参数，开发者可以从该参数中获取变化前后的相关信息。 |
3、接口说明
IMonitor类型
IMonitor类型的变量用作@Monitor装饰方法的参数。
| 属性 | 类型 | 参数 | 返回值 | 说明 |
|---|---|---|---|---|
| dirty | Array<string> | 无 | 无 | 保存发生变化的属性名。 |
| value<T> | function | path?: string | IMonitorValue<T> | 获得指定属性（path）的变化信息。当不填path时返回@Monitor监听顺序中第一个改变的属性的变化信息。 |
IMonitorValue<T>类型
IMonitorValue<T>类型保存了属性变化的信息，包括属性名、变化前值、当前值。
| 属性 | 类型 | 说明 |
|---|---|---|
| before | T | 监听属性变化之前的值。 |
| now | T | 监听属性变化之后的当前值。 |
| path | string | 监听的属性名。 |
4、监听变化
在@ComponentV2装饰的自定义组件中使用@Monitor
使用@Monitor监听的状态变量发生变化时，会触发@Monitor的回调方法。
-
@Monitor监听的变量需要被@Local、@Param、@Provider、@Consumer、@Computed装饰，未被状态变量装饰器装饰的变量在变化时无法被监听。@Monitor可以同时监听多个状态变量，这些变量名之间用","隔开。
@Entry
@ComponentV2
struct Index {
@Local message: string = "Hello World";
@Local name: string = "Tom";
@Local age: number = 24;
@Monitor("message", "name")
onStrChange(monitor: IMonitor) {
monitor.dirty.forEach((path: string) => {
console.log(`${path} changed from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`)
})
}
build() {
Column() {
Button("change string")
.onClick(() => {
this.message += "!";
this.name = "Jack";
})
}
}
}- @Monitor监听的状态变量为类对象时，仅能监听对象整体的变化。监听类属性的变化需要类属性被@Trace装饰。
class Info {
name: string;
age: number;
constructor(name: string, age: number) {
this.name = name;
this.age = age;
}
}
@Entry
@ComponentV2
struct Index {
@Local info: Info = new Info("Tom", 25);
@Monitor("info")
infoChange(monitor: IMonitor) {
console.log(`info change`);
}
@Monitor("info.name")
infoPropertyChange(monitor: IMonitor) {
console.log(`info name change`);
}
build() {
Column() {
Text(`name: ${this.info.name}, age: ${this.info.age}`)
Button("change info")
.onClick(() => {
this.info = new Info("Lucy", 18); // 能够监听到
})
Button("change info.name")
.onClick(() => {
this.info.name = "Jack"; // 监听不到
})
}
}
}5、限制条件
使用@Monitor需要注意如下限制条件：
- 不建议在一个类中对同一个属性进行多次@Monitor的监听。当一个类中存在对一个属性的多次监听时，只有最后一个定义的监听方法会生效。
- @Monitor的参数需要为监听属性名的字符串，仅可以使用字符串字面量、const常量、enum枚举值作为参数。如果使用变量作为参数，仅会监听@Monitor初始化时，变量值所对应的属性。当更改变量时，@Monitor无法实时改变监听的属性，即@Monitor监听的目标属性从初始化时便已经确定，无法动态更改。不建议开发者使用变量作为@Monitor的参数进行初始化。
- 建议开发者避免在@Monitor中再次更改被监听的属性，这会导致无限循环。
@Monitor与@Watch对比
@Monitor与@Watch的用法、功能对比如下：
| @Watch | @Monitor | |
|---|---|---|
| 参数 | 回调方法名。 | 监听状态变量名、属性名。 |
| 监听目标数 | 只能监听单个状态变量。 | 能同时监听多个状态变量。 |
| 监听能力 | 跟随状态变量观察能力（一层）。 | 跟随状态变量观察能力（深层）。 |
| 能否获取变化前的值 | 不能获取变化前的值。 | 能获取变化前的值。 |
| 监听条件 | 监听对象为状态变量。 | 监听对象为状态变量或为@Trace装饰的类成员属性。 |
| 使用限制 | 仅能在@Component装饰的自定义组件中使用。 | 能在@ComponentV2装饰的自定义组件中使用，也能在@ObservedV2装饰的类中使用。 |
1.9 @Computed装饰器：计算属性
@Computed装饰器：计算属性，在被计算的值变化的时候，只会计算一次。主要应用于解决UI多次重用该属性从而重复计算导致的性能问题。
状态变量的变化可以触发其关联@Computed的重新计算。在阅读本文档前，建议提前阅读：@ComponentV2，@ObservedV2和@Trace，@Local。
1、概述
@Computed为方法装饰器，装饰getter方法。@Computed会检测被计算的属性变化，当被计算的属性变化时，@Computed只会被求解一次。
对于复杂的计算，@Computed会有性能收益。
2、装饰器说明
@Computed语法：
@Computed
get varName(): T {
return value;
}| @Computed方法装饰器 | 说明 |
|---|---|
| 支持类型 | getter访问器。 |
| 从父组件初始化 | 禁止。 |
| 可初始化子组件 | @Param |
| 被执行的时机 | @ComponentV2被初始化时，计算属性会被触发计算。当被计算的值改变的时候，计算属性也会发生计算。 |
| 是否允许赋值 | @Computed装饰的属性是只读的，不允许赋值，详情见使用限制。 |
3、使用限制
@Computed为方法装饰器，仅能装饰getter方法。
在@Computed装饰的getter方法中，不能改变参与计算的属性。
@Computed不能和双向绑定!!连用，@Computed装饰的是getter访问器，不会被子组件同步，也不能被赋值。开发者自己实现的计算属性的setter不生效，且产生编译时报错。
@Computed为状态管理V2提供的能力，只能在@ComponentV2和@ObservedV2中使用。
多个@Computed一起使用时，警惕循环求解。
1.10 @Type装饰器：标记类属性的类型
为了实现序列化类时不丢失属性的复杂类型，开发者可以使用@Type装饰器装饰类属性。
@Type的目的是标记类属性，配合PersistenceV2使用，防止序列化时类丢失。在阅读本文档前，建议提前阅读：PersistenceV2。
1、概述
@Type标记类属性，使得类属性序列化时不丢失类型信息，便于类的反序列化。
2、装饰器说明
| @Type装饰器 | 说明 |
|---|---|
| 装饰器参数 | type：类型。 |
| 可装饰的类型 | Object class以及Array、Date、Map、Set等内嵌类型。 |
3、使用限制
- 只能用在@ObservedV2装饰的类中，不能用在自定义组件中。
- 不支持collections.Set、collections.Map等类型。
- 不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。
- 不支持简单类型，如string、number、boolean等。
2 其他状态管理
- AppStorageV2: 应用全局UI状态存储
- PersistenceV2: 持久化储存UI状态
- !!语法：双向绑定
2.1 AppStorageV2: 应用全局UI状态存储
AppStorageV2是提供状态变量在应用级全局共享的能力，开发者可以通过connect绑定同一个key，进行跨ability的数据共享。
1、概述
AppStorageV2是在应用UI启动时会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorageV2将在应用运行过程保留其数据。数据通过唯一的键字符串值访问。
AppStorageV2可以和UI组件同步，且可以在应用业务逻辑中被访问。
AppStorageV2支持应用的主线程内多个UIAbility实例间的状态共享。
2、使用说明
connect：创建或获取储存的数据
static connect<T extends object>(
type: TypeConstructorWithArgs<T>,
keyOrDefaultCreator?: string | StorageDefaultCreator<T>,
defaultCreator?: StorageDefaultCreator<T>
): T | undefined;| connect | 说明 |
|---|---|
| 参数 | type：指定的类型，若未指定key，则使用type的name作为key； keyOrDefaultCreater：指定的key，或者是默认数据的构造器； defaultCreator：默认数据的构造器。 |
| 返回值 | 创建或获取数据成功时，返回数据；否则返回undefined。 |
说明
1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器（第二个参数非法也使用第三个参数作为默认构造器）。
2、确保数据已经存储在AppStorageV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常。
3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配。
4、key建议使用有意义的值，可由字母、数字、下划线组成，长度不超过255，使用非法字符或空字符的行为是未定义的。
5、关联@Observed对象时，由于该类型的name属性未定义，需要指定key或者自定义name属性。
remove：删除指定key的储存数据
static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;| remove | 说明 |
|---|---|
| 参数 | keyOrType：需要删除的key；如果指定的是type类型，删除的key为type的name。 |
| 返回值 | 无。 |
说明
删除AppStorageV2中不存在的key会报警告。
keys：返回所有AppStorageV2中的key
static keys(): Array<string>;| eys | 说明 |
|---|---|
| 参数 | 无。 |
| 返回值 | 所有AppStorageV2中的key。 |
3、使用限制
- 需要配合UI使用（UI线程），不能在其他线程使用，如不支持@Sendable。
- 不支持collections.Set、collections.Map等类型。
- 不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。
2.2 PersistenceV2: 持久化储存UI状态
PersistenceV2是应用程序中的可选单例对象。此对象的作用是持久化存储UI相关的数据，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同。
PersistenceV2提供状态变量持久化能力，开发者可以通过connect绑定同一个key，在状态变量变换和应用冷启动时，实现持久化能力。
1、概述
PersistenceV2是在应用UI启动时会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。数据通过唯一的键字符串值访问。不同于AppStorageV2，PersistenceV2还将最新数据储存在设备磁盘上（持久化）。这意味着，应用退出再次启动后，依然能保存选定的结果。
对于与PersistenceV2关联的@ObservedV2对象，该对象的@Trace属性的变化，会触发整个关联对象的自动持久化；非@Trace属性的变化则不会，如有必要，可调用PersistenceV2 API手动持久化。
PersistenceV2可以和UI组件同步，且可以在应用业务逻辑中被访问。
PersistenceV2支持应用的主线程内多个UIAbility实例间的状态共享。
2、使用说明
connect：创建或获取储存的数据
static connect<T extends object>(
type: TypeConstructorWithArgs<T>,
keyOrDefaultCreator?: string | StorageDefaultCreator<T>,
defaultCreator?: StorageDefaultCreator<T>
): T | undefined;| connect | 说明 |
|---|---|
| 参数 | type：指定的类型，若未指定key，则使用type的name作为key； keyOrDefaultCreater：指定的key，或者是默认数据的构造器； defaultCreator：默认数据的构造器。 |
| 返回值 | 创建或获取数据成功时，返回数据；否则返回undefined。 |
说明
1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器（第二个参数非法也使用第三个参数作为默认构造器）。
2、确保数据已经存储在PersistenceV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常。
3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配。
4、key建议使用有意义的值，可由字母、数字、下划线组成，长度不超过255，使用非法字符或空字符的行为是未定义的。
5、关联@Observed对象时，由于该类型的name属性未定义，需要指定key或者自定义name属性。
remove：删除指定key的储存数据
static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;| remove | 说明 |
|---|---|
| 参数 | keyOrType：需要删除的key；如果指定的是type类型，删除的key为type的name。 |
| 返回值 | 无。 |
说明
删除PersistenceV2中不存在的key会报警告。
keys：返回所有PersistenceV2中的key
static keys(): Array<string>;| keys | 说明 |
|---|---|
| 参数 | 无。 |
| 返回值 | 所有PersistenceV2中的key。 |
save：手动持久化数据
static save<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;| save | 说明 |
|---|---|
| 参数 | keyOrType：需要手动持久化的key；如果指定的是type类型，key为type的name。 |
| 返回值 | 无。 |
说明
由于非@Trace的数据改变不会触发PersistenceV2的自动持久化，如有必要，可调用该接口持久化对应key的数据。
手动持久化当前内存中不处于connect状态的key是无意义的。
notifyOnError：响应序列化或反序列化失败的回调
static notifyOnError(callback: PersistenceErrorCallback | undefined): void;| notifyOnError | 说明 |
|---|---|
| 参数 | callback：当序列化或者反序列化失败时，执行该回调；若传入undefined，取消该回调。 |
| 返回值 | 无。 |
说明
将数据存入磁盘时，需要对数据进行序列化；当某个key序列化失败时，错误是不可预知的；可调用该接口捕获异常。
3、使用限制
- 需要配合UI使用（UI线程），不能在其他线程使用，如不支持@Sendable。
- 不支持collections.Set、collections.Map等类型。
- 不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。
- 单个key支持数据大小约8k，过大会导致持久化失败。
- 持久化的数据必须是class对象，不能是容器（如Array、Set、Map），不能是buildin的构造对象（如Date、Number）。
- 不支持循环引用的对象。
- 只有@Trace的数据改变会触发自动持久化，如V1状态变量、@Observed对象、普通数据的改变不会触发持久化。
- 不宜大量持久化数据，可能会导致页面卡顿。
2.3 !!语法：双向绑定
在状态管理V1中使用$$用于内置组件双向绑定。
在状态管理V2中，提供了归一处理，提供!!语法糖作为统一处理双向绑定语法。
说明
!!语法从API version 12开始支持。
1、概述
!!双向绑定语法，是一个语法糖方便开发者实现数据双向绑定，用于初始化子组件的@Param和@Event。其中@Event方法名需要声明为“$”+ @Param属性名，详见使用场景。
- 如果父组件使用了!!双向绑定语法，则表明父组件的变化会同步给子组件，子组件的变化也会同步给父组件。
- 如果父组件没有使用!!，则父组件发生的变化是单向的。
2、使用限制
!!双向绑定语法不支持多层父子组件传递。
3、使用场景
自定义组件间双向绑定
- Index中构造Star子组件，双向绑定父子组件中的value，初始化子组件的@Param value和@Event $value。
-
双向绑定语法糖可视为：
Star({ value: this.value, $value: (val: number) => { this.value = val }})- 点击改变Index中的Button，改变value，父组件Index和子组件Star中Text更新。
- 点击改变子组件Star中的Button，调用this.$value(10)，父组件Index和子组件Star中Text更新。
@Entry
@ComponentV2
struct Index {
@Local value: number = 0;
build() {
Column() {
Text(`${this.value}`)
Button(`change value`).onClick(() => {
this.value++;
})
Star({ value: this.value!! })
}
}
}
@ComponentV2
struct Star {
@Param value: number = 0;
@Event $value: (val: number) => void = (val: number) => {};
build() {
Column() {
Text(`${this.value}`)
Button(`change value `).onClick(() => {
this.$value(10);
})
}
}
}
