sky_Qian
2026-11-12 10:48:59 发布「为什么我只改了一个商品的数量,整页都重绘了?」——这个问题在 ArkUI 项目里出现频率极高,而答案往往不在渲染代码,在状态模型。
一、先看清 V1 到底卡在哪
官方《状态管理概述》给出的解释很直接:状态管理 V1 使用代理观察数据,创建状态变量时会同时创建一个数据代理观察者。这个观察者能感知代理变化,但无法感知实际数据变化,于是带来四个限制:状态变量不能独立于 UI 存在,同一数据被多个视图代理时,一个视图的更改不会通知其他视图更新;只能感知对象属性第一层的变化,做不到深度观测;改对象属性或数组元素时存在冗余更新;装饰器之间配合限制多,组件里没有明确的输入与输出,不利于组件化。
V2 的思路是把可观察性放到数据本身:更改数据就触发相应视图更新,支持深度观测、属性级精准更新与数组元素的最小化更新。理解这句话,比记住十几个装饰器的名字更重要。
二、装饰器各管哪一段
依据官方 UI 装饰器总览与状态管理概述,V2 的分工是:@ObservedV2 装饰 class,使类具有被深度监听的能力;@Trace 装饰该类中的属性,被装饰的属性才具备深度观测能力——两者必须配合。@ComponentV2 装饰的 struct 里才能使用新装饰器;@Local 是组件内部状态,无法从外部初始化;@Param 是组件外部输入;@Once 需与 @Param 一起用,仅初始化时同步一次;@Event 规范组件输出;@Monitor 做状态变量修改的异步监听;@Computed 是计算属性,值变化时只计算一次;@Provider / @Consumer 做跨层双向同步。
注意 @ObservedV2 与 V1 的 @Observed 语义不同:前者本身不提供观察能力,仅代表「这个类可被观察」,真正可观察要靠 @Trace 标属性。
三、一个可运行的购物车模型
下面这段代码把购物车条目做成可观察类,数量变化只更新对应行,合计金额交给 @Computed:
// CartModel.ets
@ObservedV2
export class CartItem {
@Trace name: string;
@Trace price: number;
@Trace qty: number;
constructor(name: string, price: number, qty: number) {
this.name = name;
this.price = price;
this.qty = qty;
}
}
@ObservedV2
export class CartStore {
@Trace items: CartItem[] = [];
@Computed
get total(): number {
return this.items.reduce((sum, it) => sum + it.price * it.qty, 0);
}
add(name: string, price: number): void {
this.items.push(new CartItem(name, price, 1));
}
}
// CartPage.ets
@Entry
@ComponentV2
struct CartPage {
@Local store: CartStore = new CartStore();
build() {
Column() {
Button('加入一件商品')
.onClick(() => this.store.add('机械键盘', 399))
Text(`合计:¥${this.store.total.toFixed(2)}`)
.fontSize(20).fontWeight(FontWeight.Bold)
List() {
ForEach(this.store.items, (item: CartItem) => {
ListItem() {
CartRow({ item: item })
}
}, (item: CartItem) => item.name)
}
}.padding(16)
}
}
@ComponentV2
struct CartRow {
@Param item: CartItem = new CartItem('', 0, 0);
build() {
Row() {
Text(this.item.name).layoutWeight(1)
Text(`¥${this.item.price}`).margin({ right: 12 })
Button('+').onClick(() => { this.item.qty += 1; })
Text(`${this.item.qty}`).margin({ left: 8, right: 8 })
}.padding(12)
}
}关键在于 CartRow 用 @Param 接收的是引用而非拷贝。官方 V1-V2 迁移概述特别对比过:@Prop 是深拷贝,@Param 是引用。因此子组件里改 this.item.qty 会直接落到 store 里的同一个对象上,@Trace 捕获到属性变化后只刷新依赖该属性的视图,@Computed total 也随之重算一次。
原创结论:如果把这个模型用 V1 的 @State + @ObjectLink 表达,同样的交互需要显式维护嵌套观察链路;而 V2 的收益不只是代码短,更重要的是「数据可以被多个视图共享且互不丢通知」这一点,恰好命中官方列出的 V1 第一条限制。对有跨页面共享购物车/播放器状态的业务,这才是迁移 V2 最实际的理由。
补充一点关于监听与计算的选择。@Monitor 用于状态变量修改的异步监听,@SyncMonitor 是同步监听,两者都在官方 UI 装饰器总览的 V2 列表里;@Computed 则是计算属性,值变化时只计算一次,主要用于解决 UI 多次复用同一属性时重复计算带来的性能问题。在这个购物车里,合计金额用 @Computed 而不是在 build 里现场 reduce,就是这个道理——列表滚动时 build 可能被频繁执行,而合计只依赖 items 的变化。如果业务需要在数量变化时打日志或埋点,用 @Monitor 监听 qty 比在 onClick 里散落埋点更集中,也更容易覆盖「通过其他入口改数量」的场景,比如从详情页加购、从通知栏快捷操作加购。数据可观察之后,观察点应该收敛到模型层,而不是继续挂在各个 UI 事件上,这也是 V2 相对 V1 在架构上更舒服的地方。
四、一条不能越过的线
官方英文版状态管理概述列了明确的约束:V1 与 V2 不能混用。@ComponentV2 的自定义组件里不得使用 @State、@Prop、@Link 等 V1 装饰器;@Component 的组件里不得使用 @Local、@Param 等 V2 装饰器;@Component 与 @ComponentV2 不能同时使用;也不能把 @ObservedV2 装饰的类实例交给 V1 的 @State 等变量,或把 @Observed 装饰的类实例交给 @Param。混用可能导致未定义行为,包括冗余重渲染以及深度观测、属性级更新能力的丢失。
这条约束的工程落地建议是:以组件为粒度分批迁移,而不是以文件为粒度逐个改装饰器。同一个组件内部半 V1 半 V2 是最危险的状态。可以先从叶子组件开始整体换成 @ComponentV2,逐步向父组件收敛,每收敛一层跑一次回归。
五、小结
V2 不是「新语法」,而是把可观察性从 UI 代理挪回数据本身。写的时候记住三件事:@ObservedV2 配 @Trace 才生效;@Param 传引用、改属性会回写;V1/V2 绝不混用。代码示例改写自官方文档所述装饰器语义,本环境未安装 DevEco Studio,未做实机编译验证,落地前请在目标 SDK 下编译一次。
暂无评论数据
发布
相关推荐
813
0
720
0
708
0
1018
0
sky_Qian
我还没有写个人简介......
帖子
提问
粉丝
HarmonyOS 7 已发布两个月:目标 SDK 升到 API 26 的时间窗口该怎么排
2026-11-12 10:53:27 发布状态管理 V2 实战:用 @ObservedV2 与 @Trace 把购物车刷新压到属性级
2026-11-12 10:48:59 发布


京公网安备:11010502051901号