从编译产物看懂 ArkUI V2 `@BuilderParam` 的反应式陷阱

一个看起来等价的写法，结果首屏正常、数据更新却完全静止。本文从 ArkUI V2 的编译产物出发，定位反应式追踪在哪一行被切断，并给出验证过的安全写法。

缘起

在 HarmonyOS 应用里用 LazyForEach 渲染长列表很常见。我们封装了一个列表容器组件，对外暴露 content: @BuilderParam 让调用方决定 item 怎么渲染，看起来就是个普通回调。

但很快遇到一个诡异现象：首屏渲染完全正常，数据更新后 item 却纹丝不动。换一种"看起来等价"的写法之后又好了。两种写法的差异肉眼几乎看不出来，但行为天差地别。

本文记录从编译产物出发把这个问题挖到底的过程。

必要的概念

读者如果对 ArkUI V2 不熟，先简单对齐这几个名词：

• @ComponentV2 ：V2 状态管理体系的组件装饰器，相比 V1 的 @Component 提供更细粒度的状态追踪；
• @Local ：V2 里声明组件内部状态的装饰器（V1 里对应 @State）；
• @BuilderParam：声明在组件上的"可插拔 UI 槽位"，调用方传入一个 builder 作为内容；
• @LocalBuilder ：V2 引入的成员 builder 装饰器，相比 V1 的 @Builder 修复了 this 绑定问题；
• LazyForEach：懒加载列表迭代器，按可见区域按需创建 / 销毁 / 复用 item。

TL;DR

@BuilderParam 传 builder 时直接传 @LocalBuilder / @Builder 引用。

content: this.itemBuilder                       // ✅ 正确

content: (ctx) => this.itemBuilder({ ...ctx })  // ❌ 数据变化时 item 不重渲

普通箭头函数中间层会把懒求值"压扁"成快照，反应式追踪在那一行断掉。如果必须套中间层（类型适配 / 参数变换），每个字段手动用 () => ... 包成 lazy fn 可以保住链路。

问题复现

@ComponentV2 下用懒加载列表渲染动态数据，三种写法只差 content 一处：

@ComponentV2
struct Page {
  @Local items: Item[] = [/* ... */]

  aboutToAppear() {
    setInterval(() => {
      this.items[0] = makeItem()
      this.items = [...this.items]   // 触发 @Local 更新
    }, 2000)
  }

  build() {
    LazyList({
      items: this.items,
      content: /* 写法 ① / ② / ③ */
    })
  }
}

content 写法	首屏	数据变化时 item 重渲
① 直接传 @LocalBuilder 引用	✅	✅
② 箭头函数中间层，立即求值	✅	❌
③ 箭头函数中间层，手动懒求值	✅	✅

写法 ② 和 ③ 看起来只差几个 () =>，行为却完全不同。下面看编译产物。

编译产物揭示的真相

ArkUI 工程里源 .ets 文件会被编译成中间 .ts 文件，缓存在 DevEco Studio 的项目编译目录下（典型路径 <project>/build/default/cache/.../<source>.ts）。这些产物保留了 ArkTS 装饰器展开后的完整代码，是观察编译期变换的最佳现场。

框架调用 builder 的方式

ArkUI V2 列表容器调用 content 时，实参不是普通对象，是个 proxy：

// 容器内部，调用 content 的实际代码（编译后）
this.content.bind(this)(makeBuilderParameterProxy("content", {
  data: () => liveSource.data,     // ← 字段都是懒 getter
  index: () => liveSource.index    //    访问时才回读源数据
}))

makeBuilderParameterProxy 包装的字段全是 () => ... 函数。访问 proxy 字段才触发求值，这个访问被 V2 反应式系统登记为依赖。这是整条响应式链路的起点。

---

写法 ①：直接引用（工作）

源码：

content: this.itemBuilder

@LocalBuilder
itemBuilder(ctx: ItemCtx) {
  this.innerBuilder({
    data: ctx.data,
    index: ctx.index,
  })
}

itemBuilder 编译后：

itemBuilder = (ctx) => {
  this.innerBuilder.bind(this)(makeBuilderParameterProxy("innerBuilder", {
    data: () => ctx.data,     // ← 编译器自动把字段值包成懒 getter
    index: () => ctx.index
  }))
}

链路 ：framework proxy → 编译器在 @LocalBuilder 调用边界自动加 proxy → innerBuilder 内部访问字段 → 懒 getter 触发 → 一路回溯到 LIVE liveSource.data。

---

写法 ②：立即求值的中间层（断链）

源码：

content: (ctx) => {
  this.itemBuilder({
    data: ctx.data,     // ← 立即求值
    index: ctx.index,
  })
}

编译产物（关键部分）：

content: (ctx) => {
  this.itemBuilder({
    data: ctx.data,     // ← 编译器不改写普通箭头函数体
    index: ctx.index,
  })
}

断点 ：ctx.data 在箭头函数体里立即触发 framework proxy 的 () => liveSource.data getter，得到一个具体值，塞进 plain object。下游 itemBuilder 接到的是死值 ------ 从此往后读什么都是首屏快照。

反应式追踪断在这一行。

---

写法 ③：手动懒求值的中间层（工作）

源码：

interface LazyCtx {
  data: () => Item
  index: () => number
}

content: (ctx) => {
  this.itemBuilder({
    data: () => ctx.data,      // ← 用户手动包成 lazy fn
    index: () => ctx.index,
  })
}

@LocalBuilder
itemBuilder(ctx: LazyCtx) {
  this.innerBuilder({
    data: ctx.data(),          // ← 显式调用 lazy fn
    index: ctx.index(),
  })
}

预期链路：

• 箭头函数体里 { data: () => ctx.data, index: () => ctx.index } ------ 字面量保留，用户写的 lazy fn 没被求值，framework proxy 还活着；
• itemBuilder 调用 innerBuilder：编译器在 @LocalBuilder 调用边界再包一层 proxy，data: () => ctx.data()，调用时触发用户的 lazy fn → 触发 framework proxy → LIVE 读。

懒链路完整保留 → 反应式追踪正常。

核心机制

把上面三条产物连起来看，结论可以压缩成三句：

1. makeBuilderParameterProxy 是 ArkUI V2 反应式追踪的载体：把字段值改成懒 getter，访问时才回读源数据，并登记为依赖。
2. @LocalBuilder / @Builder 之间的方法调用 ，由编译器自动给实参加 proxy 包装，让懒链路从框架一路通到叶子 UI。
3. 普通箭头函数体不在编译器改写范围：函数体里对 proxy 字段的访问就是普通 JS 立即求值，瓦解懒链路 → 反应式追踪断裂。

实用建议

默认做法

@BuilderParam 直接传 @LocalBuilder 引用：

content: this.itemBuilder

@LocalBuilder
itemBuilder(ctx: ItemCtx) {
  /* UI */
}

必须套中间层时

每个字段都用 () => ... 包成 lazy fn，下游 @LocalBuilder 接函数类型参数，显式调用求值：

content: (ctx) => {
  this.adaptedBuilder({
    typed: () => ctx.data as ConcreteType,   // ← 一定要 lazy fn
    idx: () => ctx.index,
  })
}

@LocalBuilder
adaptedBuilder(ctx: { typed: () => ConcreteType; idx: () => number }) {
  this.uiBuilder({
    data: ctx.typed(),                       // ← 显式求值，再次落入编译器的自动包装
    index: ctx.idx(),
  })
}

注意点：

• 中间层每个字段都必须 () => ...，漏一个就断链；
• 这种写法读起来比直接引用啰嗦，仅在确实需要类型适配 / 参数变换时用。

在自己项目里验证

改源码后重编译，到项目的编译缓存目录翻 .ts 产物。关键看点：

• content 最终传给框架的对象，字段是值还是 () => 值；
• 自定义 @LocalBuilder 内部调用其他 builder 时，是否被 makeBuilderParameterProxy 包装；
• 实参的每个字段值，是否都是 () => ... 形式。

链路中任何一段是直接 data: someValue（不是 data: () => someValue），那段就是断点。

一句话总结

如果你只能记住一件事：@BuilderParam 优先直接传 @LocalBuilder 引用，不要套箭头函数中间层 。要套，每个字段都得用 () => ... 包成 lazy fn。

---

验证环境 ：HarmonyOS Next / DevEco Studio，@ComponentV2 + LazyForEach + @BuilderParam 组合下，基于 esmodule debug 编译产物分析。不同 ArkUI 版本编译器行为可能有差异，结论需各自版本下复核。

未完全确证的部分 ：makeBuilderParameterProxy 的内部实现没有翻到源码，"懒 getter + 反应式登记"是从产物反推 + 行为对照得出的最合理解释；如果有官方资料澄清细节欢迎指正。