Skip to content

状态管理:@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 实例,从而建立双向绑定。

它解决的问题很具体: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 接:

arkts
@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。数据带观察能力,输入只读,修改走事件:

arkts
@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 的观察边界。

arkts
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 边界,在那里会以"路由参数怎么传"的形式再出现一次。