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 |
