ArkUI 状态管理选型实战:@State/@Link/@Observed 到底用哪个【鸿蒙心迹】

摘要
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不会重新渲染。 - 正确写法的关键三步:
Address、User两个类都加@Observed,让框架为其实例建立代理,属性变更可被追踪;- 子组件
AddressCard用@ObjectLink addr: Address持有引用而非拷贝,从而与父级数据建立深度双向监听; - 父组件通过
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 装饰器选型决策流程
5.2 错误写法与正确写法的刷新链路对比
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 的响应式失灵,而是装饰器选型与数据层级不匹配。本文的核心结论可以压缩成三句话:
- 先定归属,再选装饰器。 组件私有数据用
@State,父给子初值用@Prop,父子双向联动用@Link,跨多层共享用@Provide/@Consume,跨页面持久化交给AppStorage/PersistentStorage。 - 嵌套结构必须走深度监听。 只要出现「对象套对象」「数组装对象」,监听链路上的每一层实体类都要加
@Observed,子组件用@ObjectLink持有引用,少一层就断链。 - 性能靠作用域控制。 拆子组件、缩小
@State作用域、列表项用@ObjectLink替代@Prop,避免深拷贝与全量重绘。
如果只记一句口诀:单层用 State、嵌套用组合、实体全 Observed、子层 ObjectLink;父改子传 Prop,双向记得加 Link。 按这套思路落地,绝大多数「刷新不生效」的问题在写代码时就能被规避,而不是等到联调阶段再靠猜。
本文为原创首发实战笔记,基于 HarmonyOS ArkUI 与并发调度能力,代码示例为可复用骨架,实际接口以华为官方文档为准。
更多推荐

所有评论(0)