ArkUI @Builder装饰器：打造高效可复用的UI组件

本文面向HarmonyOS应用开发新手，全面解析ArkUI中@Builder装饰器的核心用法与最佳实践，助你快速掌握轻量级UI复用技巧。

---

一、@Builder装饰器是什么？

@Builder是ArkUI提供的UI元素复用机制，通过将重复的UI结构抽象为函数，实现：

1. 组件内复用：减少重复代码
2. 全局共享：跨组件复用UI模板
3. 动态更新：支持状态驱动的UI刷新

---

二、两种构建函数类型

1. 私有自定义构建函数

特点：组件内部使用，通过this访问组件状态

@Entry
@Component
struct PrivateBuilder {
  @State count: number = 0;

  // 定义私有构建函数
  @Builder
  CounterButton() {
    Button(`点击次数: ${this.count}`)
      .onClick(() => this.count++)
  }

  build() {
    Column() {
      this.CounterButton() // 调用
      this.CounterButton() // 重复使用
    }
  }
}

2. 全局自定义构建函数

特点：跨组件复用，不与具体组件状态绑定

// 全局定义
@Builder
function GlobalButton(text: string) {
  Button(text)
    .width(200)
    .backgroundColor(Color.Blue)
}
@Entry
@Component
struct SamplePage {
  build() {
    Column() {
      GlobalButton('提交') // 全局调用
      GlobalButton('取消')
    }
  }
}

---

三、参数传递核心规则

1. 按值传递（默认）

• 传递基本类型值的副本
• 状态变量更新不会触发UI刷新

@Builder
function ValueDemo(param: string) {
  Text(param) // 值拷贝
}

@Entry
@Component
struct Parent {
  @State msg:string = "Hello"

  build() {
    Column() {
      ValueDemo(this.msg) // 传递字符串值
      Button("更新").onClick(() => this.msg = "Updated")
    }
  }
}

2. 按引用传递

• 使用对象字面量传递
• 支持状态变量动态更新

class UpdateParam {
  content: string = ''
}

@Builder
function ReferenceDemo($$: UpdateParam) {
  Text($$.content) // 引用传递
}

@Entry
@Component
struct Parent {
  @State param :UpdateParam= new UpdateParam()

  build() {
    Column() {
      ReferenceDemo({ content: this.param.content }) // 对象字面量
      Button("更新").onClick(() => this.param.content = "New Value")
    }
  }
}

---

四、五大实战场景

场景1：动态UI刷新

@Entry
@Component
struct DynamicUI {
  @State refreshFlag: boolean = false;

  @Builder
  RefreshBlock() {
    Text(this.refreshFlag ? "最新内容" : "加载中...")
  }

  build() {
    Column() {
      this.RefreshBlock()
      Button("切换状态")
        .onClick(() => this.refreshFlag = !this.refreshFlag)
    }
  }
}

场景2：多层嵌套构建

class NestParam {
  level: number = 1;
}

@Builder
function ParentBuilder($$: NestParam) {
  Column() {
    Text(`第${$$.level}层`)
    ChildBuilder({ level: $$.level + 1 }) // 嵌套调用
  }
}

@Builder
function ChildBuilder($$: NestParam) {
  Text(`子层级: ${$$.level}`)
}

@Entry
@Component
struct NestDemo {
  @State currentLevel:number = 1;

  build() {
    Column(){
      ParentBuilder({ level: this.currentLevel })
    }

  }
}

---

五、常见问题

❌ 错误1：多参数传递

// 反例：两个参数无法触发更新
@Builder
function MultiParamDemo(a: string, b: number) {
  //...
}

✅ 正确做法：封装为对象

class CorrectParam {
  a: string = '';
  b: number = 0;
}

@Builder
function SingleParamDemo($$: CorrectParam) {
  // 通过$$.a和$$.b访问
}

❌ 错误2：修改参数值

// 反例：在构建函数内部修改参数
@Builder
function ModifyDemo($$: { val: string }) {
  Button($$.val)
    .onClick(() => $$.val = "Changed") // 禁止！
}

---

六、最佳实践总结

1. 优先全局构建：无状态复用时使用@Builder function
2. 参数对象化：多参数封装为单个对象
3. 状态管理：需要动态更新时使用按引用传递
4. 避免副作用：不在构建函数内修改参数
5. 命名规范：使用$$标识引用参数（非强制但推荐）

通过掌握这些核心技巧，你将能高效构建可维护的HarmonyOS应用界面。建议结合官方示例实践，加深对@Builder工作机制的理解。