使用者痛点

你可能遇到以下困扰：

• 首屏渲染正常，但当后台数据变化时列表 item 根本不刷新。
• 尝试 回调方式后发现效果仍旧不一致，难以确定哪一处导致响应式失效。
• 代码中使用了箭头函数包装，却没有任何提示说明这会破坏懒加载链路。
• 想要在自定义 builder 内部做类型转换或参数映射，但担心会影响反应式追踪。

缘起

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

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

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

必要的概念

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

TL;DR

⚠️ 小心！如果你想把 builder 当作参数传进去。一定要直接传 @LocalBuilder 引用，否则可能出现数据变更时 UI 不刷新。

// ✅ 正确:
content: this.itemBuilder
// ❌ 错误:
content: => this.itemBuilder // 数据变化时 item 不重渲

普通箭头函数中间层会把懒求值“压扁”成快照，反应式追踪就在那一行断掉。如果必须套中间层，每个字段手动用 => ... 包成 lazy fn 可以保住链路。话说回来，

问题复现与对比表格

@BuilderParam 写法	首屏	数据变化时 item 重渲
①直接传 @LocalBuilder 引用✅✅	✅	✅

②箭头函数中间层。立即求值✅❌ ✅ ❌

✅ ✅ “手动包”方式可以保留响应式链路。 ⚠️ 忘记任何一个字段就会断链。 ⚠️ 通常只在需要类型适配/参数变换时使用。

✅ ✅

✅ ✅
✅
“手动包”方式可以保留响应式链路。⚠️ 忘记任何一个字段就会断链。怎么说呢，⚠️ 通常只在需要类型适配/参数变换时使用。

✅

⬇︎

❌ ❌ ❌ ❌

​

​​

注③ 用的是每个字段手动包成 lazy fn 的方法，可以让响应式追踪完整保持。

编译产物揭示的真相——从源码到底层实现说起

为什么框架使用 Proxy？

ArkUI V3 列表容器调用 content 时把实参不是普通对象，而是个 Proxy。通过 Proxy 包装所有字段为懒 getter，只要访问 Proxy 字段。就触发真实数据读取并登记为依赖，这样就能实现完整响应式链路。其实，缺省情况下如果你在 Arrow 函数体内立即求值。就会把这个 Proxy 换成具体值，丢失了依赖收集机制，所以后续更新无法触发 UI 刷新。

编译器如何自动注入懒 getter？

itemBuilder = => { this.innerBuilder.bind(makeBuilderParameterProxy("innerBuilder",{ data的观点是。=> ctx.data,index: => ctx.index })) }

`makeBuilderParameterProxy` 把字段包装成 ` => value` 的 lazy getter，从而保持对原始源数据 的跟踪。当下游 `itemBuilder` 调用 `innerBuilder` 时它 通过编译器自动包装 proxy，使得整个链条一直保持响应式状态。 若你在 Arrow 函数体内直接写 `data: ctx.data` 并立即执行，就破坏了这一机制。

如何在 Arrow 函数中保留懒链接？

interface LazyCtx { data : => Item;不过，index : => number;}

content: => { this.itemBuilder({ data : => ctx.data,index : => ctx.index }) }

@LocalBuilder itemBuilder{ this.innerbuilder({ data : ctx.data。index : ctx.index }) }

• `content` 中每个字段都包成 `< => ...>`；这一步保证传递给下游的是 **lazy function** 而非已求值的数据，从而让框架继续收集依赖。
• `itemBuilder` 在调用 `innerbuilder` 时显式执行 `ctx.data` 与 `ctx.index`；此时框架 proxy 拦截请求并完成真正的数据读取和依赖登记。这样就形成了一条完整可追踪、可更新的反应式链路。

主要机制

• `makeBuilderParameterProxy` 是 ArkUI V2 响应式追踪的载体：将所有属性包装成懒 getter，并在访问时注册依赖；其实现细节尚未公开，但从编译产物可逆推出这一逻辑是最合理解释。
• `@LocalBuilder/@Builder` 方法之间自动加 proxy 包装，让框架端到叶子 UI 都能保持相同的懒链接；这正是支持 List、Grid 等复杂容器能够高效滚动和重用节点的关键所在。
• `Arrow 函数体中的普通 JS 求值不会被编译器 所以如果你把 proxy 字段直接读出来放进对象字面量里就相当于把整个链接砸烂——这是导致「首次正常、随后失效」现象根本原因所在。只有通过 `< => …>` 手工包装才能让编译器继续工作并保留 reactive 方法。‎‎ ‎ ‎ ‎ ‎‎‎‎‎‎‎‎‎ ‎ ‎ ‎ ‎ ‎‎‎

实战建议——避免陷阱的小技巧

默认做法——直传 @LocalBuild 引用

@Local items : Item =

build{ LazyList({ items : this.items,content : this.itemListRenderer // ← 正确做法 }) }

@Local Builder itemListRenderer{ /* 渲染 UI */ }

# 常见错误 # : 将 content:=>this.itemListRenderer 写进来导致第一行就已经消耗掉 Reactive 链路。

---

必须套中间层时——全部手工包 lazy fn

build{ LazyList({ 再看items，this.items。content:=>{ // 手工将所有属性包装为 lazy fn this.customAdapter=>ctx.data as ConcreteType,idx:=>ctx.index }) }) }

@Local Builder customAdapter:ConcreteType;idx:number}){ // 下游真正使用 inner-builder 时显式求值，// 从而确保它们仍然是 proxy 包裹过的对象。this.uiRenderer({ itemData : ctx.typedData,position : ctx.idx }) }

# 注意点 # :

• **每个字段都必须是 `< => …>`**，漏掉一个就能导致整条链断裂！是在大型项目里一个小小的小 bug 就能让整个列表失去响应性，引起极大调试成本；💥💥💥
• 这种写法比直接引用更啰嗦，只在必要场景使用。例如需要进领域务级别的数据转换或统一格式化处理时才值得这么做；否则请尽量采用第一种方式来降低维护成本和潜在错误率。💡🛠️   

验证步骤 – 在自己的项目里确认是否正确实现

• 修改源码后重新编译，再去 DevEco Studio 项目缓存目录里的对应 .ts 文件查看最终生成代码；关键检查：
  • *content*: 最终传给框架的是 object。其中每个属性是 **lazy fn** =>value`) 而不是已求值的数据，否则即刻失效;
  • *@Local Builder*: 当它内部 调用其他 builder 时也应该被 `` 包裹，即其内部调用也要体现为 `<=>…>`，
  • *实参*: 检查所有属性是否都是 `<=>…>` 或者 **proxy object** 本身，而不是直接赋予具体数值;

  只要发现某段方法出现了 `data:somethingValue`。那就是断点 —— 从此以后该方法不会再收集新的依赖，也就不会随源数据改变而触发 UI 更新。

  If you only remember one thing:

  Use direct reference of @Local/​@Built in @BuiltParam slot – never wrap it in an arrow function unless you manually make each field a lazy function => …). This guarantees entire reactive chain remains intact.

  # 验证环境：Tips – use HarmonyOS Next / DevEco Studio,compile with esmodule debug mode. Different ArkUI compiler versions may behave slightly differently。so validate under your own version before deploying.

  # 未完全确认：The internals of makeBuildParameterProxy are not publicly documented. The above explanation is derived from decompiled code and observed behavior,which matches best practices for reactive systems.

。

---