鸿蒙的各种装饰器的作用和使用场景

程序员春哥
8 阅读5分钟

🧱 组件注册与入口

这类装饰器是构建页面的基础“地基”，负责将普通的ArkTS类转变为具备UI渲染能力的组件。

· @Component：标记一个类为自定义组件。被它装饰的类必须实现 build() 方法来描述UI结构。一个组件可以独立存在，也可以被其他组件复用。 · @Entry：标记当前组件为页面的入口。一个页面（即一个 .ets 文件）通常只有一个 @Entry 组件。它赋予了组件完整的生命周期，如 aboutToAppear 和 aboutToDisappear。 · @CustomDialog：用于标记一个自定义组件为弹窗。它可以配置弹窗的样式（如背景色、圆角）和交互按钮。使用时，需要通过 CustomDialogController 来控制其显示与隐藏。

// 配置示例
@CustomDialog
struct MyDialog {
  controller: CustomDialogController
  // ... 弹窗内容
}
// 使用时
dialogController: CustomDialogController = new CustomDialogController({
  builder: MyDialog(),
  alignment: DialogAlignment.Center, // 对齐方式
  offset: { dx: 0, dy: -20 } // 位置偏移
})

🔄 状态管理

这是ArkUI响应式编程的核心。状态变量的变化会自动驱动UI刷新。鸿蒙提供了两套状态管理体系：经典V1版本和新一代V2版本（API 12+）。两者不能在一个组件内混用。

经典V1版本

这套体系通过装饰器明确了数据在组件树中的流动方向。

· @State：组件内部状态，只能被自身访问和修改。是响应式的基础。 · @Prop：父传子的单向数据同步。子组件内的 @Prop 变量是只读的，其修改不会影响父组件。 · @Link：父子组件间的双向数据同步。子组件内修改 @Link 变量，会直接反映到父组件上。 · @Provide / @Consume：用于跨越多层（如爷爷传孙子）的双向数据同步。祖先组件用 @Provide“提供”数据，任何后代组件用 @Consume“消费”该数据，从而建立双向绑定，无需逐层传递。 · @Observed / @ObjectLink：用于深度观察嵌套对象（类或数组）的变化。@Observed 标记类为可观察，子组件中使用 @ObjectLink 接收该对象的引用，实现对对象内部属性的精准观测。 · @Watch：用于监听状态变量的变化。当被监听的变量改变时，会触发其装饰的回调函数。

新一代V2版本 (API 12+)

V2版本旨在提供更清晰的数据流向和更精细的观测能力，解决了V1中一些复杂场景的痛点。

· @Local：相当于V1中的 @State，纯粹的内部状态，严格禁止从外部初始化。 · @Param：相当于V1中的 @Prop，用于接收外部输入。但与 @Prop 的深拷贝不同，@Param 是引用传递，性能更好。 · @Event：V2中取消了 @Link。双向数据同步通过“@Param + @Event”模式实现。父组件通过 @Param 传值，并通过 @Event 传递一个回调函数给子组件。子组件想修改值时，调用这个回调，让父组件去修改源数据，数据流向更清晰可控。 · @Monitor：升级版的 @Watch，不仅能监听变化，还能配合 @Trace 实现深层监听，并能获取变化前后的值。 · @Computed：V2新增的计算属性。用于装饰getter方法，其值会随依赖的状态自动更新，且计算结果会被缓存，直到依赖发生变化，性能更佳。 · @ObservedV2 / @Trace：V2版的深度观测方案。在类上使用 @ObservedV2，在其内部属性上使用 @Trace 标记，即可实现对该属性的精准观测，比V1方案更简洁高效。

功能分类 V1 装饰器 V2 装饰器 核心差异与V2优势 内部状态 @State @Local @Local 更纯粹，禁止外部初始化。 单向输入 @Prop @Param @Param 为引用传递，性能优于 @Prop 的深拷贝。 双向同步 @Link @Param + @Event V2通过回调明确数据流向，避免双向绑定带来的隐式修改。 跨级传递 @Provide / @Consume @Provider / @Consumer 功能类似，V2版本命名更规范。 深层观测 @Observed / @ObjectLink @ObservedV2 / @Trace V2只需标记属性，更简洁高效，解决了V1中对象赋值后引用变动的痛点。 监听变化 @Watch @Monitor @Monitor 可监听深层变化，并提供新旧值，功能更强大。 计算属性 无 @Computed V2新增，自动缓存计算结果，优化性能。

🎨 样式与结构复用

这类装饰器旨在抽取公共的样式和UI结构，避免代码冗余，提升开发效率和可维护性。

· @Styles：抽取通用样式属性的集合，类似于CSS中的类。它不支持参数，且仅能作用于属性层面。

// 全局定义
@Styles function globalBtnStyle() {
  .width(100).height(40).backgroundColor(Color.Blue).borderRadius(8)
}
// 使用
Button('Click').globalBtnStyle()

· @Extend：用于扩展特定原生组件的样式，支持传参，能力比 @Styles 更强。它只能定义为全局。

// 扩展 Text 组件
@Extend(Text) function priceText(size: number, color: ResourceColor) {
  .fontSize(size).fontColor(color).fontWeight(FontWeight.Bold)
}
// 使用
Text('￥99').priceText(24, Color.Red)

· @Builder：用于封装复杂的UI结构（包括组件、样式、事件）。它支持参数传递，是最强大的UI复用方式。

// 封装一个卡片布局
@Builder function Card(content: string) {
  Column() {
    Text(content).fontSize(16)
  }.padding(10).border({ width: 1 }).borderRadius(10)
}
// 使用
Column() {
  Card('Title 1')
  Card('Title 2')
}

⚙️ 高级能力

· @Lifecycle：用于监听组件的生命周期事件，如 aboutToAppear（组件即将显示）和 aboutToDisappear（组件即将销毁），可在此时进行数据初始化和资源释放。 · @Adaptive：用于标记组件在不同设备类型（如手机、平板）上渲染不同的布局，是实现“一次开发，多端部署”的关键工具。

avatar
文章
阅读
粉丝