在这里插入图片描述

摘要

ArkUI 的状态管理装饰器看似简单,实际选型却极易踩坑:@State 只观察第一层属性,嵌套对象改了不刷新;@Prop 是深拷贝,列表一长就卡;@Link 漏写 $ 直接退化成值拷贝。本文从「数据属于谁、谁会改、改了谁要看」这一条主线出发,先给出 @State、@Prop、@Link、@Provide/@Consume、@Observed/@ObjectLink、@Watch 的规格对照表,再用一段「嵌套对象刷新:错误 vs 正确」的可运行代码逐行拆解失效原因与修复三步,随后总结四条实战要点,最后用选型决策流程图、刷新链路对比图和能力对照表把结论可视化。读完你可以直接按图索骥,为任意一份状态数据选对装饰器,并避开「漏一层 @Observed 就断链」这类高频坑。

目录

一、背景与痛点

状态管理是 ArkUI 开发里写代码量最大、也最容易让人半夜爬起来改 Bug 的一块。我带过三四个鸿蒙项目,几乎每个新人上手第一周都会被"明明数据改了、界面却纹丝不动"这种诡异现象折磨。问题不在于 ArKUI 的响应式设计有缺陷,而在于大多数人把 @State 当成万能胶,不管嵌套对象还是跨页面共享,一股脑往上贴,结果要么刷新失效,要么一改就全页面重绘、性能暴跌。

真正写好鸿蒙状态管理,核心就一件事:先想清楚这份数据"属于谁、谁会改、改了谁要看",再决定用哪个装饰器。父给子一个初值、子改了不回传,用 @Prop;父子要双向联动,用 @Link;跨多层不想层层透传,用 @Provide/@Consume;一旦数据模型出现"对象套对象""数组装对象"的嵌套结构,就必须上 @Observed + @ObjectLink。选错装饰器,后面所有的"刷新不生效"都是必然,而不是偶然。

二、核心概念与规格

装饰器 / API数据流向最低版本关键约束(红字为高频坑)
@State组件私有,单向驱动自身API 9只能观察第一层属性变化,嵌套对象内层修改不刷新
@Prop父→子 单向拷贝API 9是深拷贝,大对象/列表项慎用;子改不影响父
@Link父子 双向同步API 9必须用 $ 传引用,漏写 $ 会变成值拷贝
@Provide/@Consume跨层级 双向共享API 9靠字符串 key 关联,key 拼错不报错但收不到数据
@Observed/@ObjectLink嵌套对象 深度双向API 9类与每层嵌套类都要加 @Observed,少一层就断链不刷新
@Watch变更副作用API 9同样只看第一层,数组内对象属性变化不触发回调

记住一句话:@State 是浅观察,嵌套数据必须 @Observed 配 @ObjectLink。这是全篇最重要的选型分水岭。

三、核心代码(嵌套对象刷新:错误 vs 正确)

// ❌ 错误写法:嵌套对象只用 @State,内层修改 UI 不刷新
class Address {
  city: string = '北京';
  detail: string = '';
}
class User {
  name: string = '';
  addr: Address = new Address(); // 嵌套子对象
}
@Entry
@Component
struct BadPage {
  @State user: User = new User();
  build() {
    Column() {
      Text(`城市:${this.user.addr.city}`) // 点按钮后这里不会变
      Button('改城市').onClick(() => { this.user.addr.city = '深圳'; })
    }
  }
}

// ✅ 正确写法:每层嵌套类加 @Observed,子组件用 @ObjectLink 持有引用
@Observed
class Address {
  city: string = '北京';
  detail: string = '';
}
@Observed
class User {
  name: string = '';
  addr: Address = new Address();
}
@Component
struct AddressCard {
  @ObjectLink addr: Address; // 建立深度双向监听
  build() {
    Column() {
      Text(`城市:${this.addr.city}`)
      Button('改城市').onClick(() => { this.addr.city = '深圳'; })
    }
  }
}
@Entry
@Component
struct GoodPage {
  @State user: User = new User();
  build() {
    Column() {
      AddressCard({ addr: this.user.addr }) // 直接传引用,改内层即刷新
    }
  }
}

代码说明:

  • 错误写法为什么失效:@State user 只观察 user 这一层属性的赋值(如 this.user = new User()),而 this.user.addr.city = '深圳' 改的是第二层属性,@State 感知不到,Text 不会重新渲染。
  • 正确写法的关键三步:
    1. Address、User 两个类都加 @Observed,让框架为其实例建立代理,属性变更可被追踪;
    2. 子组件 AddressCard 用 @ObjectLink addr: Address 持有引用而非拷贝,从而与父级数据建立深度双向监听;
    3. 父组件通过 AddressCard({ addr: this.user.addr }) 直接传引用,内层 city 一改,AddressCard 内的 Text 立即刷新。
  • 常见误区:只给最外层 User 加 @Observed、漏掉 Address,监听链在第二层断开,表现与错误写法完全一致——这也是排查时最容易忽略的点。

四、实战要点

要点 1:嵌套对象别省 @Observed,漏一层就断链。
我当初把一个三层嵌套的订单模型只给最外层加了 @Observed,结果改到第二层属性死活不刷新,调试半天发现中间那个类忘了加。规范:监听链路上的每一层实体类,全部强制加 @Observed,少一个都不行。

要点 2:@Link 绑定记得写 $,否则退化成值拷贝。
Child({ value: this.count }) 传的是副本,子组件怎么改父组件都不知道;必须 Child({ value: $count }) 才建立双向引用。我当初就因为这个,表单改完父页面数据没回写,排查了很久。

要点 3:列表项用 @ObjectLink 替代 @Prop 省拷贝。
列表里给每个 item 传 @Prop 会在渲染时深拷贝大对象,列表一长就卡。把 item 类加 @Observed,子组件用 @ObjectLink 引用持有,既能原地修改又能避免拷贝开销。

要点 4:想避免全量刷新,就拆子组件 + 缩小 @State 作用域。
把大页面拆成多个只持有自己 @State 的小组件,谁的数据变了谁重绘,别让一个顶层 @State 牵动整页。我当初一个巨型 @State 对象,改个角标整页重渲染,性能惨不忍睹,拆组件后立竿见影。

五、图表说明:选型决策与刷新链路

5.1 装饰器选型决策流程

是

否

是

否

父给子初值,子改不回传

父子双向联动

跨多层共享

跨页面持久化

这份数据属于谁?

组件私有?

是否嵌套对象/数组?

@State

@Observed + @ObjectLink

父子之间传递?

@Prop

@Link(记得写 $)

@Provide / @Consume

AppStorage / PersistentStorage

5.2 错误写法与正确写法的刷新链路对比

✅ @Observed + @ObjectLink

this.addr.city = '深圳'

@Observed 代理捕获属性变更

@ObjectLink 引用通知子组件

UI 局部刷新

❌ 只用 @State

this.user.addr.city = '深圳'

@State 只观察第一层

未捕获变更

UI 不刷新

5.3 各装饰器能力对照

观察维度@State@Prop@Link@Provide/@Consume@Observed/@ObjectLink
第一层属性变更✅✅✅✅✅
嵌套对象内层变更❌❌❌❌✅
子改父是否回传❌❌✅✅✅
是否产生深拷贝否是否否否
跨层级透传❌❌❌✅需配合使用

读图要点:只要数据模型出现「对象套对象」或「数组装对象」,无论上层用哪个装饰器,内层变更都必须靠 @Observed + @ObjectLink 兜底;其余装饰器只负责第一层的同步语义。

六、小结与边界

这套选型思路适用于所有 ArkUI 页面级状态组织:简单私有数据用 @State;父给子初值用 @Prop;父子联动用 @Link;跨多层共享用 @Provide/@Consume;嵌套对象/数组必须用 @Observed + @ObjectLink。它的边界是:只解决"UI 与状态同步"这一层,跨页面持久化要交给 AppStorage/PersistentStorage,全局单例状态更适合用状态管理库或单例类。落地口诀记牢:单层用 State、嵌套用组合、实体全 Observed、子层 ObjectLink;父改子传 Prop,双向记得加 Link。

七、总结

回到最初那个问题——「数据改了、界面却纹丝不动」,它几乎从来不是 ArkUI 的响应式失灵,而是装饰器选型与数据层级不匹配。本文的核心结论可以压缩成三句话:

  1. 先定归属,再选装饰器。 组件私有数据用 @State,父给子初值用 @Prop,父子双向联动用 @Link,跨多层共享用 @Provide/@Consume,跨页面持久化交给 AppStorage/PersistentStorage。
  2. 嵌套结构必须走深度监听。 只要出现「对象套对象」「数组装对象」,监听链路上的每一层实体类都要加 @Observed,子组件用 @ObjectLink 持有引用,少一层就断链。
  3. 性能靠作用域控制。 拆子组件、缩小 @State 作用域、列表项用 @ObjectLink 替代 @Prop,避免深拷贝与全量重绘。

如果只记一句口诀:单层用 State、嵌套用组合、实体全 Observed、子层 ObjectLink;父改子传 Prop,双向记得加 Link。 按这套思路落地,绝大多数「刷新不生效」的问题在写代码时就能被规避,而不是等到联调阶段再靠猜。


本文为原创首发实战笔记,基于 HarmonyOS ArkUI 与并发调度能力,代码示例为可复用骨架,实际接口以华为官方文档为准。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐