【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对象属性级更新

相关推荐
ywf121528 分钟前
前端的dist包放到后端springboot项目下一起打包
前端·spring boot·后端
恋猫de小郭35 分钟前
2026,Android Compose 终于支持 Hot Reload 了,但是收费
android·前端·flutter
hpoenixf7 小时前
2026 年前端面试问什么
前端·面试
还是大剑师兰特7 小时前
Vue3 中的 defineExpose 完全指南
前端·javascript·vue.js
泯泷7 小时前
阶段一:从 0 看懂 JSVMP 架构,先在脑子里搭出一台最小 JSVM
前端·javascript·架构
mengchanmian8 小时前
前端node常用配置
前端
华洛8 小时前
利好打工人,openclaw不是企业提效工具,而是个人助理
前端·javascript·产品经理
xkxnq8 小时前
第六阶段:Vue生态高级整合与优化(第93天)Element Plus进阶:自定义主题(变量覆盖)+ 全局配置与组件按需加载优化
前端·javascript·vue.js
A黄俊辉A9 小时前
vue css中 :global的使用
前端·javascript·vue.js
小码哥_常9 小时前
被EdgeToEdge适配折磨疯了,谁懂!
前端