状态管理:@State 家族与 V2 状态管理
本篇要点:拿到任意一屏界面,能画出它的状态由谁持有、往哪个方向流、哪一条边不允许反向,并在 V1 与 V2 之间给出有理由的选择。 前置:《声明式 UI:组件、布局与样式》已经把组件、布局、构建函数跑通,并在购物车那一屏摸过 V2 的
@Local与@Param。这一章回头把 V1 家族的方向讲透,再补齐两者的边界与反模式。
为什么需要它
改了备注,点保存,返回列表,那条记录的备注还是旧的。
一个记账应用的"编辑账单"页在这上面卡了三天。
写法很普通:列表点进详情,子组件用 @Prop 接收账单对象;改完打日志,值确实变了。可一返回,列表还是旧的。
他们先把 @Prop 换成 @Link,编译报错,因为 @Link 必须用 $bill 传引用。再换成 @ObjectLink,又报错,说传入的类没有被 @Observed 装饰。
两次报错都在说同一件事,只是没人往那个方向读:@Prop 走的是深拷贝,子组件拿到的是副本,改副本和改原件是两件事。@Link 要的是引用传递语法,@ObjectLink 要的是被 @Observed 标过的类。三个装饰器解决的是三种不同的同步问题,长得像,用错一个就不刷新。
这类故障最耗时间的地方在于它不报错。控制台安静,console.info 打出来的值还是对的——你改的那一刻确实改成功了,只是改在一个没人看的地方。
一条基线先记住:V1 的观察能力挂在代理上,数据一离开组件,观察就断;V2 把能力放进数据实例,实例走到哪一层,观察跟到哪一层。本篇所有"该刷新没刷新"的排查,最后都会回到这一句。
版本上以截至 2026 年 11 月的 HarmonyOS 6.0.0(API 20)为准,装饰器有版本差异的地方,下文都会标出来。
核心概念
观察能力绑在谁身上
定义:观察能力指"某个值变了,框架能不能知道"。V1 在创建状态变量时同时创建一个数据代理观察者,能力长在 UI 那一侧;V2 用 @ObservedV2 标类、@Trace 标属性,能力长在数据本身。
这个差别带来两个直接后果,也是官方文档里写明的两条 V1 限制:状态变量不能独立于 UI 存在,同一份数据被多个视图代理时,其中一个视图的更改不会通知其他视图;只能感知对象第一层的变化。
如图 3-1 所示,V1 的 @Prop 那条边是拷贝,@Link 那条边是共享引用;V2 把下行改成传引用、把上行改成事件回调,方向变多了,但每条边的含义只有一种。
图 3-1 拷贝与引用:两条同步链路的差别
反例就是开头那一屏。@Prop 传的是账单对象,子组件改 note 改在副本上,父组件的列表数据一动没动。更隐蔽的一种:同一个订单对象同时被列表页和详情页用 @State 接住,详情页改完,列表页纹丝不动——这不是谁写错了,是 V1 的代理模型决定的。
V1 五件套:方向、初始化、观察深度
五个装饰器的差别集中在三列上,背下来比查文档快。
| 装饰器 | 方向 | 初始化要求 | 观察深度 | 常见误用 |
|---|---|---|---|---|
@State | 组件自身,不参与同步 | 必须本地初始化;父组件传入只作初值 | 第一层属性 | 当全局变量用,跨页面共享同一份数据 |
@Prop | 父 → 子,单向 | 可本地初始化,父值会覆盖 | 第一层,深拷贝 | 传大对象;改副本还以为父组件会跟着变 |
@Link | 父 ↔ 子,双向 | 禁止本地初始化,必须 $bill 传引用 | 第一层 | 传普通变量而不是 $ 前缀的引用 |
@Provide / @Consume | 跨层级双向,按 key 匹配 | @Provide 需本地初始化 | 第一层 | 当全局单例;同名 key 冲突 |
@Observed / @ObjectLink | 嵌套对象双向 | @ObjectLink 禁止本地初始化,必须由父传入 | 第二层及更深 | 只标 @Observed 却没在子组件用 @ObjectLink 接住 |
几个容易忽略的细节。
@State 从父组件接收的只是初值,之后父组件再变,@State 不会跟着变。这条规则让"父子各持一份"看起来能跑,实际上是两份数据。
@Prop 的深拷贝有代价。官方建议组件复用场景下嵌套不要超过 5 层,再深就该换 @ObjectLink,否则拷贝占用和垃圾回收会拖帧。深拷贝还会丢类型:PixelMap、RegExp 这类带原生实现的类型拷完就不再是原来那个东西。
@Consume 找不到对应的 @Provide 时,API 20 之前直接抛 JS ERROR;从 API 20 起可以给 @Consume 设默认值,找不到就用默认值,页面不崩、数据永远不更新——排查成本反而更高。
@Observed 与 @ObjectLink 的边界
定义:@Observed 标在类上,让这个类的实例属性可被观察;@ObjectLink 标在子组件的变量上,接住一个 @Observed 实例,从而建立双向绑定。
它解决的问题很具体:this.bill.items[0].price = 1 这种写法,@State 只看得到 items 的引用没变,看不到数组元素里 price 变了。要让框架看到,得让 items[0] 这一层也被观察。
两个成对出现的约束:@Observed 单独使用没有任何效果,必须有子组件的 @ObjectLink 接住;@ObjectLink 不能在组件内部初始化,只能由父组件传入。漏掉任何一条,代码都能编过,就是不动。
从 API 19 起这条边界松了一格:@ObjectLink 可以接收复杂类型了(class、object、内置类型),不再强制 @Observed。但要观察嵌套,内层仍得是 @Observed 类或者 makeV1Observed() 的返回值。老工程里那些"数组套数组"的写法,升级到 19 之后有机会少写几个 @Observed。
V2:把观察能力放进数据
V2 的分工比 V1 清楚,一句话能记住:类上用 @ObservedV2,属性上用 @Trace,组件用 @ComponentV2 声明。
@Local:组件内部状态,不能从外部初始化,必须在组件内初始化。@Param:外部输入,只读,不可在组件内直接赋值;允许本地初始化,不写就得配@Require。@Once:让@Param只接受一次外部初始化,之后本地可以改。@Event:上行回调,子组件想改数据就调它,由父组件去改数据源。@Provider/@Consumer:跨层级,key 与类型绑定。@Computed:只读 getter,依赖变了才算一次(API 12 起)。@Monitor:异步监听,一次事件里改多次只看最终值(API 12 起)。
这里有个必须说清的坑:@Local 装饰对象时,只观察"整体赋值"。this.bill = new Bill(...) 会刷新,this.bill.note = 'x' 不会。想在 V2 里观察对象内部字段,仍然老老实实给类加 @ObservedV2、给字段加 @Trace。换成 V2 不等于自动深度观察,深度观察的前提是 @Trace。
状态设计的三个反模式
反模式一:派生状态存两份。 列表和合计各存一个 @State,用 @Watch 互相同步。第一版能跑,加一个"批量删除"就漏了。凡是能由别的状态算出来的,都应该用 @Computed 算,不要存。
反模式二:把 @Provide 当全局单例。 @Provide 的作用域是组件树,页面一销毁就没了;同一棵树下再写一个同名 @Provide,未加 allowOverride 时运行时报错。真正的跨页面共享走 AppStorage 或 PersistenceV2,不要靠层级往上飘。
反模式三:在 @Monitor 里改被监听的变量。 这会再触发一轮回调,写不好就是循环。需要"改完再纠正"的逻辑,放到数据源那一侧的方法里,让一次写入只发生一次。
动手实践
三步,从复现到修好。
第一步,复现深拷贝。V1 写法,父组件持有 @State,子组件用 @Prop 接:
@Observed
class Bill {
id: string = '';
note: string = '';
constructor(id: string, note: string) {
this.id = id;
this.note = note;
}
}
@Component
struct BillEditor {
@Prop bill: Bill = new Bill('', ''); // 深拷贝:拿到的是副本
build() {
Column({ space: 12 }) {
TextInput({ text: this.bill.note })
.onChange((v: string) => { this.bill.note = v; })
Button('保存').onClick(() => {
console.info(`child note=${this.bill.note}`);
})
}
}
}父组件里 @State bill: Bill = new Bill('B-1', '午餐'),再放一个按钮:先打印 this.bill.note,再把它改成 '早餐'。
运行结果:输入框改成"夜宵"、点保存,控制台打印 child note=夜宵;点父组件那个按钮,打印 parent note=午餐——子组件的修改根本没回来。随后输入框跳成"早餐",那是父组件的新值把副本整个重置了。
第二步,改成 V2。数据带观察能力,输入只读,修改走事件:
@ObservedV2
class BillV2 {
@Trace id: string = '';
@Trace note: string = '';
constructor(id: string, note: string) {
this.id = id;
this.note = note;
}
}
@ComponentV2
struct BillEditorV2 {
@Require @Param bill: BillV2; // 引用,不是副本
@Event onNoteChange: (v: string) => void = () => {};
build() {
TextInput({ text: this.bill.note })
.onChange((v: string) => this.onNoteChange(v))
}
}父组件:@Local bill: BillV2 = new BillV2('B-1', '午餐'),传 onNoteChange: (v: string) => { this.bill.note = v; }。
运行结果:输入"夜宵",父组件的标题同步变成"夜宵";父组件从别处改 bill.note,输入框也跟着变。同一份实例,两个方向都通——因为 @Param 传的是引用,@Trace 让父子的读取都登记在同一条依赖上。
第三步,验证 @Local 的观察边界。
class PlainBill {
note: string = '午餐';
}
@ComponentV2
struct BadEditor {
@Local row: PlainBill = new PlainBill();
build() {
Column({ space: 12 }) {
Text(this.row.note)
Button('改备注').onClick(() => {
this.row.note = '夜宵';
console.info(`row note=${this.row.note}`);
})
}
}
}运行结果:点按钮,控制台打印 row note=夜宵,界面上的文字一个字没变。给 PlainBill 加 @ObservedV2、给 note 加 @Trace 再跑,文字立刻跟着变。这一步能省掉以后大量的"日志对、界面错"。
常见误解
"@Prop 和 @Link 的区别就是子组件能不能改。" 能不能改只是表象,根本差别是拷贝与引用:@Prop 改的是副本,父组件永远看不到;@Link 改的是同一份数据,父组件立刻看到。选错的后果不是报错,是数据悄悄分成两份。
"@Observed 加在类上就能深层观察。" 它只是给类打上"可被观察"的标记,还需要子组件的 @ObjectLink 接住,两处成对才有用。少了后者,框架不会为这个实例建立任何绑定。
"V2 是性能升级,老页面都该迁。" V2 换来的是深度观察、属性级更新、清晰的输入输出,帧率上不会有可测量的提升。官方给的建议也一样:新应用直接用 V2;已经用 V1 且功能性能都够的,不必急着改。
"@Local 就是 V2 版的 @State。" 两个差别:@Local 不能从外部初始化;@Local 装饰对象时只观察整体赋值。当成 @State 用,嵌套字段那一层照样不刷新。
小结
- 观察能力在 V1 长在代理上、在 V2 长在数据上;这条差别解释了绝大多数"该刷新没刷新"。
- V1 五件套按方向和初始化要求区分:
@State自身、@Prop拷贝下行、@Link引用双向、@Provide/@Consume跨层级、@Observed/@ObjectLink管第二层。 @Observed与@ObjectLink必须成对;@ObjectLink不能本地初始化。API 19 起后者可以接收复杂类型。- V2 的分工是"类
@ObservedV2、字段@Trace、组件@ComponentV2",@Local不可外部初始化,@Param只读,要改就抛@Event。 - 三种反模式值得背:派生状态存两份、
@Provide当单例、@Monitor里改被监听的变量。
相关主题
状态组织好之后,马上会遇到下一个问题:这一屏怎么进、怎么出、出去时怎么把结果带回来。《页面导航与路由:Navigation、路由与参数》讲 页面导航与路由:Navigation、路由与参数,把 NavPathStack 的入栈出栈、返回值、路由拦截和宽屏分栏串起来。本篇的 @Prop 与 @Param 边界,在那里会以"路由参数怎么传"的形式再出现一次。