logo
积分中心
V1 迁 V2 装饰器对照表:@State、@Prop、@Link 各自落到哪里 原创
头像 sky_Qian 2026-11-12 10:52:00    发布
1 浏览 0 收藏

迁移状态管理框架时,最危险的不是「不会写新语法」,而是「照着旧语义写了新语法」。官方《V1-V2 迁移概述》里有一条对比,值得贴在工位上:@Prop 是深拷贝,@Param 是引用。同一个交互,换完装饰器行为就变了,而且不会报错。

一、官方给出的对照关系

按官方迁移文档整理:

V1V2需要注意
@State(无外部初始化)@Local两者都是数据源概念,不需外部传入时可直接迁移
@State(需外部初始化一次)@Param + @Once@Once 必须与 @Param 一起用
@Prop@Param@Prop 深拷贝,@Param 引用;复杂类型行为不同
@Link@Param + @EventV2 没有框架封装的双向同步,需自己实现
@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 之后,拿到的是同一个引用,子组件里的赋值会直接改到父组件的数据上。

这个变化不会抛异常,也不会有编译告警,只会表现为「某个页面莫名被改了」。我们的建议是把迁移切成一个显式的核查步骤:

  1. 全量搜索 @Prop,逐个确认该参数在子组件内是否被写入;
  2. 若被写入且业务上不该影响父级,在 V2 里显式做一次拷贝(例如构造新对象再传给 @Param),或改用 @Param @Once 固定初始快照;
  3. 若本来就需要回写,正好借机改成 @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,未做实机编译验证;建议在目标工程里先用一个低风险页面试跑,再批量推进。


©本站发布的所有内容,包括但不限于文字、图片、音频、视频、图表、标志、标识、广告、商标、商号、域名、软件、程序等,除特别标明外,均来源于网络或用户投稿,版权归原作者或原出处所有。我们致力于保护原作者版权,若涉及版权问题,请及时联系我们进行处理。
分类
HarmonyOS

暂无评论数据

加载中...

发布

头像

sky_Qian

我还没有写个人简介......

21

帖子

0

提问

1

粉丝

关注
地址:北京市朝阳区北三环东路三元桥曙光西里甲1号第三置业A座1508室 电话:13391790444或(010)62178877
版权所有:电脑商情信息服务集团 北京赢邦策略咨询有限责任公司
声明:本媒体部分图片、文章来源于网络,版权归原作者所有,我司致力于保护作者版权,如有侵权,请与我司联系删除

京ICP备:2022009079号-2

京公网安备:11010502051901号

ICP证:京B2-20230255