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 替代深层参数传递。

相关推荐
Jalor20 分钟前
Flutter + 鸿蒙 | Flutter 跳转鸿蒙原生界面
flutter·harmonyos
zhanshuo1 小时前
开发者必看!如何在HarmonyOS中快速调用摄像头功能
harmonyos
HMSCore1 小时前
借助HarmonyOS SDK,《NBA巅峰对决》实现“分钟级启动”到“秒级进场”
harmonyos
zhanshuo1 小时前
鸿蒙UI开发全解:JS与Java双引擎实战指南
前端·javascript·harmonyos
HarmonyOS小助手2 小时前
闯入鸿蒙:浪漫、理想与「草台班子」
harmonyos·鸿蒙·harmonyos next·鸿蒙生态
xq95272 小时前
flutter 鸿蒙化插件开发横空出世
harmonyos
HarmonyOS_SDK2 小时前
借助HarmonyOS SDK,《NBA巅峰对决》实现“分钟级启动”到“秒级进场”
harmonyos
别说我什么都不会3 小时前
【OpenHarmony】鸿蒙开发之Jmustache
harmonyos
塞尔维亚大汉3 小时前
鸿蒙内核源码分析(文件系统篇) | 用图书管理说文件系统
源码·harmonyos
塞尔维亚大汉7 小时前
鸿蒙内核源码分析(忍者ninja篇) | 都忍者了能不快吗
源码·harmonyos