HarmonyOS鸿蒙Next中@Builder可复用UI组件设计

HarmonyOS鸿蒙Next中@Builder可复用UI组件设计 在 ArkUI 中，@Builder 装饰器用于创建可复用的 UI 片段。@Builder 函数与普通函数有什么区别？如何向 @Builder 函数传递参数？@Builder 函数内部如何访问组件的状态变量？在设计复杂列表项时，如何合理使用 @Builder 提高代码复用性？（问题来源项目案例整理:https://github.com/heqiyuan35-creator/HydroQuiz.git）


更多关于HarmonyOS鸿蒙Next中@Builder可复用UI组件设计的实战教程也可以访问 https://www.itying.com/category-93-b0.html

3 回复

@Builder 是 ArkUI 的轻量级 UI 复用机制，比自定义组件更轻量。

特点：

  • 可以直接访问所在组件的状态变量和方法
  • 支持参数传递
  • 不创建新的组件实例，性能更好
[@Builder](/user/Builder)
KnowledgeArticleTreeItem(article: KnowledgeArticle, color: string) {
  Row() {
    Column() {
      // 标题行 - 可以访问组件方法
      Row() {
        Text(article.title)
          .fontSize(14)
          .fontColor(this.knowledgeService.isArticleRead(article.id)
            ? ThemeColors.TEXT_HINT
            : ThemeColors.TEXT_PRIMARY)
          .layoutWeight(1)
        // 已读标记
        if (this.knowledgeService.isArticleRead(article.id)) {
          Text('已读')
            .fontSize(10)
            .fontColor(ThemeColors.SUCCESS)
            .backgroundColor(ThemeColors.SUCCESS + '15')
            .borderRadius(8)
        }
      }
      .width('100%')
      // 元信息
      Row() {
        if (article.source) {
          Text(article.source)
            .fontSize(11)
            .fontColor(color)  // 使用传入的参数
        }
        Text(`⏱ ${article.readTime}分钟`)
          .fontSize(11)
          .fontColor(ThemeColors.TEXT_HINT)
      }
    }
    .layoutWeight(1)
    Text('›')
      .fontSize(18)
      .fontColor(ThemeColors.TEXT_HINT)
  }
  .onClick(() => {
    // 可以访问组件方法
    this.navigateToDetail(article.id);
  })
}

// 使用
ForEach(this.getArticlesByCategory(category.id), (article: KnowledgeArticle) => {
  this.KnowledgeArticleTreeItem(article, subject.color)
}, (article: KnowledgeArticle) => article.id)

更多关于HarmonyOS鸿蒙Next中@Builder可复用UI组件设计的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


@Builder装饰器

@Builder是鸿蒙Next中用于构建可复用UI组件的装饰器。它允许开发者将UI元素封装为方法，通过调用该方法在多个地方复用同一UI结构。@Builder支持参数传递，可动态定制组件内容。它适用于构建局部UI模块，提升代码复用性和可维护性。在声明时需遵循特定语法，并可在自定义组件或页面中灵活调用。

在HarmonyOS Next的ArkUI中，@Builder装饰器是构建可复用UI逻辑的核心工具。以下是针对您问题的具体解答：

1. @Builder函数与普通函数的区别

  • 目的不同：@Builder专门用于声明UI描述，最终渲染为界面元素；普通函数用于封装业务逻辑或数据处理，不直接参与UI构建。
  • 语法限制：@Builder函数体内必须是UI描述语句（如组件声明），不能包含逻辑表达式（如if/else、变量赋值），但可以调用普通函数执行逻辑。普通函数无此限制。
  • 更新机制：@Builder函数依赖其参数和闭包内的状态变量（@State、@Link等），当这些依赖变化时，会触发UI重建。普通函数的执行由代码调用触发。

2. 向@Builder函数传递参数 传递参数有两种方式：

  • 按值传递：适用于基础类型或需要隔离数据场景。在@Builder函数内修改参数值不会影响外部。
    [@Builder](/user/Builder) function MyBuilder(param: string) {
  Text(param) // 显示传入的字符串
}
// 调用
MyBuilder('Hello')
  • 按引用传递：使用$$语法传递状态变量的引用，实现双向同步。
    [@State](/user/State) message: string = 'Hello'
[@Builder](/user/Builder) function MyBuilder($$: { text: string }) {
  Text($$.text)
}
// 调用
MyBuilder({ text: $$this.message })

3. 访问组件状态变量 @Builder函数可以直接访问其定义所在组件的作用域内的状态变量（如@State、@Prop、@Link）：

[@State](/user/State) count: number = 0
[@Builder](/user/Builder) function CounterButton() {
  Button(`Click ${this.count}`) // 直接访问count
    .onClick(() => { this.count++ })
}

当count变化时，CounterButton会自动更新。

4. 在复杂列表项中提高复用性 以HydroQuiz项目为例，设计复杂列表项时：

  • 提取公共UI为@Builder：将列表项中可复用的布局结构（如带有特定样式的文本图片组合）封装成独立的@Builder函数。
  • 参数化配置：通过参数控制@Builder显示的内容和样式，使其能适应不同数据项。
  • 组合使用：将多个细粒度的@Builder组合成复杂的列表项，便于维护和单独测试。
  • 示例结构：
    // 定义可复用的标题构建器
[@Builder](/user/Builder) function ItemHeader(title: string, icon: Resource) {
  Row() {
    Image(icon)
    Text(title).fontSize(16)
  }
}

// 在列表项中使用
ForEach(listItems, item => {
  ListItem() {
    ItemHeader(item.title, item.icon) // 复用头部
    // ... 其他项特有内容
  }
})

通过以上方式，@Builder能有效提升UI代码的模块化水平和复用效率。

回到顶部