企业官网建设流程全解析

ArkUI 自定义组件：Builder 函数与 AttributeModifier 深度解析

读完本文，你将掌握 Builder 函数与 AttributeModifier 的底层机制差异，彻底告别"封装了但不好用"的困境。

适用版本：HarmonyOS NEXT / API 12+

阅读时长：约 18 分钟

---

场景切入：封装 UI 模块时你会遇到的两道墙

你负责维护一套设计系统，产品说按钮需要支持三种尺寸和五种色调，还要支持 Loading 状态。你用@Component封装了一个AppButton，上线后同学反馈："怎么没办法加 margin？为什么不能响应.onClick链式调用？"

这就是 ArkUI 自定义组件最常见的两道墙：

1.Builder 函数：解决"内容可配置、结构可复用"的问题

2.AttributeModifier：解决"属性可扩展、链式调用可传递"的问题

两者不是替代关系，而是各司其职。本文从源码视角切入，帮你搞清楚"用哪个、怎么用、踩过哪些坑"。

---

一、Builder 函数：UI 模板的高阶函数

1.1 什么是 Builder 函数

@Builder是 ArkUI 提供的一种轻量级 UI 复用机制。本质上，它是一个无状态的 UI 模板函数，编译期会被内联展开到调用处，和@Component相比没有独立的组件树节点。

@Builder 函数调用链路（编译期）
─────────────────────────────────────────────────
调用方组件树
│
├─ @Builder 调用 ──▶ 内联展开（无独立节点）
│ └─ Row { Text { } Image { } }
│
└─ @Component ──▶ 独立节点（有独立生命周期/渲染上下文）
└─ CustomCard { ... }
─────────────────────────────────────────────────

1.2 全局 Builder vs 局部 Builder

// 全局 Builder：文件级别，任何组件可调用
@Builder
function GlobalCard(title: string, icon: Resource) {
Row({ space: 8 }) {
Image(icon).width(24).height(24)
Text(title).fontSize(16).fontWeight(FontWeight.Medium)
}
.padding(12)
.backgroundColor('#F5F5F5')
.borderRadius(8)
}
@Component
struct DemoPage {
// 局部 Builder：仅在当前组件内可用，可访问 this
@Builder
localHeader(subtitle: string) {
Column() {
Text('固定标题').fontSize(20).fontWeight(FontWeight.Bold)
Text(subtitle).fontSize(14).fontColor('#999999')
}
.alignItems(HorizontalAlign.Start)
.padding({ left: 16, top: 12 })
}
build() {
Column({ space: 16 }) {
this.localHeader('副标题内容') // 调用局部 Builder
GlobalCard('搜索', $r('app.media.ic_search')) // 调用全局 Builder
}
}
}

1.3 Builder 参数传递：按值传递 vs 按引用传递

这是 Builder 最容易踩坑的地方。

// ❌ 错误写法：简单类型参数，状态变化不会触发 Builder 重新渲染
@Component
struct WrongDemo {
@State count: number = 0
@Builder
counterView(num: number) { // 简单类型，按值传递
Text(count: ${num})
}
build() {
Column() {
this.counterView(this.count) // count 变化，此处不会刷新！
Button('加一').onClick(() => { this.count++ })
}
}
}

问题根因：@Builder函数参数默认按值传递，调用时已固化为传入时的快照，后续状态变化不会触发重新展开。

// ✅ 正确写法：使用对象包装 + $$ 引用传递语法
interface CounterParam {
num: number
}
@Component
struct CorrectDemo {
@State count: number = 0
@Builder
counterView($$: CounterParam) { // 对象引用传递
Text(count: ${$$.num}) // 通过 $$ 访问，响应状态变化
}
build() {
Column() {
this.counterView({ num: this.count }) // 传对象，响应式
Button('加一').onClick(() => { this.count++ })
}
}
}

核心规则：Builder 需要响应状态变化时，必须将参数包装为对象并通过$$语法传递引用。简单类型参数只适合"静态渲染"场景。

1.4 @BuilderParam：让子组件接受 UI 插槽

@BuilderParam用于将 Builder 函数作为参数传入子组件，实现类似 Vue slot 的插槽能力。

@Component
struct Card {
@BuilderParam header: () => void // 接收 Builder 函数作为 header 插槽
@BuilderParam content: () => void // 接收 Builder 函数作为 content 插槽
build() {
Column() {
this.header()
Divider()
this.content()
}
.width('100%')
.backgroundColor(Color.White)
.borderRadius(12)
.padding(16)
}
}
@Component
struct PageDemo {
@Builder
myHeader() {
Text('自定义标题').fontSize(18).fontWeight(FontWeight.Bold)
}
@Builder
myContent() {
Text('这里是内容区域，可以放任意 UI').fontSize(14)
}
build() {
Card({ header: this.myHeader, content: this.myContent })
}
}

---

二、AttributeModifier：可传递的属性包

2.1 设计动机

@Component封装的组件有一个根本限制：外部调用方无法通过链式.method()设置子组件属性。这导致封装后的组件"属性被锁死"，调用方不得不通过 Props 一个个暴露属性——当属性超过 10 个时，组件接口就变得不可维护。AttributeModifier正是为了解决这个问题。它让你把任意属性操作包装成一个可传递的对象，注入到组件中执行。

AttributeModifier 工作原理
─────────────────────────────────────────────────────────
调用方 组件内部 渲染引擎
│ │ │
│ modifier对象 │ │
│─────────────────────▶│ │
│ │ applyNormalAttribute │
│ │─────────────────────▶│
│ │ applyPressedAttr │
│ │─────────────────────▶│
│ │ applyFocusedAttr │
│ │─────────────────────▶│
─────────────────────────────────────────────────────────

2.2 实现 AttributeModifier

// 定义自定义 Modifier，T 为目标组件属性类型
class PrimaryButtonModifier implements AttributeModifier {
private _size: 'small' | 'medium' | 'large' = 'medium'
private _loading: boolean = false
size(s: 'small' | 'medium' | 'large'): PrimaryButtonModifier {
this._size = s
return this // 支持链式调用
}
loading(v: boolean): PrimaryButtonModifier {
this._loading = v
return this
}
// 正常状态下的属性设置
applyNormalAttribute(instance: ButtonAttribute): void {
const sizeMap = { small: 28, medium: 36, large: 44 }
instance
.height(sizeMap[this._size])
.backgroundColor(this._loading ? '#CCCCCC' : '#0A59F7')
.borderRadius(sizeMap[this._size] / 2)
}
// 按下状态
applyPressedAttribute(instance: ButtonAttribute): void {
instance.backgroundColor('#0050D0').scale({ x: 0.97, y: 0.97 })
}
// 禁用状态
applyDisabledAttribute(instance: ButtonAttribute): void {
instance.backgroundColor('#E5E5E5').opacity(0.5)
}
}

// 调用方：像写原生属性一样使用
@Component
struct DemoPage {
modifier = new PrimaryButtonModifier().size('large').loading(false)
build() {
Column({ space: 16 }) {
Button('提交')
.attributeModifier(this.modifier) // 注入 modifier
.margin({ top: 20 }) // 外部属性仍可叠加
.onClick(() => { /* ... */ })
}
}
}

2.3 Modifier 状态响应：让属性动态变化

// ❌ 错误写法：直接修改 modifier 对象属性，UI 不会刷新
@Component
struct WrongModifierDemo {
modifier = new PrimaryButtonModifier()
build() {
Button('提交')
.attributeModifier(this.modifier)
.onClick(() => {
this.modifier._loading = true // 不会触发重渲染！
})
}
}

// ✅ 正确写法：用 @State 包装 modifier，替换整个对象触发刷新
@Component
struct CorrectModifierDemo {
@State modifier: PrimaryButtonModifier = new PrimaryButtonModifier()
build() {
Button('提交')
.attributeModifier(this.modifier)
.onClick(() => {
// 替换整个 modifier 对象，触发 @State 变更检测
this.modifier = new PrimaryButtonModifier().loading(true)
})
}
}

---

三、两者协同：构建真正可复用的组件库

3.1 架构对比

Builder vs AttributeModifier 适用场景对比
┌─────────────────┬────────────────────┬──────────────────────┐
│ 维度 │ @Builder │ AttributeModifier │
├─────────────────┼────────────────────┼──────────────────────┤
│ 复用粒度 │ UI 结构/模板 │ 属性集合 │
│ 状态感知 │ 需 $$ 引用传递 │ 需 @State 替换对象 │
│ 组件树节点 │ 无（编译期内联） │ 无（属性注入） │
│ 跨组件边界 │ @BuilderParam 传入 │ 直接作为 Props 传递 │
│ 链式调用 │ 不支持 │ 原生支持 │
│ 状态切换(按压等)│ 手动判断 │ applyPressedAttr │
└─────────────────┴────────────────────┴──────────────────────┘

3.2 实战：用两者封装 AppCard 组件

// 定义卡片 Modifier
class CardModifier implements AttributeModifier {
private _elevated: boolean = false
elevated(v: boolean): CardModifier {
this._elevated = v
return this
}
applyNormalAttribute(instance: ColumnAttribute): void {
instance
.backgroundColor(Color.White)
.borderRadius(12)
.padding(16)
.shadow(this._elevated
? { radius: 12, color: '#1A000000', offsetY: 4 }
: { radius: 4, color: '#0D000000', offsetY: 2 }
)
}
}
// 组件定义：Builder 负责内容插槽，Modifier 负责属性扩展
@Component
struct AppCard {
@BuilderParam headerSlot: () => void = this.defaultHeader
@BuilderParam contentSlot: () => void = this.defaultHeader
@Prop modifier: CardModifier = new CardModifier()
@Builder
defaultHeader() {
Text('默认标题').fontSize(16)
}
build() {
Column({ space: 8 }) {
this.headerSlot()
Divider().color('#F0F0F0')
this.contentSlot()
}
.attributeModifier(this.modifier)
.width('100%')
}
}
// 调用方
@Component
struct HomePage {
cardModifier = new CardModifier().elevated(true)
@Builder
cardHeader() {
Row({ space: 8 }) {
Image($r('app.media.ic_star')).width(20)
Text('热门推荐').fontSize(16).fontWeight(FontWeight.Bold)
}
}
@Builder
cardBody() {
Text('这是卡片内容区域').fontSize(14).fontColor('#666')
}
build() {
AppCard({
headerSlot: this.cardHeader,
contentSlot: this.cardBody,
modifier: this.cardModifier
})
.margin(16)
}
}

---

四、最佳实践

实践 1：Builder 函数控制在 50 行以内

做法：单个 @Builder 函数的模板代码不超过 50 行，超出时拆分为多个函数或改用 @Component。原因：Builder 会在每个调用点内联展开，过长的 Builder 函数导致组件树膨胀，Profiler 中可见 UI 节点数量激增，首帧渲染时间线性增长。不这样做会怎样：一个 200 行、被调用 10 次的 Builder，等效于将 2000 行 UI 压进同一个组件，渲染树深度和 diff 计算量双重膨胀。

实践 2：AttributeModifier 不在 build() 中 new

做法：在 @State 或成员变量中声明 Modifier，不要在build()方法内部构造。原因：build()每次渲染都会被调用。在build()内new Modifier()会在每帧创建新对象，既增加 GC 压力，又因对象引用变化导致不必要的属性重计算。不这样做会怎样：高频滚动场景下（LazyForEach 列表），每帧每个 item 都 new 一次 Modifier，GC 频率可在 Profiler 中观察到明显波峰，帧率从 60fps 跌至 45fps 以下。

实践 3：多插槽组件优先具名 @BuilderParam，而非尾随闭包

做法：当组件有 2 个及以上插槽时，全部使用具名 @BuilderParam 传参，禁用尾随闭包语法。原因：尾随闭包仅能传递最后一个 @BuilderParam，多插槽场景下会产生歧义。HarmonyOS NEXT 编译器对"尾随闭包给多 @BuilderParam 组件"会发出 warning，未来版本可能转为 error。不这样做会怎样：ComponentA { content() }写法在单插槽时正常，一旦组件迭代新增第二个插槽，所有调用方代码需全部修改，破坏向前兼容性。

---

五、常见坑点

坑点 1：Builder 内使用 this 导致 undefined

现象：局部 Builder 函数内访问this.someState，运行时报Cannot read property of undefined。原因：当通过@BuilderParam将局部 Builder 传入子组件时，this 上下文丢失——Builder 函数在父组件定义，但在子组件上下文中执行，this 指向子组件实例，而子组件没有该属性。复现：父组件局部 Builder 内访问this.parentState，将该 Builder 传入子组件的@BuilderParam，触发渲染时崩溃。解决：传递时通过.bind(this)绑定上下文，或将所需数据通过函数参数显式传入 Builder。

// ✅ bind this 后再传递
{ headerSlot: this.myHeader.bind(this) }

坑点 2：AttributeModifier applyNormalAttribute 属性叠加

现象：切换 Tab 回来后样式错乱，部分属性（如 border/shadow）叠加而非覆盖。原因：applyNormalAttribute在每次属性刷新时被调用，若方法内使用累加性 API 多次调用，每次刷新属性叠加一层。复现：在applyNormalAttribute内条件分支中调用.shadow()，多次切换状态后阴影效果叠加变深。解决：确保applyNormalAttribute是幂等的，每次显式设置完整值（包括"无效果"状态也要显式赋 undefined 或空值）。

坑点 3：@BuilderParam 未设默认值导致白屏

现象：组件在部分调用点未传@BuilderParam，渲染结果为空白，无报错日志。原因：@BuilderParam若无默认值且调用方未传入，ArkUI 会静默跳过该插槽的渲染（不抛出异常），导致对应区域白屏，难以排查。复现：定义@BuilderParam content: () => void（无默认值），调用方漏传，content 区域直接消失。解决：始终为@BuilderParam提供默认 Builder，即使是空实现：

@Builder
emptyBuilder() {}
@BuilderParam content: () => void = this.emptyBuilder

---

总结

1.@Builder是编译期内联的 UI 模板，适合封装可复用的 UI 结构；状态响应必须使用对象参数 +$$引用传递。

2.@BuilderParam实现 UI 插槽机制，多插槽场景必须具名传参，始终提供默认值防止白屏。

3.AttributeModifier将属性集合包装为可传递对象，天然支持链式调用和状态切换（按压/禁用/聚焦）。

4. Modifier 的状态响应需将整个 Modifier 对象声明为@State，通过替换对象触发刷新。

5. 两者结合使用：Builder 管结构，Modifier 管样式，共同构建真正可扩展的组件库。

核心结论：Builder 解决"UI 结构复用"，AttributeModifier 解决"属性跨边界传递"，二者互补而非替代。

---

参考资料

- ArkUI @Builder 装饰器官方文档

- AttributeModifier 接口说明

- @BuilderParam 装饰器文档

- OpenHarmony 源码参考路径：foundation/arkui/ace_engine/frameworks/core/components_ng/pattern/

- ArkUI 渲染管线源码：foundation/arkui/ace_engine/frameworks/core/pipeline_ng/