场景

在多数情况下，我们会有很多重复的内容，那如果多个相似 UI 组件我们都需要重复编写相同结构；这样就会冗余 ，不太方便 。所以我们就需要将这些相似 的封装起来组件化。

实现思路

我们使用 @Builder 这个属性来进行定义可复用的 UI 片段

@Builder
private function renderUserCard(user: { name: string; role: string }) {
  Column() {
    Text(user.name)
      .fontSize(16)
      .fontWeight(FontWeight.Bold)
    Text(user.role)
      .fontSize(12)
      .fontColor(Color.Gray)
  }
  .padding(10)
  .backgroundColor('#F0F0F0')
  .borderRadius(8)
}

然后在UI中进行调用这个Builder出来的组件片段

Column() {
  // 动态渲染多个卡片
  ForEach(users, (user) => {
    this.renderUserCard(user);
  })

  // 条件渲染：仅当用户有角色时显示
  if (currentUser.role) {
    this.renderUserCard(currentUser);
  }
}

完整的代码

interface UserInter {
  name: string;
  role: string;
}


@Entry
@Component
struct DynamicBuilderDemo {
  @State users: Array<UserInter> = [
    { name: 'Alice', role: '工程师' },
    { name: 'Bob', role: '设计师' },
    { name: 'Charlie', role: '产品经理' }
  ];
  @State currentUser: UserInter = { name: 'David', role: 'UI/UX' };

  //  原生 @Builder 用法
  @Builder
  private renderUserCard(user: UserInter) {
    Column() {
      Text(user.name)
        .fontSize(16)
        .fontWeight(FontWeight.Bold)
      Text(user.role)
        .fontSize(12)
        .fontColor(Color.Gray)
    }
    .padding(10)
    .backgroundColor('#F0F0F0')
    .borderRadius(8)
  }

  build() {
    Column({ space: 20 }) {
      Text('@Builder 动态组件示例')
        .fontSize(18)
        .fontWeight(FontWeight.Bold)

      // 动态渲染用户列表
      Text('团队成员')
        .fontSize(14)
        .fontColor(Color.Blue)
      ForEach(this.users, (user:UserInter) => {
        this.renderUserCard(user);
      })

      // 条件渲染当前用户
      if (this.currentUser.role) {
        Text('当前用户')
          .fontSize(14)
          .fontColor(Color.Blue)
        this.renderUserCard(this.currentUser);
      }
    }
    .padding(30)
    .width('100%')
    .height('100%')
  }
}

实现效果

可以看到通过@builder封装出来的片段可直接引用

在HarmonyOS Next中，@Builder装饰器用于构建自定义组件。它支持动态组合UI组件，通过参数传递实现灵活配置。@Builder允许在组件内定义可复用的UI描述块，并可根据条件或数据动态生成不同组件结构。使用@BuilderParam可接受@Builder类型的参数，实现父组件向子组件传递动态UI逻辑。这增强了组件间的解耦与复用能力。

在HarmonyOS Next中，@Builder装饰器是实现动态组件组合的核心工具，它允许你构建可复用的UI片段，并支持动态逻辑。以下是快速上手的要点：

1. 基础使用： 在组件内定义@Builder方法，封装UI结构：

@Builder
function MyButtonBuilder(label: string) {
  Button(label)
    .onClick(() => {
      // 点击逻辑
    })
}

在build()中调用：MyButtonBuilder('动态按钮')

2. 动态组合： 结合条件渲染和循环实现动态组合：

@Builder
function DynamicListBuilder(items: string[]) {
  Column() {
    ForEach(items, (item) => {
      Text(item).fontSize(16)
    })
    if (items.length > 0) {
      Divider()
    }
  }
}

3. 参数传递： 支持常规参数、尾随闭包（{ }）和@BuilderParam：

// 接收BuilderParam
@Builder
function ContainerBuilder(@BuilderParam content: () => void) {
  Column() {
    content() // 执行传入的UI构建器
  }
}

// 调用时传入UI片段
ContainerBuilder(() => {
  Text('内部内容')
})

4. 与状态联动： @Builder内可直接使用组件内的状态变量，状态变更时会触发UI更新：

@State count: number = 0

@Builder
function CounterBuilder() {
  Text(`点击次数：${this.count}`)
}

关键特性：

• 轻量复用：每个@Builder函数都是独立的UI单元，减少重复代码
• 类型安全：TypeScript支持参数类型校验
• 动态性：可与if/else、ForEach等语句灵活组合
• 作用域：默认访问组件内状态，也可通过参数传递数据

典型场景：

• 列表项模板
• 条件渲染的复杂UI块
• 可配置的弹窗/卡片组件
• 需要递归渲染的树形结构

通过@Builder将UI分解为可组合的构建块，能显著提升代码的可维护性和复用性。注意避免在@Builder内执行耗时操作，它应专注于UI描述。