目录
1.4 @Provide装饰器和@Consume装饰器：与后代组件双向同步
1.5 @Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化
2.3 PersistentStorage：持久化存储UI状态
1 管理组件拥有的状态
1.1 @State装饰器：组件内状态
1、概述
@State装饰的变量，与声明式范式中的其他被装饰变量一样，是私有的，只能从组件内部访问，在声明时必须指定其类型和本地初始化。初始化也可选择使用命名参数机制从父组件完成初始化。
@State装饰的变量拥有以下特点：
@State装饰的变量与子组件中的@Prop装饰变量之间建立单向数据同步,与@Link、@ObjectLink装饰变量之间建立双向数据同步。
@State装饰的变量生命周期与其所属自定义组件的生命周期相同。
2、装饰器使用规则说明
| @State变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无 |
| 同步类型 | 不与父组件中任何类型的变量同步。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 支持Date类型。 支持undefined和null类型。 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。 类型必须被指定。 支持类型的场景请参考观察变化。 不支持any。 API11及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见@State支持联合类型实例。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@State a : string | undefined = undefined是推荐的，不推荐@State a: string = undefined。 |
| 被装饰变量的初始值 | 必须本地初始化。 |
3、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父组件初始化 | 可选，从父组件初始化或者本地初始化。如果从父组件初始化，并且从父组件传入的值非undefined，将会覆盖本地初始化；如果从父组件传入的值为undefined，则初值为@State装饰变量自身的初值。 支持父组件中常规变量（常规变量对@State赋值，只是数值的初始化，常规变量的变化不会触发UI刷新，只有状态变量才能触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量，初始化子组件的@State。 |
| 用于初始化子组件 | @State装饰的变量支持初始化子组件的常规变量、@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 不支持，只能在组件内访问。 |
图1 初始化规则图示
1.2 @Prop装饰器：父子单向同步
1、概述
@Prop装饰的变量和父组件建立单向的同步关系：
@Prop变量允许在本地修改，但修改后的变化不会同步回父组件。
当数据源更改时，@Prop装饰的变量都会更新，并且会覆盖本地所有更改。因此，数值的同步是父组件到子组件（所属组件)，子组件数值的变化不会同步到父组件。
2、限制条件
- @Prop装饰变量时会进行深拷贝，在拷贝的过程中除了基本类型、Map、Set、Date、Array外，都会丢失类型。例如PixelMap等通过NAPI提供的复杂类型，由于有部分实现在Native侧，因此无法在ArkTS侧通过深拷贝获得完整的数据。
3、装饰器使用规则说明
| @Prop变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 同步类型 | 单向同步：对父组件状态变量值的修改，将同步给子组件@Prop装饰的变量，子组件@Prop变量的修改不会同步到父组件的状态变量上。嵌套类型的场景请参考观察变化。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 不支持any，支持undefined和null。 支持Date类型。 API11及以上支持Map、Set类型。 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。 必须指定类型。 @Prop和数据源类型需要相同，有以下三种情况： - @Prop装饰的变量和@State以及其他装饰器同步时双方的类型必须相同，示例请参考父组件@State到子组件@Prop简单数据类型同步。 - @Prop装饰的变量和@State以及其他装饰器装饰的数组的项同步时 ，@Prop的类型需要和@State装饰的数组的数组项相同，比如@Prop : T和@State : Array<T>，示例请参考父组件@State数组中的项到子组件@Prop简单数据类型同步。 - 当父组件状态变量为Object或者class时，@Prop装饰的变量和父组件状态变量的属性类型相同，示例请参考从父组件中的@State类对象属性到@Prop简单类型的同步。 支持类型的场景请参考观察变化。 API11及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见Prop支持联合类型实例。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@Prop a : string | undefined = undefined是推荐的，不推荐@Prop a: string = undefined。 |
| 嵌套传递层数 | 在组件复用场景，建议@Prop深度嵌套数据不要超过5层，嵌套太多会导致深拷贝占用的空间过大以及GarbageCollection(垃圾回收)，引起性能问题，此时更建议使用@ObjectLink。 |
| 被装饰变量的初始值 | 允许本地初始化。如果在API 11中和@Require结合使用，则必须父组件构造传参。 |
4、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父组件初始化 | 如果本地有初始化，则是可选的，初始化行为和@State保持一致。没有的话，则必选，支持父组件中的常规变量（常规变量对@Prop赋值，只是数值的初始化，常规变量的变化不会触发UI刷新。只有状态变量才能触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp去初始化子组件中的@Prop变量。 |
| 用于初始化子组件 | @Prop支持去初始化子组件中的常规变量、@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | @Prop装饰的变量是私有的，只能在组件内访问。 |
图1 初始化规则图示
1.3 @Link装饰器：父子双向同步
1、概述
@Link装饰的变量与其父组件中的数据源共享相同的值。
2、装饰器使用规则说明
| @Link变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 同步类型 | 双向同步。 父组件中的状态变量可以与子组件@Link建立双向同步，当其中一方改变时，另外一方能够感知到变化。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 支持Date类型。 API11及以上支持Map、Set类型。 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。 类型必须被指定，且和双向绑定状态变量的类型相同。 支持类型的场景请参考观察变化。 不支持any。 API11及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见Link支持联合类型实例。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@Link a : string | undefined。 |
| 被装饰变量的初始值 | 无，禁止本地初始化。 |
3、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父组件初始化和更新 | 必选。与父组件@State, @StorageLink和@Link 建立双向绑定。允许父组件中@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰变量初始化子组件@Link。 从API version 9开始，@Link子组件从父组件初始化@State的语法为Comp({ aLink: this.aState })。同样Comp({aLink: $aState})也支持。 |
| 用于初始化子组件 | 允许，可用于初始化常规变量、@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 私有，只能在所属组件内访问。 |
图1 初始化规则图示
1.4 @Provide装饰器和@Consume装饰器：与后代组件双向同步
1、概述
@Provide/@Consume装饰的状态变量有以下特性：
@Provide装饰的状态变量自动对其所有后代组件可用，即该变量被“provide”给他的后代组件。由此可见，@Provide的方便之处在于，开发者不需要多次在组件之间传递变量。
后代通过使用@Consume去获取@Provide提供的变量，建立在@Provide和@Consume之间的双向数据同步，与@State/@Link不同的是，前者可以在多层级的父子组件之间传递。
@Provide和@Consume可以通过相同的变量名或者相同的变量别名绑定，建议类型相同，否则会发生类型隐式转换，从而导致应用行为异常。
// 通过相同的变量名绑定
@Provide age: number = 0;
@Consume age: number;
// 通过相同的变量别名绑定
@Provide('a') id: number = 0;
@Consume('a') age: number;@Provide和@Consume通过相同的变量名或者相同的变量别名绑定时，@Provide装饰的变量和@Consume装饰的变量是一对多的关系。不允许在同一个自定义组件内，包括其子组件中声明多个同名或者同别名的@Provide装饰的变量，@Provide的属性名或别名需要唯一且确定，如果声明多个同名或者同别名的@Provide装饰的变量，会发生运行时报错。
2、装饰器说明
@State的规则同样适用于@Provide，差异为@Provide还作为多层后代的同步源。
| @Provide变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 别名：常量字符串，可选。 如果指定了别名，则通过别名来绑定变量；如果未指定别名，则通过变量名绑定变量。 |
| 同步类型 | 双向同步。 从@Provide变量到所有@Consume变量以及相反的方向的数据同步。双向同步的操作与@State和@Link的组合相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 支持Date类型。 API11及以上支持Map、Set类型。 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。 必须指定类型。 @Provide变量的@Consume变量的类型必须相同。 支持类型的场景请参考观察变化。 不支持any。 API11及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见@Provide_and_Consume支持联合类型实例。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@Provide a : string | undefined = undefined是推荐的，不推荐@Provide a: string = undefined。 |
| 被装饰变量的初始值 | 必须指定。 |
| 支持allowOverride参数 | 允许重写，只要声明了allowOverride，则别名和属性名都可以被Override。示例见@Provide支持allowOverride参数。 |
| @Consume变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 别名：常量字符串，可选。 如果提供了别名，则必须有@Provide的变量和其有相同的别名才可以匹配成功；否则，则需要变量名相同才能匹配成功。 |
| 同步类型 | 双向：从@Provide变量（具体请参见@Provide）到所有@Consume变量，以及相反的方向。双向同步操作与@State和@Link的组合相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 支持Date类型。 支持ArkUI框架定义的联合类型Length、ResourceStr、ResourceColor类型。必须指定类型。 @Provide变量和@Consume变量的类型必须相同。 @Consume装饰的变量，在其父组件或者祖先组件上，必须有对应的属性和别名的@Provide装饰的变量。 支持类型的场景请参考观察变化。 不支持any。 API11及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见@Provide_and_Consume支持联合类型实例。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@Consume a : string | undefined。 |
| 被装饰变量的初始值 | 无，禁止本地初始化。 |
3、变量的传递/访问规则说明
| @Provide传递/访问 | 说明 |
|---|---|
| 从父组件初始化和更新 | 可选，允许父组件中常规变量（常规变量对@Provide赋值，只是数值的初始化，常规变量的变化不会触发UI刷新，只有状态变量才能触发UI刷新）、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量装饰变量初始化子组件@Provide。 |
| 用于初始化子组件 | 允许，可用于初始化@State、@Link、@Prop、@Provide。 |
| 和父组件同步 | 否。 |
| 和后代组件同步 | 和@Consume双向同步。 |
| 是否支持组件外访问 | 私有，仅可以在所属组件内访问。 |
图1 @Provide初始化规则图示
| @Consume传递/访问 | 说明 |
|---|---|
| 从父组件初始化和更新 | 禁止。通过相同的变量名和alias（别名）从@Provide初始化。 |
| 用于初始化子组件 | 允许，可用于初始化@State、@Link、@Prop、@Provide。 |
| 和祖先组件同步 | 和@Provide双向同步。 |
| 是否支持组件外访问 | 私有，仅可以在所属组件内访问 |
图2 @Consume初始化规则图示
1.5 @Observed装饰器和@ObjectLink装饰器：嵌套类对象属性变化
1、概述
@ObjectLink和@Observed类装饰器用于在涉及嵌套对象或数组的场景中进行双向数据同步：
使用new创建被@Observed装饰的类，可以被观察到属性的变化。
子组件中@ObjectLink装饰器装饰的状态变量用于接收@Observed装饰的类的实例，和父组件中对应的状态变量建立双向数据绑定。这个实例可以是数组中的被@Observed装饰的项，或者是class object中的属性，这个属性同样也需要被@Observed装饰。
@Observed用于嵌套类场景中，观察对象类属性变化，要配合自定义组件使用（示例详见嵌套对象），如果要做数据双/单向同步，需要搭配@ObjectLink或者@Prop使用（示例详见@Prop与@ObjectLink的差异）。
2、装饰器说明
| @Observed类装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 类装饰器 | 装饰class。需要放在class的定义前，使用new创建类对象。 |
| @ObjectLink变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无。 |
| 允许装饰的变量类型 | 必须为被@Observed装饰的class实例，必须指定类型。 @ObjectLink不支持简单类型，如果开发者需要使用简单类型，可以使用@Prop。 支持继承Date、Array的class实例，API11及以上支持继承Map、Set的class实例。示例见观察变化。 API11及以上支持@Observed装饰类和undefined或null组成的联合类型，比如ClassA | ClassB, ClassA | undefined 或者 ClassA | null, 示例见@ObjectLink支持联合类型。 @ObjectLink的属性是可以改变的，但是变量的分配是不允许的，也就是说这个装饰器装饰变量是只读的，不能被改变。 |
| 被装饰变量的初始值 | 不允许。 |
@ObjectLink装饰的数据为可读示例。
// 允许@ObjectLink装饰的数据属性赋值
this.objLink.a= ...
// 不允许@ObjectLink装饰的数据自身赋值
this.objLink= ...说明
@ObjectLink装饰的变量不能被赋值，如果要使用赋值操作，请使用@Prop。
@Prop装饰的变量和数据源的关系是是单向同步，@Prop装饰的变量在本地拷贝了数据源，所以它允许本地更改，如果父组件中的数据源有更新，@Prop装饰的变量本地的修改将被覆盖。
@ObjectLink装饰的变量和数据源的关系是双向同步，@ObjectLink装饰的变量相当于指向数据源的指针。禁止对@ObjectLink装饰的变量赋值，如果一旦发生@ObjectLink装饰的变量的赋值，则同步链将被打断。因为@ObjectLink装饰的变量通过数据源（Object）引用来初始化。对于实现双向数据同步的@ObjectLink，赋值相当于更新父组件中的数组项或者class的属性，TypeScript/JavaScript不能实现，会发生运行时报错。
3、变量的传递/访问规则说明
| @ObjectLink传递/访问 | 说明 |
|---|---|
| 从父组件初始化 | 必须指定。 初始化@ObjectLink装饰的变量必须同时满足以下场景： - 类型必须是@Observed装饰的class。 - 初始化的数值需要是数组项，或者class的属性。 - 同步源的class或者数组必须是@State，@Link，@Provide，@Consume或者@ObjectLink装饰的数据。 |
| 与源对象同步 | 双向。 |
| 可以初始化子组件 | 允许，可用于初始化常规变量、@State、@Link、@Prop、@Provide |
图1 初始化规则图示
2 管理应用拥有的状态
2.1 LocalStorage：页面级UI状态存储
LocalStorage是页面级的UI状态存储，通过@Entry装饰器接收的参数可以在页面内共享同一个LocalStorage实例。LocalStorage支持UIAbility实例内多个页面间状态共享。
1、概述
LocalStorage是ArkTS为构建页面级别状态变量提供存储的内存内的“数据库”。
应用程序可以创建多个LocalStorage实例，LocalStorage实例可以在页面内共享，也可以通过getShared接口，实现跨页面、UIAbility实例内共享。
组件树的根节点，即被@Entry装饰的@Component，可以被分配一个LocalStorage实例，此组件的所有子组件实例将自动获得对该LocalStorage实例的访问权限。
@Component装饰的组件既可以自动继承来自父组件的LocalStorage实例，也可以传入指定的LocalStorage的实例，详见：自定义组件接收LocalStorage实例。
LocalStorage中的所有属性都是可变的。
应用程序决定LocalStorage对象的生命周期。当应用释放最后一个指向LocalStorage的引用时，比如销毁最后一个自定义组件，LocalStorage将被JS Engine垃圾回收。
LocalStorage根据与@Component装饰的组件的同步类型不同，提供了两个装饰器：
@LocalStorageProp：@LocalStorageProp装饰的变量与LocalStorage中给定属性建立单向同步关系。
@LocalStorageLink：@LocalStorageLink装饰的变量与LocalStorage中给定属性建立双向同步关系。
@LocalStorageProp
在上文中已经提到，如果要建立LocalStorage和自定义组件的联系，需要使用@LocalStorageProp和@LocalStorageLink装饰器。使用@LocalStorageProp(key)/@LocalStorageLink(key)装饰组件内的变量，key标识了LocalStorage的属性。
当自定义组件初始化的时候，@LocalStorageProp(key)/@LocalStorageLink(key)装饰的变量会通过给定的key，绑定LocalStorage对应的属性，完成初始化。本地初始化是必要的，因为无法保证LocalStorage一定存在给定的key（这取决于应用逻辑是否在组件初始化之前在LocalStorage实例中存入对应的属性）。
@LocalStorageProp(key)是和LocalStorage中key对应的属性建立单向数据同步，ArkUI框架支持修改@LocalStorageProp(key)在本地的值，但是对本地值的修改不会同步回LocalStorage中。相反，如果LocalStorage中key对应的属性值发生改变，例如通过set接口对LocalStorage中的值进行修改，改变会同步给@LocalStorageProp(key)，并覆盖掉本地的值。
1、装饰器使用规则说明
| @LocalStorageProp变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 API12及以上支持Map、Set、Date类型。嵌套类型的场景请参考观察变化和行为表现。 类型必须被指定，建议和LocalStorage中对应属性类型相同，否则会发生类型隐式转换，从而导致应用行为异常。 不支持any，API12及以上支持undefined和null类型。 API12及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见LocalStorage支持联合类型。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@LocalStorageProp("AA") a: number | null = null是推荐的，不推荐@LocalStorageProp("AA") a: number = null。 |
| 同步类型 | 单向同步：从LocalStorage的对应属性到组件的状态变量。组件本地的修改是允许的，但是LocalStorage中给定的属性一旦发生变化，将覆盖本地的修改。 |
| 被装饰变量的初始值 | 必须指定，如果LocalStorage实例中不存在属性，则用该初始值初始化该属性，并存入LocalStorage中。 |
2、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父节点初始化和更新 | 禁止，@LocalStorageProp不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
| 初始化子节点 | 支持，可用于初始化@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 否。 |
图1 @LocalStorageProp初始化规则图示
@LocalStorageLink
@LocalStorageLink(key)是和LocalStorage中key对应的属性建立双向数据同步：
-
本地修改发生，该修改会被写回LocalStorage中。
-
LocalStorage中的修改发生后，该修改会被同步到所有绑定LocalStorage对应key的属性上，包括单向（@LocalStorageProp和通过prop创建的单向绑定变量）、双向（@LocalStorageLink和通过link创建的双向绑定变量）变量。
1、装饰器使用规则说明
| @LocalStorageLink变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 API12及以上支持Map、Set、Date类型。嵌套类型的场景请参考观察变化和行为表现。 类型必须被指定，建议和LocalStorage中对应属性类型相同，否则会发生类型隐式转换，从而导致应用行为异常。 不支持any，API12及以上支持undefined和null类型。 API12及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见LocalStorage支持联合类型。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@LocalStorageLink("AA") a: number | null = null是推荐的，不推荐@LocalStorageLink("AA") a: number = null。 |
| 同步类型 | 双向同步：从LocalStorage的对应属性到自定义组件，从自定义组件到LocalStorage对应属性。 |
| 被装饰变量的初始值 | 必须指定，如果LocalStorage实例中不存在属性，则用该初始值初始化该属性，并存入LocalStorage中。 |
2、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父节点初始化和更新 | 禁止，@LocalStorageLink不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
| 初始化子节点 | 支持，可用于初始化@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 否。 |
图2 @LocalStorageLink初始化规则图示
2.2 AppStorage：应用全局的UI状态存储
AppStorage是应用全局的UI状态存储，是和应用的进程绑定的，由UI框架在应用程序启动时创建，为应用程序UI状态属性提供中央存储。
和AppStorage不同的是，LocalStorage是页面级的，通常应用于页面内的数据共享。而AppStorage是应用级的全局状态共享，还相当于整个应用的“中枢”，持久化数据PersistentStorage和环境变量Environment都是通过AppStorage中转，才可以和UI交互。
1、概述
AppStorage是在应用启动的时候会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorage将在应用运行过程保留其属性。属性通过唯一的键字符串值访问。
AppStorage可以和UI组件同步，且可以在应用业务逻辑中被访问。
AppStorage支持应用的主线程内多个UIAbility实例间的状态共享。
AppStorage中的属性可以被双向同步，数据可以是存在于本地或远程设备上，并具有不同的功能，比如数据持久化（详见PersistentStorage）。这些数据是通过业务逻辑中实现，与UI解耦，如果希望这些数据在UI中使用，需要用到@StorageProp和@StorageLink。
@StorageProp
在上文中已经提到，如果要建立AppStorage和自定义组件的联系，需要使用@StorageProp和@StorageLink装饰器。使用@StorageProp(key)/@StorageLink(key)装饰组件内的变量，key标识了AppStorage的属性。
当自定义组件初始化的时候，会使用AppStorage中对应key的属性值将@StorageProp(key)/@StorageLink(key)装饰的变量初始化。由于应用逻辑的差异，无法确认是否在组件初始化之前向AppStorage实例中存入了对应的属性，所以AppStorage不一定存在key对应的属性，因此@StorageProp(key)/@StorageLink(key)装饰的变量进行本地初始化是必要的。
@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步，允许本地改变，但是对于@StorageProp，本地的修改永远不会同步回AppStorage中，相反，如果AppStorage给定key的属性发生改变，改变会被同步给@StorageProp，并覆盖掉本地的修改。
1、装饰器使用规则说明
| @StorageProp变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 API12及以上支持Map、Set、Date类型。嵌套类型的场景请参考观察变化和行为表现。 类型必须被指定，建议和AppStorage中对应属性类型相同，否则会发生类型隐式转换，从而导致应用行为异常。 不支持any，API12及以上支持undefined和null类型。 API12及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见AppStorage支持联合类型。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@StorageProp("AA") a: number | null = null是推荐的，不推荐@StorageProp("AA") a: number = null。 |
| 同步类型 | 单向同步：从AppStorage的对应属性到组件的状态变量。 组件本地的修改是允许的，但是AppStorage中给定的属性一旦发生变化，将覆盖本地的修改。 |
| 被装饰变量的初始值 | 必须指定，如果AppStorage实例中不存在属性，则用该初始值初始化该属性，并存入AppStorage中。 |
2、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父节点初始化和更新 | 禁止，@StorageProp不支持从父节点初始化，只能AppStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
| 初始化子节点 | 支持，可用于初始化@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 否。 |
图1 @StorageProp初始化规则图示
@StorageLink
@StorageLink(key)是和AppStorage中key对应的属性建立双向数据同步：
-
本地修改发生，该修改会被写回AppStorage中。
-
AppStorage中的修改发生后，该修改会被同步到所有绑定AppStorage对应key的属性上，包括单向（@StorageProp和通过Prop创建的单向绑定变量）、双向（@StorageLink和通过Link创建的双向绑定变量）变量和其他实例（比如PersistentStorage）。
1、装饰器使用规则说明
| @StorageLink变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 API12及以上支持Map、Set、Date类型。嵌套类型的场景请参考观察变化和行为表现。 类型必须被指定，建议和AppStorage中对应属性类型相同，否则会发生类型隐式转换，从而导致应用行为异常。 不支持any，API12及以上支持undefined和null类型。 API12及以上支持上述支持类型的联合类型，比如string | number, string | undefined 或者 ClassA | null，示例见AppStorage支持联合类型。 注意 当使用undefined和null的时候，建议显式指定类型，遵循TypeScript类型校验，比如：@StorageLink("AA") a: number | null = null是推荐的，不推荐@StorageLink("AA") a: number = null。 |
| 同步类型 | 双向同步：从AppStorage的对应属性到自定义组件，从自定义组件到AppStorage对应属性。 |
| 被装饰变量的初始值 | 必须指定，如果AppStorage实例中不存在属性，则用该初始值初始化该属性，并存入AppStorage中。 |
2、变量的传递/访问规则说明
| 传递/访问 | 说明 |
|---|---|
| 从父节点初始化和更新 | 禁止。 |
| 初始化子节点 | 支持，可用于初始化常规变量、@State、@Link、@Prop、@Provide。 |
| 是否支持组件外访问 | 否。 |
图2 @StorageLink初始化规则图示
2.3 PersistentStorage：持久化存储UI状态
前两个小节介绍的LocalStorage和AppStorage都是运行时的内存，但是在应用退出再次启动后，依然能保存选定的结果，是应用开发中十分常见的现象，这就需要用到PersistentStorage。
PersistentStorage是应用程序中的可选单例对象。此对象的作用是持久化存储选定的AppStorage属性，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同。
PersistentStorage提供状态变量持久化的能力，但是需要注意，其持久化和读回UI的能力都需要依赖AppStorage
1、概述
PersistentStorage将选定的AppStorage属性保留在设备磁盘上。应用程序通过API，以决定哪些AppStorage属性应借助PersistentStorage持久化。UI和业务逻辑不直接访问PersistentStorage中的属性，所有属性访问都是对AppStorage的访问，AppStorage中的更改会自动同步到PersistentStorage。
PersistentStorage和AppStorage中的属性建立双向同步。应用开发通常通过AppStorage访问PersistentStorage，另外还有一些接口可以用于管理持久化属性，但是业务逻辑始终是通过AppStorage获取和设置属性的。
2、限制条件
PersistentStorage允许的类型和值有：
- number, string, boolean, enum 等简单类型。
- 可以被JSON.stringify()和JSON.parse()重构的对象，但是对象中的成员方法不支持持久化。
- API12及以上支持Map类型，可以观察到Map整体的赋值，同时可通过调用Map的接口set, clear, delete 更新Map的值。且更新的值被持久化存储。详见装饰Map类型变量。
- API12及以上支持Set类型，可以观察到Set整体的赋值，同时可通过调用Set的接口add, clear, delete 更新Set的值。且更新的值被持久化存储。详见装饰Set类型变量。
- API12及以上支持Date类型，可以观察到Date整体的赋值，同时可通过调用Date的接口setFullYear, setMonth, setDate, setHours, setMinutes, setSeconds, setMilliseconds, setTime, setUTCFullYear, setUTCMonth, setUTCDate, setUTCHours, setUTCMinutes, setUTCSeconds, setUTCMilliseconds 更新Date的属性。且更新的值被持久化存储。详见装饰Date类型变量。
- API12及以上支持undefined 和 null。
- API12及以上支持联合类型。
PersistentStorage不允许的类型和值有：
- 不支持嵌套对象（对象数组，对象的属性是对象等）。因为目前框架无法检测AppStorage中嵌套对象（包括数组）值的变化，所以无法写回到PersistentStorage中。
持久化数据是一个相对缓慢的操作，应用程序应避免以下情况：
持久化大型数据集。
持久化经常变化的变量。
PersistentStorage的持久化变量最好是小于2kb的数据，不要大量的数据持久化，因为PersistentStorage写入磁盘的操作是同步的，大量的数据本地化读写会同步在UI线程中执行，影响UI渲染性能。如果开发者需要存储大量的数据，建议使用数据库api。
PersistentStorage和UI实例相关联，持久化操作需要在UI实例初始化成功后（即loadContent传入的回调被调用时）才可以被调用，早于该时机调用会导致持久化失败。
// EntryAbility.ets
onWindowStageCreate(windowStage: window.WindowStage): void {
windowStage.loadContent('pages/Index', (err) => {
if (err.code) {
return;
}
PersistentStorage.persistProp('aProp', 47);
});
}2.4 Environment：设备环境查询
开发者如果需要应用程序运行的设备的环境参数，以此来作出不同的场景判断，比如多语言，深浅色模式等，需要用到Environment设备环境查询。
Environment是ArkUI框架在应用程序启动时创建的单例对象。它为AppStorage提供了一系列描述应用程序运行状态的属性。Environment的所有属性都是不可变的（即应用不可写入），所有的属性都是简单类型。
Environment提供了读取系统某些环境变量的能力，具体见Environment内置参数，并将其值写入AppStorage里，所以开发者需要通过AppStorage才能获取环境变量的值。
1、Environment内置参数
| 键 | 数据类型 | 描述 |
|---|---|---|
| accessibilityEnabled | boolean | 获取无障碍屏幕读取是否启用。 |
| colorMode | ColorMode | 色彩模型类型：选项为ColorMode.LIGHT: 浅色，ColorMode.DARK: 深色。 |
| fontScale | number | 字体大小比例。开发者需要配置configuration使fontScale跟随系统变化。 |
| fontWeightScale | number | 字体粗细程度。 |
| layoutDirection | LayoutDirection | 布局方向类型：包括LayoutDirection.LTR: 从左到右，LayoutDirection.RTL: 从右到左。 |
| languageCode | string | 当前系统语言值，取值必须为小写字母, 例如zh。 |
3 其他状态管理
3.1 @Watch装饰器：状态变量更改通知
@Watch应用于对状态变量的监听。如果开发者需要关注某个状态变量的值是否改变，可以使用@Watch为状态变量设置回调函数。
@Watch提供了状态变量的监听能力，@Watch仅能监听到可以观察到的变化。
1、概述
@Watch用于监听状态变量的变化，当状态变量变化时，@Watch的回调方法将被调用。@Watch在ArkUI框架内部判断数值有无更新使用的是严格相等（===），遵循严格相等规范。当在严格相等为false的情况下，就会触发@Watch的回调。
2、装饰器说明
| @Watch补充变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 必填。常量字符串，字符串需要有引号。是(string) => void自定义成员函数的方法的引用。 |
| 可装饰的自定义组件变量 | 可监听所有装饰器装饰的状态变量。不允许监听常规变量。 |
| 装饰器的顺序 | 装饰器顺序不影响实际功能，开发者可以根据自己的需要决定装饰器顺序的先后。建议@State、@Prop、@Link等装饰器在@Watch装饰器之前，以保持整体风格的一致。 |
| @Watch触发时机 | 使用@Watch来监听状态变量变化时，回调触发时间是变量真正变化、被赋值的时间。详细示例请参考使用场景中的@Watch的触发时机。 |
3、语法说明
| 类型 | 说明 |
|---|---|
| (changedPropertyName? : string) => void | 该函数是自定义组件的成员函数，changedPropertyName是被watch的属性名。 在多个状态变量绑定同一个@Watch的回调方法的时候，可以通过changedPropertyName进行不同的逻辑处理 将属性名作为字符串输入参数，不返回任何内容。 |
3.2 $$语法：内置组件双向同步
$$运算符为系统内置组件提供TS变量的引用，使得TS变量和系统内置组件的内部状态保持同步。
内部状态具体指什么取决于组件。例如，TextInput组件的text参数。
说明
$$还用于@Builder装饰器的按引用传递参数，开发者需要注意两种用法的区别。
1、使用规则
-
当前$$支持的组件：
组件 支持的参数/属性 起始API版本 Checkbox select 10 CheckboxGroup selectAll 10 DatePicker selected 10 TimePicker selected 10 MenuItem selected 10 Panel mode 10 Radio checked 10 Rating rating 10 Search value 10 SideBarContainer showSideBar 10 Slider value 10 Stepper index 10 Swiper index 10 Tabs index 10 TextArea text 10 TextInput text 10 TextPicker selected、value 10 Toggle isOn 10 AlphabetIndexer selected 10 Select selected、value 10 BindSheet isShow 10 BindContentCover isShow 10 Refresh refreshing 8 GridItem selected 10 ListItem selected 10 -
$$绑定的变量变化时，会触发UI的同步刷新。
3.3 @Track装饰器：class对象属性级更新
@Track应用于class对象的属性级更新。@Track装饰的属性变化时，只会触发该属性关联的UI更新。
在阅读本文档之前，建议开发者对状态管理基本观察能力有基本的了解。建议提前阅读：@State。
1、概述
@Track是class对象的属性装饰器。当一个class对象是状态变量时，@Track装饰的属性发生变化，只会触发该属性关联的UI更新；如果class类中使用了@Track装饰器，则未被@Track装饰器装饰的属性不能在UI中使用，如果使用，会发生运行时报错。
2、装饰器说明
| @Track变量装饰器 | 说明 |
|---|---|
| 装饰器参数 | 无 |
| 可装饰的变量 | class对象的非静态成员属性。 |
3、限制条件
如果class类中使用了@Track装饰器，那么该class类中非@Track装饰的属性不能在UI中使用，包括不能绑定在组件上、不能用于初始化子组件，错误的使用将导致运行时报错，详见在UI中使用非@Track装饰的属性发生运行时报错；可以在非UI中使用非@Track装饰的属性，如事件回调函数中、生命周期函数中等。
建议开发者不要混用包含@Track的class对象和不包含@Track的class对象，如联合类型中、类继承中等。
扫一扫
6472
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
