鸿蒙 核心与非核心装饰器

HarmonyOS NEXT 版本中完整的 ArkTS 装饰器分类整理（含核心与非核心装饰器，已剔除废弃特性）

---

一、核心装饰器（Essential Decorators）

1. 组件基础

装饰器	功能
@Entry	应用入口组件，每个模块必须且仅有一个，承载视图层级根节点
@Component	自定义组件声明，支持结构化UI开发（必须与struct配合使用）
@Builder	UI片段复用，定义可复用UI构建函数（非完整组件）

2. 状态管理

装饰器	数据流向	特性
@State	组件内部维护	私有状态驱动UI更新，支持本地初始化
@Prop	父 → 子单向同步	接收父组件数据，本地修改不影响源头
@Link	父 ↔ 子双向同步	自动双向绑定父组件的@State变量
@ObjectLink	复杂对象双向同步	配合@Observed实现嵌套对象属性级响应式更新
@Observed	对象可观察化	标记类为可观察对象（必须与@ObjectLink或@Prop配合使用）

3. 生命周期

装饰器	触发时机
@OnPageShow	页面显示（如返回栈恢复）
@OnPageHide	页面隐藏（如跳转至其他页面）
@OnBackPress	物理返回键/导航栏返回按钮事件监听（可拦截默认行为）

---

二、进阶装饰器（Advanced Decorators）

1. 性能优化

装饰器	用途
@Reusable	组件实例复用（类似Android RecyclerView回收池机制），减少重复渲染
@Track	精细化属性追踪，深度监听复杂对象属性变化（优化渲染性能）

2. 状态共享

装饰器	作用层级	特性
@Provide / @Consume	跨层级共享	实现祖先与后代组件间的状态透传（无需逐层传递props）
@StorageLink	全局持久化存储(AppStorage)	双向绑定应用级共享状态
@StorageProp	全局持久化存储(AppStorage)	单向绑定应用级共享状态（仅读取）
@LocalStorageLink	页面级临时存储	双向绑定页面栈内状态
@LocalStorageProp	页面级临时存储	单向绑定页面栈内状态（仅读取）

3. 动画与样式

装饰器	用途
@Animatable	声明式动画支持，配合animateTo实现属性过渡动画
@Styles	样式复用，定义组件通用样式集合（支持条件样式）
@Extend	样式扩展，为现有组件添加自定义样式能力

4. 异步与监听

装饰器	用途
@Watch	状态变化监听，在指定变量变化时触发回调函数
@Concurrent	并发函数标记，允许函数在TaskPool线程池中执行（需配合taskpoolAPI）

---

三、使用原则与建议

1. 优先核心装饰器：90%的场景可通过@State、@Prop、@Link解决状态管理问题
2. 谨慎使用深度监听：@Track过度使用会导致内存开销增加
3. 全局状态选择：
   • 持久化数据用AppStorage系列装饰器
   • 页面级临时数据用LocalStorage系列装饰器
4. 线程安全：@Concurrent装饰的函数需确保无UI操作（遵守ArkTS线程模型）
5. 生命周期对齐：页面级装饰器（如@OnPageShow）仅在@Entry组件生效

---

四、完整对比速查表

分类	核心装饰器	进阶装饰器
组件基础	@Entry, @Component, @Builder	-
状态管理	@State, @Prop, @Link, @Observed	@Provide/Consume, Storage/LocalStorage系列
性能优化	-	@Reusable, @Track
动画样式	-	@Animatable, @Styles, @Extend
异步监听	-	@Watch, @Concurrent

---