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

摘要
ArkUI 的响应式状态管理看似简单,实则选错一个装饰器就会陷入「数据改了、界面不动」或「一改就整页重绘」的两难。本文从真实项目踩坑出发,先给出 @State、@Prop、@Link、@Provide/@Consume、@Observed/@ObjectLink、@Watch 六类装饰器的规格对照表,再用「嵌套对象刷新」的错误写法与正确写法做正反代码对比,配合选型决策流程图与数据流向对比表,最后沉淀出四条可直接落地的实战要点与选型口诀。读完你应能在一分钟内判断一份数据该用哪个装饰器,并知道嵌套结构为什么会断链、怎么修。
目录
一、背景与痛点
状态管理是 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 }) // 直接传引用,改内层即刷新
}
}
}
3.1 选型决策流程图
拿到一份数据,先按下面这条链路走一遍,基本不会选错装饰器:
3.2 数据流向对比
| 场景 | 推荐组合 | 数据流向 | 刷新范围 |
|---|---|---|---|
| 组件私有简单值 | @State | 自身 → 自身 | 仅当前组件 |
| 组件私有嵌套对象 | @State + @Observed/@ObjectLink | 子组件 → 对象 → 所有引用方 | 引用该对象的子组件 |
| 父下发初值 | @Prop | 父 → 子(深拷贝) | 仅子组件 |
| 父子双向 | @Link | 父 ⇄ 子(引用) | 父子共同刷新 |
| 跨层级共享 | @Provide/@Consume | 祖先 ⇄ 后代(key 关联) | 所有消费方 |
3.3 补充示例:@Link 与 @Provide/@Consume
// 父子双向:@Link 必须用 $ 传引用
@Component
struct Counter {
@Link count: number; // 与父组件双向同步
build() {
Row() {
Button('-').onClick(() => { this.count--; })
Text(`${this.count}`)
Button('+').onClick(() => { this.count++; })
}
}
}
// 跨层级共享:@Provide 下发,@Consume 按 key 取用
@Entry
@Component
struct LinkPage {
@State total: number = 0;
@Provide('theme') theme: string = 'dark'; // 跨层级共享,无需层层透传
build() {
Column() {
Counter({ count: $total }) // 注意 $,漏写会退化成值拷贝
Text(`总计:${this.total}`)
ThemeBadge() // 深层子组件直接 @Consume 取 theme
}
}
}
@Component
struct ThemeBadge {
@Consume('theme') theme: string; // key 必须与 @Provide 一致,拼错不报错但收不到
build() {
Text(`当前主题:${this.theme}`)
}
}
四、实战要点
要点 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 对象,改个角标整页重渲染,性能惨不忍睹,拆组件后立竿见影。
五、小结与边界
这套选型思路适用于所有 ArkUI 页面级状态组织:简单私有数据用 @State;父给子初值用 @Prop;父子联动用 @Link;跨多层共享用 @Provide/@Consume;嵌套对象/数组必须用 @Observed + @ObjectLink。它的边界是:只解决"UI 与状态同步"这一层,跨页面持久化要交给 AppStorage/PersistentStorage,全局单例状态更适合用状态管理库或单例类。落地口诀记牢:单层用 State、嵌套用组合、实体全 Observed、子层 ObjectLink;父改子传 Prop,双向记得加 Link。
本文为原创首发实战笔记,基于 HarmonyOS ArkUI 与并发调度能力,代码示例为可复用骨架,实际接口以华为官方文档为准。
六、总结
回到最初那个问题——「明明数据改了、界面却纹丝不动」,它几乎从来不是 ArkUI 的锅,而是选型时少想了一步。把本文压缩成三句话:
- 先定归属,再选装饰器。 数据是组件私有、父下发、父子双向还是跨层级共享,决定了候选集只有一两个,而不是六个里随便挑。
- 嵌套即断链,实体全
@Observed。 只要模型出现「对象套对象」「数组装对象」,监听链路上的每一层类都必须加@Observed,子组件用@ObjectLink持有引用,少一层就白干。 - 刷新范围要主动收窄。 拆子组件、缩小
@State作用域、列表项用@ObjectLink替代@Prop,都是把「全量重绘」压成「局部重绘」的同一件事。
如果只记一句口诀:单层用 State、嵌套用组合、实体全 Observed、子层 ObjectLink;父改子传 Prop,双向记得加 Link。 下次再遇到刷新问题,先按 3.1 的流程图走一遍,多数坑在写代码之前就能避开。
更多推荐

所有评论(0)