一、

在 HarmonyOS 应用开发中，UI 代码的复用性直接决定了开发效率与代码可维护性。ArkTS 的声明式语法让 @Builder 成为建立可复用 UI 片段的关键工具，但许多开发者在实际使用时常常遇到以下痛点：

• 重复编写相同布局导致代码冗余。
• 状态变化后 UI 未能及时刷新。
• 难以区分何时使用局部 Builder 与全局 Builder。
• 对按值传递与按引用传递机制理解不清晰。

二、@Builder 装饰器简介

@Builder 是 ArkTS 中用于建立可复用 UI 片段的主要装饰器。它将重复的 UI 结构抽象为独立函数，提高模块化和可维护性。

主要特点

• 复用性: 封装重复布局，消除冗余代码。
• 灵活性: 可在组件内部或模块级别定义。
• 关系区别: @Builder 用于 UI 片段；@Component 用于完整自定义组件，有自己的状态和生命周期。

三、基础用法

组件内 @Builder

仅在当前组件内可调用，可通过 this 访问组件状态变量：

@Componentstruct MyComponent {
@State count: number = 0;@Builder ItemBuilder {
Text
.padding
.backgroundColor;}
build {
Column {
this.ItemBuilder;this.ItemBuilder;}
}
}

全局 @Builder

在模块级别定义，可在整个应用内调用。但无法使用 this

@Builder
function GlobalBuilder {
Text.fontSize;}
@Componentstruct MyComponent {
build {
Column {
GlobalBuilder;}
}
}

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

This section addresses one of most common pain points—UI not refreshing after state changes.

按值传递——导致刷新失败的典型案例：

@Entry
@Componentstruct Parent {
@State label: string = 'Hello';怎么说呢，build {
Column {
ValueBuilder;
// label 变化不会更新
Divider;
Text.fontSize;Button.width
.onClick => { this.label = 'ArkUI';})，}.width;}
}
@builderfunction ValueBuilder {
Row {
Text.fontSize;}
}

再看运行效果说明，

User may notice that even after clicking button to change alertLabel。Builder-generated text remains unchanged because it received a value copy.

@builder 按引用传递——解决刷新问题的方法：

The key rule is *only one argument* and it must be an object literal.

1. Create a wrapper class or interface for parameters.

// Wrapper definition
class Tmp { param: string = '';}
// Global Builder using reference passing
@builderfunction RefBuilder {
Row {
Text.fontSize;
}
}
@Entry
@Componentstruct ReferencePassingExample {
@State label: string = 'Hello';
build {
Column {
RefBuilder;// use object literal
Divider;Text.fontSize;Button.width
.onClick => { this.label = 'ArkUI';})，}.width;}


}


运行效果说明的观点是，



The displayed text updates automatically when alertLabel . This demonstrates that passing by reference works as expected.

If you try to modify tag.param . inside Builder,it will throw a runtime error because parameters are immutable within Builders.

Avoid using new 。strings directly or multiple arguments—those trigger value passing and break reactivity.
Tip: Always wrap related state in a single object if you need multiple values in a Builder.





至于注意，按值传递时修改参数不会报错，但不会影响外部状态：

@builderfunction ValueChangeDemo {
Row {
Text.fontSize
.onClick => { paramA1 = 'World';按理说，console.log;})，}
}


五、高级用法与常用方法 

循环生成列表 

Simplify dynamic list rendering:

@builderfunction ListItem{
Text.padding.width;}
@builderfunction ListRenderer {
Column{
ForEach=>{ListItem});}
}

You can n call `ListRenderer` .

嵌套 Builders – 更细粒度复用 

@builderfunction Header{
Text.fontSize.fontWeight;}
@builderfunction Card{
Column{
Header;Text.fontSize;说起来，}.padding.backgroundColor.borderRadius;}

与 @Prop / @Link 的配合 

This allows Builders inside components to access component state directly:

@Componentstruct ChildComponent{
@Prop message:string;@Link counter:number;
 @builder MessageDisplay{
Row{
Text.fontColor;Button.onClick=>{this.counter++;})，}
}
build{Column{this.MessageDisplay;}}



六、注意事项 



参数传递必须明确value vs reference否则 UI 刷新失效！

若只需一次性渲染且无状态依赖，用全局 Builder；若需访问 this 状态，用局部 Builder。

避免滥用 Builders 替代完整 Component；当逻辑复杂或需要生命周期管理时请改为 Component。

Builders 内禁止修改参数，否则会抛出错误；若需要双向绑定请考虑 @Link 或 Observable. 

'按引用'可能导致更多重绘。请合理设计对象结构，以免出现性能瓶颈。'






七、