Bootstrap

【HarmonyOS Next】鸿蒙实用装饰器一览(一)

  装饰器现代js一个很重要(尚未成熟)的特性,TS4.9开始对装饰器的Stage 3支持,并在TS5.0中发布了装饰器规范的完整版本。ArkTSTS生态基础上做了进一步扩展,保持了TS的基本风格,同时封装了大量的装饰器来简化功能。

以下内容基于HarmonyOS Next 5.0.0(API12)。

UI组件装饰器

详细文档参考
HarmonyOS Developer文档 - 创建自定义组件

@Component装饰器

@Component装饰器仅能装饰struct关键字声明的数据结构。struct@Component装饰后具备组件化的能力。

@Entry装饰器

@Entry装饰的自定义组件将作为UI页面入口。在单个UI页面中,最多可以使用@Entry装饰一个自定义组件。

@Reusable装饰器

@Reusable装饰的自定义组件具备可复用能力。官方文档未详细说明,事实上这个装饰器在解决帧率瓶颈时非常重要且有效。

使用场景
  • 滑动场景下对同一类自定义组件的实例进行频繁的创建与销毁。
  • 反复切换条件渲染的控制分支,且控制分支中的组件子树结构比较复杂。

可复用自定义组件的缓存和复用只能发生在同一父组件下,无法在不同的父组件下复用同一自定义组件的实例。

组件状态管理装饰器

@State装饰器

@State装饰的变量,与声明式范式中的其他被装饰变量一样,是私有的,只能从组件内部访问,在声明时必须指定其类型和本地初始化。

初始化也可选择使用命名参数机制从父组件完成初始化。这一点受到争议,大部分人认为私有的变量不应该从父组件进行初始化,所以在@ComponentV2中,新增@Local进行平替。

详细文档参考
HarmonyOS Developer文档 - @State装饰器:组件内状态

@Prop装饰器

@Prop装饰的变量和父组件建立单向的同步关系。当父组件的变量发生变化时会同步到子组件,所以@Prop装饰器自然不能使用在被@Entry装饰的UI页面上;另外@Prop装饰的变量允许组件内部进行修改,个人认为这个特性是松散且不严谨的。

详细文档参考
HarmonyOS Developer文档 - @State装饰器:组件内状态

@Link装饰器

@Link装饰的变量与其父组件中对应的数据源建立双向数据绑定。同@Prop装饰器一样也只能作用在子组件上。

详细文档参考
HarmonyOS Developer文档 - @Link装饰器:父子双向同步

@Provide装饰器和@Consume装饰器

@Provide@Consume,应用于与后代组件的双向数据同步,应用于状态数据在多个层级之间传递的场景。不同于上文提到的@Link装饰器@Provide@Consume摆脱参数传递机制的束缚,实现跨层级传递。

详细文档参考
HarmonyOS Developer文档 - @Provide装饰器和@Consume装饰器:与后代组件双向同步

@Observed装饰器和@ObjectLink装饰器

@ObjectLink@Observed类装饰器用于在涉及嵌套对象数组的场景中进行双向数据同步,被@ObjectLink修饰的状态变量用于接收被@Observed装饰的类的实例,和父组件中对应的状态变量建立双向数据绑定

详细文档参考
HarmonyOS Developer文档 - @Observed装饰器和@ObjectLink装饰器:嵌套类对象属性变化

应用状态管理装饰器

@LocalStorageProp装饰器

@LocalStorageProp装饰的变量与LocalStorage中给定属性建立单向同步关系。

LocalStorage页面级UI状态存储,通过@Entry装饰器接收的参数可以在页面内共享同一个LocalStorage实例。

详细文档参考
HarmonyOS Developer文档 - @LocalStorageProp

@LocalStorageLink装饰器

@LocalStorageLink(key)是和LocalStoragekey对应的属性建立双向数据同步关系。

详细文档参考
HarmonyOS Developer文档 - @LocalStorageLink

@StorageProp装饰器

@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步关系。

AppStorage是应用全局的UI状态存储,是和应用的进程绑定的,由UI框架在应用程序启动时创建,为应用程序UI状态属性提供中央存储

详细文档参考
HarmonyOS Developer文档 - @StorageProp

@StorageLink装饰器

@StorageLink(key)是和AppStorage中key对应的属性建立双向数据同步关系。

详细文档参考
HarmonyOS Developer文档 - @StorageLink

其他状态管理装饰器

@Watch装饰器

@Watch用于监听状态变量的变化,当状态变量变化时,@Watch的回调方法将被调用。@WatchArkUI框架内部判断数值有无更新使用的是严格相等(===),遵循严格相等规范。

详细文档参考
HarmonyOS Developer文档 - @Watch装饰器:状态变量更改通知

@Track装饰器

@Track应用于class对象属性级更新@Track装饰的属性变化时,只会触发该属性关联的UI更新。而未被标记的属性不能在UI中使用,如果使用,会发生运行时报错。

详细文档参考
HarmonyOS Developer文档 - @Track装饰器:class对象属性级更新

;