数据变量相关装饰器
- @State
- @Link
- @Prop
- @Provide
- @Consume
- @Observed/@ObjectLink
- @Watch
- $$运算符
- @LocalStorageProp
- @LocalStorageLink
@State
| @State | 说明 |
|---|---|
| 装饰器参数 | 无 |
| 功能 | 装饰的变量拥有其所属组件的状态， 可以作为其子组件单向和双向同步的数据源。 当其数值改变时，会引起相关组件的渲染刷新。 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 与父组件的同步类型 | 不与父组件中任何类型的变量同步。 |
| 与子组件的同步类型 | 与子组件中的@Prop装饰变量之间建立单向数据同步，与@Link、@ObjectLink装饰变量之间建立双向数据同步 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 必须指定。 |
| 注意 | 类型必须被指定。 不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。 建议不要装饰Date类型，应用可能会产生异常行为。 不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
| 初始化 | 可选，从父组件初始化或者本地初始化。如果从父组件初始化将会覆盖本地初始化。 |
| 支持父组件中常规变量初始化 | @State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量，初始化子组件的@State。 |
| 用于初始化子组件 | @State装饰的变量支持初始化子组件的常规变量、@State、@Link、@Prop、@Provide。 |
@Link
| @Link | 说明 |
|---|---|
| 装饰器参数 | 无 |
| 功能 | 装饰的变量与其父组件中对应的数据源建立双向数据绑定，共享相同的值。 |
| 限制 | @Link装饰器不能在@Entry装饰的自定义组件中使用 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 与父组件的同步类型 | 与父组件@State, @StorageLink和@Link 建立双向绑定。 |
| 与子组件的同步类型 | 与子组件中的@Prop装饰变量之间建立单向数据同步，与@Link装饰变量之间建立双向数据同步 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 禁止本地初始化。 |
| 注意 | 类型必须被指定，且和双向绑定状态变量的类型相同。 不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。 不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
| 初始化 | 从父组件初始化。 |
| 支持父组件中常规变量初始化 | @State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰变量初始化子组件@Link。 |
| 用于初始化子组件 | 可用于初始化常规变量、@State、@Link、@Prop、@Provide。 |
@Prop
| @Prop | 说明 |
|---|---|
| 装饰器参数 | 无 |
| 功能 | 装饰的变量可以和父组件建立单向的同步关系 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 与父组件的同步类型 | 父组件状态变量值的修改，将同步给子组件@Prop装饰的变量，@Prop装饰的相关变量值将被覆盖。。 变量的修改不会同步到父组件的状态变量上 |
| 与子组件的同步类型 | 与子组件中的@Prop装饰变量之间建立单向数据同步，与@Link装饰变量之间建立双向数据同步 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | string、number、boolean、enum类型。 |
| 被装饰变量的初始值 | 允许本地初始化。 |
| 注意 | 类型必须被指定。 不支持any，不允许使用undefined和null。 在父组件中，传递给@Prop装饰的值不能为undefined或者null。 @Prop和数据源类型需要相同。 |
| 初始化 | 如果本地有初始化，则是可选的。没有的话，则必选。 |
| 支持父组件中常规变量初始化 | 常规变量、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp去初始化子组件中的@Prop变量。 |
| 用于初始化子组件 | 支持去初始化子组件中的常规变量、@State、@Link、@Prop、@Provide。 |
@Provide
| @Provide | 说明：@State的规则同样适用于@Provide，差异为@Provide还作为多层后代的同步源。 |
|---|---|
| 装饰器参数 | 别名：常量字符串，可选。 如果指定了别名，则通过别名来绑定变量； 如果未指定别名，则通过变量名绑定变量。 |
| 功能 | @Provide和@Consume配合，应用于与后代组件的双向数据同步，应用于状态数据在多个层级之间传递的场景，实现跨层级传递。 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 同步类型 | 双向同步。 从@Provide变量到所有@Consume变量以及相反的方向的数据同步。双向同步的操作与@State和@Link的组合相同。 不与父组件数据同步 只和@Consume双向同步 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 必须指定。 |
| 注意 | 类型必须被指定。@Provide变量的@Consume变量的类型必须相同。 不允许在同一个自定义组件内，包括其子组件中声明多个同名或者同别名的@Provide装饰的变量。 不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。 不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
| 初始化 | 必须本地初始化 |
| 支持父组件中常规变量更新 | 允许父组件中常规变量、@State、@Link、@Prop、@Provide、@Consume、@ObjectLink、@StorageLink、@StorageProp、@LocalStorageLink和@LocalStorageProp装饰的变量装饰变量更新绑定子组件@Provide。 |
| 用于初始化子组件 | 可用于初始化@State、@Link、@Prop、@Provide。 |
@Consume
| @Consume | 说明 |
|---|---|
| 装饰器参数 | 别名：常量字符串，可选。 如果提供了别名，则必须有@Provide的变量和其有相同的别名才可以匹配成功；否则，则需要变量名相同才能匹配成功。 |
| 功能 | @Consume装饰的变量是在后代组件中，去“消费（绑定）”祖先节点（@Provide）提供的变量。 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 同步类型 | 双向同步。 从@Provide变量到所有@Consume变量以及相反的方向的数据同步。双向同步的操作与@State和@Link的组合相同。 和@Provide双向同步。 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 禁止本地初始化。 |
| 注意 | 类型必须被指定。@Provide变量的@Consume变量的类型必须相同。 @Consume装饰的变量，在其父节点或者祖先节点上，必须有对应的属性和别名的@Provide装饰的变量。 不支持any，不支持简单类型和复杂类型的联合类型，不允许使用undefined和null。 不支持Length、ResourceStr、ResourceColor类型，Length、ResourceStr、ResourceColor为简单类型和复杂类型的联合类型。 |
| 初始化 | 禁止本地初始化 |
| 支持父组件中常规变量初始化/更新 | 禁止。通过相同的变量名和alias（别名）从@Provide初始化。 |
| 用于初始化子组件 | 可用于初始化@State、@Link、@Prop、@Provide。 |
@Provide/@Consume装饰的状态变量有以下特性：
- @Provide装饰的状态变量自动对其所有后代组件可用。
- @Provide和@Consume之间的双向数据同步，可以在多层级的父子组件之间传递。
- @Provide和@Consume可以通过相同的变量名或者相同的变量别名绑定，变量类型必须相同。
- @Provide修饰的变量和@Consume修饰的变量是一对多的关系。不允许在同一个自定义组件内，包括其子组件中声明多个同名或者同别名的@Provide装饰的变量。
@Observed
| @Observed/@ObjectLink | 说明:@ObjectLink和@Observed类装饰器用于在涉及嵌套对象或数组的场景中进行双向数据同步 |
|---|---|
| 装饰器参数 | 无 |
| @Observed | 说明 |
| 类装饰器 | 只能装饰Class，需要放在class的定义前，使用时需使用new创建类对象。 |
| 功能 | 被@Observed装饰的类，可以被观察到属性的变化. 单独使用@Observed是没有任何作用的，需要搭配@ObjectLink或者@Prop使用 |
| 注意 | 使用@Observed装饰class会改变class原始的原型链，@Observed和其他类装饰器装饰同一个class可能会带来问题。 |
| @ObjectLink | 说明 |
| 同步类型 | 不与父组件中的任何类型同步变量 |
| 允许装饰的变量类型 | 必须为被@Observed装饰的class实例，必须指定类型。不支持简单类型， |
| 被装饰变量的初始值 | 禁止指定 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 初始化 | 禁止本地初始化 |
| 特性 | @ObjectLink装饰变量是只读的，不能被改变。只能从数据源处改变 |
| 从父组件初始化 | 必须指定。 初始化@ObjectLink装饰的变量必须同时满足以下场景： 类型必须是@Observed装饰的class。 初始化的数值需要是数组项，或者class的属性。 同步源的class或者数组必须是@State，@Link，@Provide，@Consume或者@ObjectLink装饰的数据。 |
| 与源对象同步 | 同步数据源的修改 |
| 可以初始化子组件 | 可用于初始化常规变量、@State、@Link、@Prop、@Provide |
@Watch
- @Watch应用于对状态变量的监听。如果开发者需要关注某个状态变量的值是否改变，可以使用@Watch为状态变量设置回调函数。
- @Watch在ArkUI框架内部判断数值有无更新使用的是严格相等（===），遵循严格相等规范。当在严格相等为false的情况下，就会触发@Watch的回调。
| @Watch | 说明 |
|---|---|
| 装饰器参数 | 必填。常量字符串，字符串需要有引号。是(string) => void自定义成员函数的方法的引用。 |
| 可装饰的自定义组件变量 | 可监听所有装饰器装饰的状态变量。不允许监听常规变量。 |
| 装饰器的顺序 | 建议@State、@Prop、@Link等装饰器在@Watch装饰器之前。 |
| 可装饰的自定义组件变量 | 可监听所有装饰器装饰的状态变量。不允许监听常规变量。 |
| 限制 | 避免无限循环，建议不要在@Watch的回调方法里修改当前装饰的状态变量。 属性值更新函数会延迟组件的重新渲染，因此，回调函数应仅执行快速运算 不建议在@Watch函数中调用async await |
| 注意 | 在第一次初始化的时候，@Watch装饰的方法不会被调用，即认为初始化不是状态变量的改变 如果在@Watch的方法里改变了其他的状态变量，也会引起状态变更和@Watch的执行 @Watch方法在自定义组件的属性变更之后同步执行 |
@Component
struct TotalView {
@Prop @Watch('onCountUpdated') count: number;
@State total: number = 0;
// @Watch 回调
onCountUpdated(propName: string): void {
this.total += this.count;
}
build() {
Text(`Total: ${this.total}`)
}
}
$$运算符
- $$运算符为系统内置组件提供TS变量的引用，使得TS变量和系统内置组件的内部状态保持同步。
- 当前$$支持基础类型变量，以及@State、@Link和@Prop装饰的变量。
- 当前$$仅支持Refresh组件的refreshing参数。
- $$绑定的变量变化时，会触发UI的同步刷新。
// xxx.ets
@Entry
@Component
struct RefreshExample {
@State isRefreshing: boolean = false
@State counter: number = 0
build() {
Column() {
Text('Pull Down and isRefreshing: ' + this.isRefreshing)
.fontSize(30)
.margin(10)
Refresh({ refreshing: $$this.isRefreshing, offset: 120, friction: 100 }) {
Text('Pull Down and refresh: ' + this.counter)
.fontSize(30)
.margin(10)
}
.onStateChange((refreshStatus: RefreshStatus) => {
console.info('Refresh onStatueChange state is ' + refreshStatus)
})
}
}
}
@LocalStorageProp
- @LocalStorageProp装饰的变量和与LocalStorage中给定属性建立单向同步关系。
| @LocalStorageProp | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 功能 | 和LocalStorage中key对应的属性建立单向数据同步 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 必须指定。如果LocalStorage实例中不存在属性，则作为初始化默认值，并存入LocalStorage中。 |
| 注意 | 类型必须被指定，且必须和LocalStorage中对应属性相同。 不支持any，不允许使用undefined和null。 |
| 初始化 | 禁止，@LocalStorageProp不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
| 初始化子节点 | 可用于初始化@State、@Link、@Prop、@Provide。 |
| 同步类型 | 单向同步：从LocalStorage的对应属性到组件的状态变量。组件本地的修改是允许的，但是LocalStorage中给定的属性一旦发生变化，将覆盖本地的修改 |
@LocalStorageLink
- @LocalStorageLink装饰的变量和在@Component中创建与LocalStorage中给定属性建立双向同步关系。
- 本地修改发生，该修改会被写回LocalStorage中；
- LocalStorage中的修改发生后，该修改会被同步到所有绑定LocalStorage对应key的属性上，包括单向（@LocalStorageProp和通过prop创建的单向绑定变量）、双向（@LocalStorageLink和通过link创建的双向绑定变量）变量。
| @LocalStorageLink | 说明 |
|---|---|
| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 |
| 功能 | 和LocalStorage中key对应的属性建立双向数据同步 |
| 可见性 | 私有，仅所属组件可见。不支持组件外访问，只能在组件内访问。 |
| 变量生命周期 | 变量生命周期与其所属自定义组件的生命周期相同。 |
| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。 |
| 被装饰变量的初始值 | 必须指定。如果LocalStorage实例中不存在属性，则作为初始化默认值，并存入LocalStorage中。 |
| 注意 | 类型必须被指定，且必须和LocalStorage中对应属性相同。 不支持any，不允许使用undefined和null。 |
| 初始化 | 禁止，@LocalStorageProp不支持从父节点初始化，只能从LocalStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化。 |
| 初始化子节点 | 可用于初始化@State、@Link、@Prop、@Provide。 |
| 同步类型 | 双向同步：从LocalStorage的对应属性到自定义组件，从自定义组件到LocalStorage对应属性。 |
网友评论