在 HarmonyOS 应用开发中，使用 ArkTS 的 @Builder 装饰器构建可复用的 UI 片段是极常见的操作。然而，许多开发者会遇到一个棘手的现象：明明父组件的状态变量（@State）已经更新了，但渲染出来的 @Builder 内容却“纹丝不动”。

本文将深入探讨这一问题的根源，并提供标准化的解决方案。

通过本文来解决问题后：

这里要感谢工单对面的这位不知名的工程师。

---

1. 现象描述：消失的响应式

假设你正在开发一个打字练习应用，底部需要实时显示打字速度和时间。你可能会这样写：

@Entry
@Component
struct TypingPage {
  @State timeDisplay: string = '00:00';

  // 错误示范：使用基础类型值传递
  @Builder BottomStatItem(label: string, value: string) {
    Row() {
      Text(`${label}：`).fontColor('#BDC3C7')
      Text(value).fontColor(Color.White) // 这里不会实时刷新
    }
  }

  build() {
    Column() {
      // 调用时传入基础类型
      this.BottomStatItem('时间', this.timeDisplay)
    }
  }
}

结果： 即使 this.timeDisplay 每秒都在变化，界面上的时间依然停留在初次渲染时的 00:00。

---

2. 根源分析：值传递与引用传递的差异

为什么值传递（Primitive Types）会失效？

在 ArkTS 的组件渲染机制中：

• 状态追踪：@State 装饰器会追踪变量的变化。
• Builder 执行时机：当你以 this.BottomStatItem('时间', this.timeDisplay) 这种形式调用时，实际上是将 timeDisplay 当时的快照值传给了函数参数。
• 闭包限制：对于 @Builder 而言，它接收到的参数是基本类型数据。一旦函数执行完毕，内部的 Text 组件绑定的是那个固定的字符串。由于基础类型不具备“指针”特性，当外部 timeDisplay 变化时，Builder 内部无法感知。

为什么对象传递（Object/Reference）有效？

当你传递一个对象（或类实例）时，Builder 内部持有的是对该对象的引用。由于 ArkUI 的数据观察机制能够穿透对象属性，当对象的属性发生变化时，框架能够识别出该 Builder 依赖的数据发生了变更，从而触发局部重绘。

---

3. 解决流程：对象封装法

流程图：UI 更新机制对比

实施步骤

1. 定义数据结构：创建一个类或接口来承载数据。
2. 修改 Builder 签名：让其接收这个对象作为参数。
3. 引用式调用：在 build() 中以对象形式传递参数。

---

4. 完整正确代码示例

第一步：定义数据类

/**
 * 使用类作为载体，ArkTS 能够更好地追踪其属性变化
 */
class BuilderItem {
  label: string = '';
  value: string = '';
}

第二步：重构组件

@Entry
@Component
struct TypingPage {
  @State timeDisplay: string = '00:00';
  @State rawSpeed: number = 0;

  /**
   * 正确示范：通过对象引用传递参数
   * @param item 封装了显示数据的对象
   */
  @Builder
  BottomStatItem(item: BuilderItem) {
    Row() {
      Text(item.label + '：')
        .fontSize(16)
        .fontColor('#BDC3C7')
      
      Text(item.value)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
        .fontColor(Color.White)
    }
  }

  build() {
    Column() {
      // ... 其它页面逻辑
      
      Row({ space: 40 }) {
        // 关键：以对象字面量形式传入
        // 框架会自动将其属性（如 this.timeDisplay）与该 Builder 建立响应式关联
        this.BottomStatItem({ label: '时间', value: this.timeDisplay })
        
        this.BottomStatItem({ label: '速度', value: `${this.rawSpeed} 字/分` })
      }
      .backgroundColor('#2C3E50')
      .width('100%')
      .height(60)
      .justifyContent(FlexAlign.Center)
    }
  }
}

---

5. 如何避免此类问题（最佳实践）

为了确保 UI 的响应式表现，请遵循以下准则：

1. 避开基础类型：尽量不要在 @Builder 传参中直接使用 string, number, boolean。
2. 强制对象化：即便只有一个参数，也建议封装成对象（例如 { val: this.count }）。
3. 使用接口或类：在复杂的业务场景中，定义专门的 Param 类，不仅能解决刷新问题，还能增加代码的可维护性。
4. 注意字面量调用：在调用 Builder 时，直接在参数位置书写 { key: this.stateVar } 是最稳妥的做法。

---

总结

ArkTS 的 UI 刷新依赖于对数据依赖项的精准追踪。通过将“值传递”改为“引用传递”，我们为框架提供了一个持久的“观察点”，从而彻底解决 @Builder 内部 UI 不更新的顽疾。