鸿蒙应用开发 @Builder 使用教程：从入门到精通

一、引言

在 HarmonyOS 应用开发中，UI 代码的复用性是提升开发效率和代码可维护性的关键。ArkTS 作为鸿蒙的声明式开发语言，提供了@Builder装饰器，专门用于构建可复用的 UI 片段。本文将深入浅出地介绍@Builder的核心概念、使用场景、参数传递机制以及最佳实践，帮助你彻底掌握这一重要工具。

二、@Builder 装饰器简介

@Builder是 ArkTS（HarmonyOS 5.0.0+）中用于构建可复用 UI 片段的核心装饰器。它允许开发者将重复的 UI 结构抽象为独立的函数，提升代码的模块化和可维护性。@Builder装饰的函数称为“自定义构建函数”，遵循 ArkUI 的build()函数语法规则，用于返回一组 UI 描述。

主要特点

• 复用性：封装重复的 UI 结构，避免代码冗余。
• 灵活性：可在组件内部定义（私有）或全局定义（跨组件使用）。
• 与组件关系：@Builder通常用于 UI 片段的复用，而@Component用于定义完整的、带有独立状态和生命周期的自定义组件。

三、基础用法

3.1 组件内 @Builder（私有）

在自定义组件内部定义，仅在该组件内可调用，能够通过this访问组件的状态变量。

@Componentstruct MyComponent{@Statecount:number=0;@BuilderItemBuilder(text:string){Text(text).padding(10).backgroundColor(0xeeeeee)}build(){Column(){this.ItemBuilder("条目1")this.ItemBuilder("条目2")}}}

3.2 全局 @Builder

在模块级别定义，可在整个应用内调用，但不允许使用this，因此不适合依赖组件状态的场景。

@BuilderfunctionGlobalBuilder(param:string){Text(param).fontSize(16)}@Componentstruct MyComponent{build(){Column(){GlobalBuilder("全局构建函数")}}}

四、参数传递：按值传递 vs 按引用传递

这是@Builder使用中最关键的概念，理解不当会导致 UI 不刷新的问题。

4.1 按值传递（默认）

传递的参数在@Builder内部是值的拷贝，外部状态变化不会触发@Builder内部的 UI 刷新。

// 按值传递（不响应外部变化）@BuilderfunctionValueBuilder(paramA1:string){Row(){Text(`Builder - 按值传递:${paramA1}`).fontSize(20)}}@Entry@Componentstruct Parent{@Statelabel:string='Hello';build(){Column({space:20}){ValueBuilder(this.label)// label 变化不会更新Divider()Text(`label的值：${this.label}`).fontSize(20)Button('点击').width('80%').onClick(()=>{this.label='ArkUI'})}.width('100%')}}

运行效果：

4.2 按引用传递（响应外部变化）

使用对象字面量传递参数，当状态变量变化时，@Builder内部的 UI 会同步刷新。

@Builder按引用传递的核心规则是：必须且只能传入一个参数，且该参数必须是一个对象字面量。

以下是具体的实现步骤和示例：

1. 定义一个类或接口，用于封装需要传递的参数。
2. 在@Builder函数中，将参数类型指定为该类或接口。
3. 在调用@Builder时，使用对象字面量 { 属性名: 状态变量 }的形式传入。

// 1. 定义一个类，用于封装参数classTmp{param:string='';}// 按引用传递（响应外部变化）// 2. 定义全局 @Builder 函数，参数类型为 Tmp@BuilderfunctionRefBuilder(tmp:Tmp){Row(){Text(`Builder - 按引用传递:${tmp.param}`).fontSize(20)}}@Entry@Componentstruct ReferencePassingExample{@Statelabel:string='Hello';build(){Column({space:20}){// 3. 调用时，使用对象字面量形式传入状态变量RefBuilder({param:this.label})Divider()Text(`label的值：${this.label}`).fontSize(20)Button('改变值').width('80%').onClick(()=>{this.label='ArkUI';// 修改状态变量，会触发 @Builder 内 UI 刷新})}.width('100%')}}

运行效果：

关键点与常见错误：

1. 必须使用对象字面量：{ param: this.myParam }这种形式是触发按引用传递的必要条件。
2. 只能传入一个参数：如果@Builder函数需要多个值，必须将它们封装到同一个对象中（如上面的Tmp类），不能写成RefBuilder({ param: this.myParam }, 12)。
3. 不能使用new构造对象：RefBuilder(new Tmp(this.myParam))这种方式会变成按值传递，UI 不会刷新。
4. 不能直接传字符串：RefBuilder(this.myParam)是典型的按值传递，UI 不会刷新。
5. 禁止修改参数值：在@Builder函数内部，不允许修改传入的参数（如tmp.param = 'new'），否则会抛出运行时错误。

@BuilderfunctionRefBuilder(tmp:Tmp){Row(){Text(`Builder - 按引用传递:${tmp.param}`).fontSize(20).onClick(()=>{tmp.param='new';})}}

运行效果：

注意：按值传递时，修改参数值不会报错：

@BuilderfunctionValueBuilder(paramA1:string){Row(){Text(`Builder - 按值传递:${paramA1}`).fontSize(20).onClick(()=>{paramA1='World'console.log(`修改后的值为：${paramA1}`)})}}

运行效果：

五、高级用法与最佳实践

5.1 在 @Builder 中使用循环

结合ForEach可以动态生成多个 UI 片段。

@BuilderfunctionListBuilder(items:string[]){Column(){ForEach(items,(item:string)=>{Text(item).padding(8).width('100%')})}}

5.2 嵌套 @Builder

@Builder函数内部可以调用其他@Builder函数，实现更细粒度的复用。

@BuilderfunctionHeaderBuilder(title:string){Text(title).fontSize(20).fontWeight(FontWeight.Bold)}@BuilderfunctionCardBuilder(title:string,content:string){Column(){HeaderBuilder(title)Text(content).fontSize(14)}.padding(16).backgroundColor(0xffffff).borderRadius(8)}

5.3 与 @Prop 和 @Link 配合

在组件内@Builder中，可以直接使用this访问组件的@State、@Prop、@Link等装饰器修饰的变量。

@Componentstruct ChildComponent{@Propmessage:string;@BuilderMessageBuilder(){Text(this.message).fontColor(Color.Blue)}build(){Column(){this.MessageBuilder()}}}

六、注意事项

• 参数传递机制：若@Builder需要响应状态变化，务必使用按引用传递（封装为对象）。直接传递基本类型（如number、string）会导致 UI 不更新。
• 作用域选择：仅在单个组件内复用的 UI 使用组件内@Builder；无状态、全局复用的 UI 使用全局@Builder。
• 避免滥用：@Builder适合静态或简单动态 UI 片段；对于具有独立生命周期或复杂逻辑的 UI，应使用@Component。
• 参数不可变：在@Builder函数内部不要修改参数值（ArkTS 强制约束），如需双向同步，考虑使用@Link装饰器。
• 性能考量：按引用传递可能引起更多 UI 刷新，合理设计参数结构以避免不必要的重绘。

七、总结

@Builder是 ArkUI 声明式开发范式中提升 UI 复用性的重要工具。正确理解其参数传递机制（按值 vs 按引用）是避免 UI 更新问题的关键。

在开发中，根据场景灵活选择@Builder与@Component，能够构建出既高效又易维护的 HarmonyOS 应用界面。