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） |
三、使用原则与建议
- 优先核心装饰器 ：90%的场景可通过
@State、@Prop、@Link解决状态管理问题 - 谨慎使用深度监听 ：
@Track过度使用会导致内存开销增加 - 全局状态选择 ：
- 持久化数据用
AppStorage系列装饰器 - 页面级临时数据用
LocalStorage系列装饰器
- 持久化数据用
- 线程安全 ：
@Concurrent装饰的函数需确保无UI操作（遵守ArkTS线程模型） - 生命周期对齐 ：页面级装饰器（如
@OnPageShow）仅在@Entry组件生效
四、完整对比速查表
| 分类 | 核心装饰器 | 进阶装饰器 |
|---|---|---|
| 组件基础 | @Entry, @Component, @Builder | - |
| 状态管理 | @State, @Prop, @Link, @Observed | @Provide/Consume, Storage/LocalStorage系列 |
| 性能优化 | - | @Reusable, @Track |
| 动画样式 | - | @Animatable, @Styles, @Extend |
| 异步监听 | - | @Watch, @Concurrent |