鸿蒙 ArkTS 状态管理实战：五个装饰器的边界与常见坑

最近在鸿蒙开发实践中心连着做了几个 ArkTS 案例，发现状态管理是最容易"看起来对、跑起来不刷新"的地方。这篇把自己踩过的坑整理一下，重点不是罗列 API，而是说清每个装饰器到底管哪一段数据流。

一、五个装饰器，各管一段

二、一个计数器看清 @State / @Prop / @Link

@Component
struct Counter {
  @State count: number = 0

  build() {
    Column({ space: 12 }) {
      Text(`父组件：${this.count}`)
      ChildProp({ value: this.count })
      ChildLink({ count: $count })
      Button('父组件 +1').onClick(() => { this.count++ })
    }
  }
}

@Component
struct ChildProp {
  @Prop value: number
  build() {
    Text(`@Prop 收到：${this.value}`)
  }
}

@Component
struct ChildLink {
  @Link count: number
  build() {
    Button(`@Link 修改：${this.count}`).onClick(() => { this.count++ })
  }
}

点 ChildLink 的按钮，父组件和 ChildProp 一起刷新；点父组件的按钮，ChildProp 也会更新。但如果在 ChildProp 里写 this.value++，只有它自己变，父组件不动——这就是"单向"的实际含义：同步是父到子的，反向没有通路。

三、五个高频坑

坑 1：@State 对象改嵌套属性不刷新

@State user: User = new User()

this.user.address.city = '杭州'   // 不刷新

@State 只观察第一层属性。嵌套结构要么用 @Observed + @ObjectLink，要么整体替换：

this.user = { ...this.user, address: { ...this.user.address, city: '杭州' } }

坑 2：数组元素属性修改不刷新

@State items: Item[] = []

this.items[0].done = true          // 不刷新
this.items[0] = { ...this.items[0], done: true }   // 刷新

数组本身的 push、splice、整体替换会触发刷新，元素内部的属性变化不会。列表里做勾选、展开这类交互时，这个差异最容易出问题。

坑 3：@Prop 是深拷贝，别拿它传大对象

@Prop 会复制一份数据，父子各持一份。传大数组或嵌套对象时有拷贝开销；高频更新的列表更建议用 @Link 或 @ObjectLink，避免每帧复制。

坑 4：@Link 忘了 $，或者给子组件赋了初值

ChildLink({ count: $count })      // 正确
ChildLink({ count: this.count })  // 传的是值，不是引用

另外 @Link 变量在子组件里不能写初始值，编译期就会报错。

坑 5：@Provide/@Consume 同名覆盖，@Watch 里再改状态

跨层级建议显式写别名，比如 @Provide('theme') 和 @Consume('theme')，避免不同业务用了同一个 key 互相干扰。@Watch 的回调在状态变更后触发，回调里不要再去同步修改被监听的变量，否则容易形成循环刷新。

四、选型建议

• 只在组件内部用：@State
• 父传子、子只读：@Prop
• 子组件要改父状态：@Link
• 跨三层以上共享：@Provide/@Consume
• 类实例的嵌套属性要观察：@Observed + @ObjectLink

五、关于状态管理 V2

API 12 起官方提供了状态管理 V2：@ComponentV2、@Local、@Param、@Event、@Monitor。简单说，@Local 对应组件内部状态，@Param 是只读的单向入参，@Event 用来把事件回传给父组件，@Monitor 替代 @Watch 做多属性监听。新项目可以按官方迁移指南评估，但不要在同一个组件里混用 V1 和 V2 的装饰器，排查问题时很难定位。

小结

状态管理的问题，九成不是"没写装饰器"，而是装饰器的作用域和数据的实际流向对不上：你以为改的是同一份数据，其实是两份拷贝；你以为观察的是整个对象，其实只观察了第一层。写之前先想清楚"这份状态归谁所有、谁需要改它"，再选装饰器，比事后补 @Observed 省事得多。