首发于华为开发者论坛：https://developer.huawei.com/consumer/cn/blog/topic/03225800866361179
把 @State 状态在调用点当实参传进 @Builder，那一处 UI 首次渲染后就固化了——之后状态怎么变它都不动。编译不报错、运行不报错、日志一切正常，这个坑连一行异常都不给你。

我在三个不同的地方踩了它三次，前两次都没认出来。第三次是被华为审核实测复现、按功能异常驳回的，才终于想明白三次是同一件事。

三次事故，表现完全不一样

第一次在统计页。卡片是个 metricCard(label, value, ...) 形状的 @Builder，调用点传的是 this.perKmStr。记录页的数据早就是新值了，统计页这张卡片还停在初始的「——」。同一个指标，两个页面两个答案。我当时以为是数据没算出来，钻进计算逻辑查了一圈——计算是对的。

第二次在编辑页。输入框 numInput(placeholder, value, onChange) 接收 this.amountStr。点开一条既有记录，金额、油量、里程全是空白；用户改完一存，金额还被写坏了。这次我以为是异步时序问题，加 await、加刷新计数，没用。

第三次是个结果卡 resultCard($$: QuickResult)，调用点传 this.bpRes、this.gluRes、this.bmiRes，改完数据重算不刷新。这一次没等我自己发现，审核实测撞见了，2026-07-30 驳回，归在应用功能类的功能异常。（归类这几个字来自我事后写在守卫脚本上方的一行备忘，报告本身没留，所以只算大意。）

三次的表现毫无相似之处——一个显示旧值、一个全空白、一个不刷新。共同点只有一个：状态都是在调用点作为实参传进 @Builder 的。

想明白的那一刻：值参只求一次值，之后就再也不看了

ArkUI 这条规则其实很干脆：@Builder 函数体内读 this.<状态>，会随组件刷新；状态在调用点作为实参传进去，首次渲染后固化。值参只在第一次求值，之后 state 再变，也不会重新求值。

所以才会出现「内容变了、这一处不变」：内容变是因为别处直接读了状态，这一处不变是因为它拿的是第一次求值的那个快照。整个过程不报错、不抛异常，日志里干干净净。

修法是把状态判断挪进 @Builder 内部：

// ❌ 调用点算好再传进去：active 永远是第一次那个值
@Builder chip(label: string, active: boolean) {
  Text(label).fontColor(active ? C.brand : C.text)
  }
  ...
  this.chip('本月', this.range === 'MONTH')
// ✅ 判断放进 Builder，直接读 @State
@Builder chip(label: string, key: string) {
  Text(label).fontColor(this.range === key ? C.brand : C.text)
  }
  ...
  this.chip('本月', 'MONTH')

同族还有一个形态：带值参的 @Builder 渲染 async 加载的数据——首帧拿到 undefined，之后不再更新。这种更适合改成独立 @Component + @Prop。

一条不需要复现现场的判别式

这个坑最气人的地方是不产生任何报错，但它有个比报错更好用的东西：能静态扫出来。判别式就一句——在 @Builder 的调用点搜 this.<状态>。搜得到，那一处的 UI 首次渲染后就固化了。

grep -nE "this\.[a-zA-Z]+\((.*this\.)" entry/src/main/ets/**/*.ets

这条在任何鸿蒙工程上都能立刻跑，不需要先把现象复现出来。我要是早点有它，第二次、第三次就不会发生。

验证判据：真点一下，两处都要看

修完怎么算修好？在设备上真的点一下，看那一处有没有跟着变。我的做法是 hdc shell uitest uiInput click <x> <y> 点切换，然后 hdc shell uitest dumpLayout 把布局拉回来，断言两件事：内容变了，而且选中态标记也变了。

两个都要断。只断内容会漏掉这个坑——内容本来就会变，卡住的恰恰是高亮那一处。

别把这篇读成「值参都是错的」

值参本身不是错的。传常量——label 文本、图标名、尺寸——完全正常，这也是 @Builder 该有的用法，错的只有「传状态」。也别一刀切全改成 @Component：@Builder 更轻，能用就用，只要状态判断在函数体内。

上面那条静态扫描覆盖不了全部形态：实参是 this.foo(this.bar) 这种间接形式、或者状态经过一层函数包装，扫描器可能识别不出。所以绿灯只能读作「没踩到已知形态」，不是「没有这个坑」。

还有一件事值得单独说：这三次事故里，前两次审核都没抓到，是我们自己发现的，第三次才被抓。所以别拿「审核没提」当没问题的证据——审核抓到的是这一类问题的下界，不是上界。

这是《鸿蒙开发踩坑实录》第 10 篇。同一个坑连踩三次才认出来，这种事后来我学会了交给静态守卫去防。

本文由作者与 AI 协作整理，事实经作者核验。