sky_Qian
2026-11-12 10:52:00 发布迁移状态管理框架时,最危险的不是「不会写新语法」,而是「照着旧语义写了新语法」。官方《V1-V2 迁移概述》里有一条对比,值得贴在工位上:@Prop 是深拷贝,@Param 是引用。同一个交互,换完装饰器行为就变了,而且不会报错。
一、官方给出的对照关系
按官方迁移文档整理:
| V1 | V2 | 需要注意 |
|---|---|---|
@State(无外部初始化) | @Local | 两者都是数据源概念,不需外部传入时可直接迁移 |
@State(需外部初始化一次) | @Param + @Once | @Once 必须与 @Param 一起用 |
@Prop | @Param | @Prop 深拷贝,@Param 引用;复杂类型行为不同 |
@Link | @Param + @Event | V2 没有框架封装的双向同步,需自己实现 |
@Observed | @ObservedV2 | 能力不等价:@Observed 可观察第一层属性且需配 @ObjectLink;@ObservedV2 本身不观察,需配 @Trace |
@ObjectLink / @Track | @ObservedV2 + @Trace | 用于嵌套类观察场景 |
@Provide / @Consume | @Provider / @Consumer | 官方标注为兼容 |
@Watch | @Monitor | 前者是 V1 监听,后者为 V2 深度监听(另还有同步监听的 @SyncMonitor) |
还有一个容易被跳过的条目:如果使用滚动组件关联的 WaterFlowSections / ChildrenMainSize,官方迁移文档指出需要使用 makeObserved。这类「不在装饰器表里但要额外处理」的点,往往是迁移后列表不刷新的真因。
二、@Link 的等价实现要自己写
V1 里父子双向同步一行 @Link 搞定;V2 用 @Param 接输入、@Event 出事件,由父组件决定怎么改。下面是一组完整的前后对照:
// ---------- 迁移前:V1 ----------
@Component
struct V1Counter {
@Link count: number;
build() {
Button(`V1: ${this.count}`).onClick(() => { this.count += 1; })
}
}
// ---------- 迁移后:V2 ----------
@ComponentV2
struct V2Counter {
@Param count: number = 0;
@Event onCountChange: (next: number) => void = () => {};
build() {
Button(`V2: ${this.count}`)
.onClick(() => { this.onCountChange(this.count + 1); })
}
}
@Entry
@ComponentV2
struct CounterPage {
@Local count: number = 0;
build() {
Column() {
V2Counter({
count: this.count,
onCountChange: (next: number) => { this.count = next; }
})
Text(`父组件当前值:${this.count}`)
}.padding(16)
}
}注意子组件里不要直接写 this.count += 1。@Param 是输入,改它并不会按 V1 的 @Link 语义回写父级;统一走 @Event 才能让数据流方向清晰。官方状态管理概述把「在组件中明确输入与输出,有利于组件化」列为 V2 的优点,这段写法就是它的具体体现。
三、最容易出线上问题的一处:深拷贝变引用
假设 V1 里父组件用 @Prop 把一个复杂对象传给子组件,子组件内部改了对象字段但没回传,父组件不受影响——这是深拷贝带来的隔离。换成 @Param 之后,拿到的是同一个引用,子组件里的赋值会直接改到父组件的数据上。
这个变化不会抛异常,也不会有编译告警,只会表现为「某个页面莫名被改了」。我们的建议是把迁移切成一个显式的核查步骤:
- 全量搜索
@Prop,逐个确认该参数在子组件内是否被写入; - 若被写入且业务上不该影响父级,在 V2 里显式做一次拷贝(例如构造新对象再传给
@Param),或改用@Param @Once固定初始快照; - 若本来就需要回写,正好借机改成
@Param+@Event的显式通道,并把这条数据流的方向写进组件注释。
原创观察:很多迁移指南把 @Prop → @Param 列成「对应关系」就结束了,但语义差异恰恰是最需要人工评审的部分。迁移工作量应该按「被写入的 @Prop 数量」估算,而不是按「装饰器总数」估算——前者通常只占后者的很小一部分,却能覆盖绝大多数回归缺陷。
还有两个不太起眼但容易出错的落点。一是 @Once:官方明确它必须与 @Param 一起使用,仅初始化时同步一次,适合「父组件给个初始值、之后子组件自己维护」的场景,不要把它当成 @Prop 的等价替代。二是 @Provide / @Consume 到 @Provider / @Consumer 被官方标注为兼容,迁移成本较低,但跨层双向同步的链路变长,建议迁移后专门验证一次深层组件的状态回写。我们把回归重点放在三处:被写入的 @Prop、@Link 拆出的事件回调、以及使用 WaterFlowSections / ChildrenMainSize 的滚动列表,因为它们分别对应语义变化、数据流重建和 makeObserved 的额外要求。相比之下,纯展示型的 @State 换 @Local 几乎不需要回归,把测试预算倾斜到前三类,比平均用力更有效率。
四、别把两套东西放在一个组件里
官方英文版状态管理概述明确禁止 V1/V2 混用:@ComponentV2 内不得使用 @State/@Prop/@Link 等;@Component 内不得使用 @Local/@Param 等;两者不能同时装饰同一组件;@ObservedV2 类实例不能交给 V1 状态变量,反之亦然。混用可能带来未定义行为,包括冗余重渲染以及深度观测、属性级更新能力的丢失。
因此推荐以「组件树的一整棵子树」为迁移单元:从叶子开始,整棵子树换完再往上接。跨子树边界传值时,宁可多写一层 @Event,也不要在边界上混搭。
五、小结
迁移不是替换关键字。@State 分两种落法,@Link 要拆成输入与输出,@Prop 到 @Param 藏着语义变化,滚动组件还有 makeObserved 的额外要求。代码示例依据官方迁移文档所述语义编写,本环境未安装 DevEco Studio,未做实机编译验证;建议在目标工程里先用一个低风险页面试跑,再批量推进。
暂无评论数据
发布
相关推荐
sky_Qian
1
0
调试的少年A
1125
0
程序人生下半场
2499
0
在人间耕耘
4469
0
栀枝夏
4437
0
sky_Qian
我还没有写个人简介......
帖子
提问
粉丝
HarmonyOS 7 已发布两个月:目标 SDK 升到 API 26 的时间窗口该怎么排
2026-11-12 10:53:27 发布状态管理 V2 实战:用 @ObservedV2 与 @Trace 把购物车刷新压到属性级
2026-11-12 10:48:59 发布


京公网安备:11010502051901号