HarmonyOS5鸿蒙开发常用装饰器

​一、UI 组件装饰器​

  1. @Component

    • 标记 struct 为自定义组件,必须实现 build() 方法描述 UI 结构

    • 示例:

      scss 复制代码
      @Component
      struct MyButton {
        build() {
          Button('Click')
        }
      }
  2. @Entry

    • 声明页面入口组件,每个页面仅允许一个 @Entry 装饰的组件

    • 常与 @Component 组合使用:

      less 复制代码
      @Entry
      @Component
      struct HomePage { ... }
  3. @Reusable

    • 使组件具备复用能力,优化频繁创建/销毁场景的性能(如列表滑动、条件渲染)

    • 限制:仅能在同一父组件下复用实例。


🔄 ​​二、状态管理装饰器​

​1. 组件内状态​

  • @State

    组件内部私有状态变量,变化触发 UI 刷新

    ini 复制代码
    @State count: number = 0;
  • @Prop

    单向同步父组件的参数,子组件不可修改

    less 复制代码
    @Prop title: string; // 父组件传递的只读数据
  • @Link

    父子组件双向数据绑定,修改同步至父组件

​2. 跨层级状态​

  • @Provide@Consume

    实现祖先与后代组件的双向同步,无需逐层传递参数

    less 复制代码
    // 祖先组件
    @Provide('theme') theme: string = 'dark';
    
    // 后代组件
    @Consume('theme') theme: string;
  • @Observed@ObjectLink

    用于嵌套对象或数组属性的双向同步 @Observed 装饰类,@ObjectLink 装饰子组件中接收该类的变量。

​3. 应用级状态​

  • @LocalStorageProp / @LocalStorageLink

    与页面级 LocalStorage 中的属性建立单向/双向同步

  • @StorageProp / @StorageLink

    与全局 AppStorage 中的属性建立单向/双向同步


🛠️ ​​三、UI 复用与样式装饰器​

  1. @Builder

    • 封装可复用的 UI 描述块,支持引用状态变量($$ 语法)

      scss 复制代码
      @Builder customButton($$: { text: string }) {
        Button($$.text).width(100)
      }
  2. @BuilderParam

    • 作为占位符,接收外部传入的 @Builder 方法

      less 复制代码
      @BuilderParam action: () => void;
  3. @Styles@Extend

    • @Styles​:封装多条样式属性,支持全局或组件内复用

      scss 复制代码
      @Styles fancy() {
        .width(200).backgroundColor(Color.Red)
      }
    • @Extend​:扩展原生组件样式,支持参数传递

      less 复制代码
      @Extend(Text) function textStyle(size: number) {
        .fontSize(size).fontColor('#333')
      }
  4. stateStyles

    • 依据组件内部状态(如按下、禁用)动态切换样式

⚙️ ​​四、辅助功能装饰器​

  1. @Watch

    • 监听状态变量变化,触发回调逻辑

      less 复制代码
      @State @Watch('onCountChange') count: number = 0;
      onCountChange() { ... }
  2. @Track

    • 标记类对象的属性,仅当该属性变化时触发 UI 更新(优化性能)

      kotlin 复制代码
      class User {
        @Track name: string; // 仅 name 变化时更新 UI
      }

💎 ​​关键总结​

​类别​ ​装饰器​ ​核心用途​
​组件定义​ @Entry, @Component 标记入口和自定义组件
​状态管理​ @State, @Prop, @Link 组件内状态与父子同步
​跨组件通信​ @Provide/@Consume 祖先-后代数据共享
​UI 复用​ @Builder, @BuilderParam 封装与动态注入 UI 逻辑
​样式扩展​ @Styles, @Extend 样式复用与原生组件扩展
​性能优化​ @Reusable, @Track 组件复用与精准更新

更多实践案例可参考:HarmonyOS 开发文档 developer.huawei.com/consumer/cn... 。实际开发中需根据场景组合使用,例如 @State + @Watch 实现状态监听,@Provide + @Consume 替代深层参数传递。

相关推荐
zhanshuo10 小时前
构建可扩展的状态系统:基于 ArkTS 的模块化状态管理设计与实现
harmonyos
zhanshuo10 小时前
ArkTS 模块通信全解析:用事件总线实现页面消息联动
harmonyos
codefish79815 小时前
鸿蒙开发学习之路:从入门到实践的全面指南
harmonyos
yrjw21 小时前
一款基于react-native harmonyOS 封装的【文档】文件预览查看开源库(基于Harmony 原生文件预览服务进行封装)
harmonyos
搜狐技术产品小编20232 天前
搜狐新闻直播间适配HarmonyOs实现点赞动画
华为·harmonyos
zhanshuo2 天前
ArkUI 玩转水平滑动视图:超全实战教程与项目应用解析
harmonyos·arkui
zhanshuo2 天前
ArkUI Canvas 实战:快速绘制柱状图图表组件
harmonyos·arkui
zhanshuo2 天前
手把手教你用 ArkUI 写出高性能分页列表:List + onScroll 实战解析
harmonyos
zhanshuo2 天前
深入解析 ArkUI 触摸事件机制:从点击到滑动的开发全流程
harmonyos
i仙银3 天前
鸿蒙沙箱浏览器 - SandboxFinder
app·harmonyos