MoonInkHarmonyOS 6
元服务
V2 状态管理 @Monitor 和 @Computed 不触发
从 V1 状态管理迁移到 V2,用了 @ObservedV2 + @Trace + @Monitor + @Computed,但遇到几个问题:
给 model 类加了 @ObservedV2,属性加了 @Trace,但 @Monitor 回调死活不触发
@Computed计算属性返回的值在 UI 上不更新,手动打印发现值已经变了但界面没刷新
@Monitor 监听多个属性时,只写了属性名没写路径,部分属性变化捕获不到
北墨NoLimit
你好,这几个现象通常都是 V2 观测链或监听路径不完整导致的:
-
@ObservedV2只表示类可被观测;实际变化、参与@Computed计算的字段仍需加@Trace。嵌套对象的类也需使用@ObservedV2。 -
@Computed只能装饰 getter,并且只有其读取的 V2 状态变量变化时才重新计算。若依赖的是普通字段,直接打印 getter 可能是新值,但缓存的计算属性和 UI 不会更新。 -
UI 需要实际读取计算属性,例如
Text(this.model.fullName),才能建立刷新依赖。 -
@Monitor路径相对于其声明位置填写:-
声明在组件中:
@Monitor('model.name', 'model.age') -
声明在
model类中:@Monitor('name', 'age')
多个路径应作为多个参数传入,不能只写叶子属性名或写成一个逗号字符串。
-
-
构造函数、状态初始化阶段的赋值不会触发
@Monitor;它是异步监听,同一事件中最终值若与初始值相同,也不会触发。
可参考如下示例:
@ObservedV2
class UserModel {
@Trace firstName: string = '';
@Trace lastName: string = '';
@Computed
get fullName(): string {
return `${this.firstName} ${this.lastName}`;
}
}
@Entry
@ComponentV2
struct Page {
@Local model: UserModel = new UserModel();
@Monitor('model.firstName', 'model.lastName')
onNameChanged(_monitor: IMonitor): void {
}
build() {
Text(this.model.fullName)
}
}官方资料:
希望有帮助!
慢行
- 当一个类中存在对一个属性的多次监听时,只有最后一个定义的监听方法会生效。
- 当@Monitor传入多个路径参数时,以参数的全拼接结果判断是否重复监听。全拼接时会在参数间加空格,以区分不同参数。例如,'ab', 'c'的全拼接结果为'ab c','a', 'bc'的全拼接结果为'a bc',二者全拼接不相等。以下示例中,Monitor 1、Monitor 2与Monitor 3都监听了name属性的变化。由于Monitor 2与Monitor 3的入参全拼接相等(都为'name position'),因此Monitor 2不生效,仅Monitor 3生效。
- @Monitor的参数需要为监听属性名的字符串,仅可以使用字符串字面量、const常量、enum枚举值作为参数。如果使用变量作为参数,仅会监听@Monitor初始化时,变量值所对应的属性。当更改变量时,@Monitor无法实时改变监听的属性,即@Monitor监听的目标属性从初始化时便已经确定,无法动态更改。
- @Monitor中再次更改被监听的属性
@Computed装饰器计算属性返回的值在 UI 上不更新,手动打印发现值已经变了但界面没刷新。排查如下:
- @Computed为方法装饰器,仅能装饰getter方法。
- @Computed装饰的方法只有在初始化,或者其被计算的状态变量改变时,才会发生重新计算。不建议开发者在@Computed装饰的getter方法中做除获取数据外其余的逻辑操作。 收起自动换行深色代码主题复制
@Entry @ComponentV2 struct Page { @Local firstName: string = 'Hua'; @Local lastName: string = 'Li'; @Local showFullNameRequestCount: number = 0; private fullNameRequestCount: number = 0; @Computed get fullName() { console.info('fullName'); // 不建议在@Computed的计算中做赋值逻辑,因为@Computed本质是一个getter访问器,用来节约重复计算 // 在这个例子中,fullNameRequestCount仅代表@Computed计算次数,不能代表fullName被访问的次数 this.fullNameRequestCount++; return this.firstName + ' ' + this.lastName; } build() { Column() { Text(`${this.fullName}`) // 获取一次fullName .fontSize(20) .margin(10) Text(`${this.fullName}`) // 获取一次fullName,累计获取两次fullName,但是fullName不会重新计算,读取缓存值 .fontSize(20) .margin(10) // 点击Button,获取fullNameRequestCount次数 Text(`count ${this.showFullNameRequestCount}`) .fontSize(20) .margin(10) Button('get fullName') .width(300) .margin(10) .onClick(() => { this.showFullNameRequestCount = this.fullNameRequestCount; }) } .width('100%') } } - 在@Computed装饰的getter方法中,不能改变参与计算的属性,以防止重复执行计算属性导致的appfreeze。
- @Computed不能和双向绑定!!连用,@Computed装饰的是getter访问器,不会被子组件同步,也不能被赋值。开发者自己实现的计算属性的setter不生效,且产生编译时报错。
- @Computed为状态管理V2提供的能力,只能在@ComponentV2和@ObservedV2中使用。
- 多个@Computed一起使用时,警惕循环求解,以防止计算过程中的死循环。
不羁的木木这几个问题基本都集中在一个点:V2 的响应式链路必须完整,@ObservedV2、@Trace、@Monitor、@Computed 各自负责的事情不一样。官方当前文档也明确把它们分别定义为类属性观测、监听和计算属性能力。
先看一张关系图
@ObservedV2
│
└── 标记这个 class 可被状态管理框架观测
│
↓
@Trace
│
└── 真正参与属性变化追踪
│
┌──────────┴──────────┐
↓ ↓
@Monitor UI刷新
监听属性变化 精准更新相关组件
│
↓
@Computed
派生/计算状态1.@Monitor 不触发,先检查 @Trace
仅仅这样是不够的:
@ObservedV2
class User {
name: string = ''
age: number = 0
}应该是:
@ObservedV2
class User {
@Trace name: string = ''
@Trace age: number = 0
}@ObservedV2 本身不是“把所有属性自动变成可观察属性”,需要和 @Trace 配合使用。官方迁移文档也是按照 @ObservedV2 + @Trace 替换 V1 @Observed + @Track 的。
另外,使用 @Monitor 的组件需要是 @ComponentV2:
@ComponentV2
struct UserView {
@Local user: User = new User()
@Monitor('user.name')
onNameChange(monitor: IMonitor) {
console.info(`name changed`)
}
}2.@Computed 值变了,但 UI 不刷新
这里最容易误判。
@Computed 本身只是“计算属性”,它依赖的源数据必须是可观察状态。
例如:
@ObservedV2
class User {
@Trace firstName: string = 'Tom'
@Trace lastName: string = 'Lee'
}
@ComponentV2
struct Index {
@Local user: User = new User()
@Computed
get fullName(): string {
return `${this.user.firstName} ${this.user.lastName}`
}
build() {
Text(this.fullName)
}
}这里 fullName 依赖的是 user.firstName 和 user.lastName。
因此:
firstName / lastName
│
│ @Trace
↓
状态变化
↓
@Computed重新计算
↓
使用fullName的UI刷新如果你打印发现 Computed 返回值已经变了,但界面没变化,重点检查两件事:
@Computed内部读取的属性是不是@Trace- UI 是否真的读取了这个
@Computed属性
尤其不要把依赖数据复制成普通变量后再计算,例如:
let name = this.user.name
@Computed
get title(): string {
return name
}这里 name 已经脱离响应式依赖了,user.name 后续变化自然无法驱动这个计算属性。
官方对 V2 的定义也是“数据本身可观察”,@Computed 在依赖值变化时重新计算。
3.@Monitor 多属性监听不要只写变量名
这个也是 V1 迁移到 V2 时很容易踩的坑。
例如实际数据是:
@Local user: User = new User()而 User:
@ObservedV2
class User {
@Trace name: string = ''
@Trace age: number = 0
}监听具体属性应该写路径:
@Monitor('user.name')
onNameChange() {
}
@Monitor('user.age')
onAgeChange() {
}而不是只写:
@Monitor('name')
@Monitor('age')因为你真正监听的数据源是 user.name、user.age。
V2 的 @Monitor 支持深度监听,官方术语里也明确称为 Deep Monitor,可以递归监听对象或数组的嵌套属性。
4. 迁移 V1 时不要机械替换
可以直接按这个关系检查:
| V1 | V2 | 注意点 |
|---|---|---|
|
|
| class |
|
|
| 属性 |
|
|
| 监听 |
|
|
| V2 状态管理 |
|
|
| 本地状态 |
|
|
| 双向同步 |
| 普通派生变量 |
| 依赖必须可观察 |
官方迁移文档目前也是这个方向。
最后给一个排查顺序
遇到“@Monitor 不触发 / @Computed 不更新 / UI 不刷新”,按这个顺序查最快:
@ComponentV2
↓
数据对象是否 @ObservedV2
↓
被依赖的属性是否 @Trace
↓
修改的是不是这个被观察对象本身
↓
@Monitor 路径是否正确
↓
@Computed 是否直接读取了响应式数据
↓
UI 是否实际读取了 @Computed特别是 V1 → V2 迁移,最常见的问题就是只把 @Observed 改成 @ObservedV2,却漏掉 @Track → @Trace,或者 @Watch → @Monitor 后仍然按照 V1 的属性路径写法处理。这样就会出现“数据明明变了,监听和 UI 却没反应”的情况。
蓝瘦的蜕变
V1 转 V2 状态管理时,三类常见问题的快速排查要点如下:
- @Monitor 回调不触发:需用 @ComponentV2/ObservedV2 装饰器,监听属性及嵌套层级需加@Trace/@ObservedV2,对象必须通过 new 实例化,避免 V1/V2 装饰器混用。
- @Computed 不刷新 UI:仅在 @ComponentV2/ObservedV2 中生效,getter 依赖的属性需是可观察类型(加 @Trace),确保嵌套链路可观察、对象通过 new 构造。
- 监听路径捕获不全:嵌套属性需写完整路径(如 form.address.city),仅监听自身属性时直接写属性名;优先监听 @Trace 修饰的属性,避免普通变量。
另外,承载这些逻辑的组件应使用 @ComponentV2;UI 刷新不需要靠 @Monitor 手动转发,@Computed 的依赖正确就能自行更新。规则对应官方的 V2 计算属性说明。
仙银
三个问题根因不同,但都跟 V2 的观测机制和路径语法有关。
问题一:@Monitor 不触发
最常见的原因有两个:
-
在 @ComponentV2 组件里用 @Monitor 监听类属性时,必须写完整路径,不能只写属性名。比如你有一个 @Local user: UserModel,想监听 user 的 name 属性变化,必须写
@Monitor('user.name'),而不是@Monitor('name')。只有 @Monitor 写在 @ObservedV2 类内部时才能只写属性名@Monitor('name')。 -
被监听的属性必须被 @Trace 装饰。没加 @Trace 的普通属性即使变了也监听不到。另外类实例必须通过 new 创建,没走 new 的实例观测不生效。
还有一个容易踩的坑:同一属性在同一个类中被多个 @Monitor 监听时,只有最后定义的那个生效。比如 @Monitor('name') onA() 和 @Monitor('name') onB() 同时存在,只有 onB 会触发。
文档参考:@Monitor装饰器、@Monitor常见问题
问题二:@Computed 值变了但 UI 不刷新
值已经变了说明 @Computed 重新计算了,问题出在组件没有感知到变化。最可能的原因是:@Computed 依赖了非状态变量。官方文档明确说了,只有参与计算的状态变量变化才会触发 @Computed 重新计算,如果 getter 里读了一个没加 @Trace 的属性,那个属性变了 @Computed 不会重算,UI 自然不更新。
另外一种情况:类实例不是组件的状态变量。虽然 @Trace 本身支持深度观测,但如果实例只是普通成员变量(没加 @Local/@Param),某些场景下组件可能无法正确追踪 @Computed 的变化。建议把类实例声明为 @Local。
还有一种:@Computed 在 @ObservedV2 类中是异步初始化的,如果赋值发生在组件创建之前(比如在类的 constructor 里),@Computed 的依赖追踪还没建立,UI 不会刷新。把初始赋值挪到 aboutToAppear 里就好。
文档参考:@Computed装饰器
问题三:@Monitor 监听多属性只写属性名,部分变化捕获不到
这就是路径语法的问题。@Monitor 的路径规则:
- 在 @ObservedV2 类内部:写属性名就行,如
@Monitor('name', 'age')。监听嵌套属性用点号路径,如@Monitor('detail.city') - 在 @ComponentV2 组件内:必须从状态变量名开始写完整路径,如
@Monitor('user.name', 'user.age')。嵌套属性写@Monitor('user.detail.city') - 数组用点号索引:
@Monitor('list.0.name')而不是list[0].name - 监听数组整体只能感知整体赋值,监听数组长度用
@Monitor('list.length')
只写属性名在组件里是监听不到的,因为组件的 @Monitor 需要从状态变量出发建立监听路径。
文档参考:@Monitor深层监听
最小验证 demo,三个问题都能跑通:
@ObservedV2
class Detail {
@Trace city: string = 'Beijing'
}
@ObservedV2
class UserModel {
@Trace name: string = 'Tom'
@Trace age: number = 18
@Trace detail: Detail = new Detail()
@Monitor('name', 'age')
onFieldChange(monitor: IMonitor) {
monitor.dirty.forEach((path: string) => {
console.info(`[Class] ${path}: ${monitor.value(path)?.before} -> ${monitor.value(path)?.now}`)
})
}
@Monitor('detail.city')
onDeepChange(monitor: IMonitor) {
console.info(`[ClassDeep] detail.city: ${monitor.value('detail.city')?.before} -> ${monitor.value('detail.city')?.now}`)
}
@Computed
get info(): string {
return `${this.name}, age ${this.age}, from ${this.detail.city}`
}
}
@Entry
@ComponentV2
struct Index {
@Local user: UserModel = new UserModel()
@Monitor('user.name', 'user.age')
onUserFieldChange(monitor: IMonitor) {
monitor.dirty.forEach((path: string) => {
console.info(`[Component] ${path}: ${monitor.value(path)?.before} -> ${monitor.value(path)?.now}`)
})
}
@Monitor('user.detail.city')
onDeepFieldChange(monitor: IMonitor) {
console.info(`[ComponentDeep] ${monitor.value('user.detail.city')?.before} -> ${monitor.value('user.detail.city')?.now}`)
}
build() {
Column({ space: 12 }) {
Text(this.user.info)
.fontSize(24)
.margin(20)
Button('change name').onClick(() => { this.user.name = 'Jerry' })
Button('change age').onClick(() => { this.user.age = 20 })
Button('change city').onClick(() => { this.user.detail.city = 'Shanghai' })
}
.width('100%')
.height('100%')
}
}
飞b6这三个现象基本都和 V2 的“依赖追踪”规则有关。先抓住一句:
@ObservedV2只是让类进入 V2 观察体系;真正能够触发依赖更新的是@Trace字段。@Monitor要监听正确的状态路径,@Computed也必须通过可追踪依赖建立响应关系。
1. @ObservedV2 加了,为什么 @Monitor 还是不触发?
例如:
@ObservedV2
class UserModel {
@Trace name: string = ''
@Trace age: number = 0
@Monitor('name')
onNameChanged(monitor: IMonitor) {
console.info('name changed')
}
}修改:
this.user.name = 'Tom'这类才是标准链路:
@ObservedV2
↓
@Trace name
↓
name发生变化
↓
@Monitor('name')常见错误是:
@ObservedV2
class UserModel {
name: string = '' // 没有 @Trace
@Monitor('name')
onChanged() {}
}@ObservedV2 并不会自动把类中所有普通属性变成可观察字段。
所以:
@ObservedV2 ≠ 所有字段自动响应式需要观察:
@Trace name: string = ''2. 更容易踩的是“改错对象实例”
例如:
const user1 = new UserModel()
const user2 = new UserModel()
this.user = user1页面和 Monitor 实际关联:
user1但业务代码:
user2.name = 'Tom'当然不会触发当前页面预期的更新。
迁 V2 后尤其建议确认:
UI → Model A
Repository → Model B是不是无意中创建了两份对象。
这种问题日志里特别迷惑,因为:
console.info(user2.name)确实已经变了,但 UI 观察的是 user1。
3. 嵌套对象是 @Monitor 最容易写错的地方
例如:
@ObservedV2
class Address {
@Trace city: string = ''
}
@ObservedV2
class User {
@Trace address: Address = new Address()
}如果真正需要监听:
user.address.city就要区分:
address 这个引用变化
和
address.city 变化这是两件事。
比如:
this.user.address =
new Address()修改的是:
address而:
this.user.address.city = '深圳'修改的是:
address.city因此 Monitor 的路径必须对应你真正关心的字段。
如果 Monitor 位于持有 user 的组件/对象中,可能需要监听类似:
@Monitor('user.address.city')而不是只写:
@Monitor('city')因为:
city不是当前作用域的直接状态字段。
4. 监听多个字段,要写完整依赖路径
例如页面:
@ComponentV2
struct UserPage {
@Local user: User = new User()
@Monitor(
'user.name',
'user.address.city'
)
onUserChanged(monitor: IMonitor) {
console.info('user changed')
}
}不要想当然写:
@Monitor('name', 'city')因为 Monitor 路径是从当前装饰器所在作用域解析的。
可以理解成:
UserPage
│
└── user
├── name
└── address
└── city所以对应:
user.name
user.address.city路径不完整,就可能出现你说的:
有的属性变化能捕获,有的捕获不到。
5. @Computed 不更新,先查依赖是不是 @Trace
例如:
@ObservedV2
class Order {
@Trace price: number = 100
@Trace count: number = 2
@Computed
get totalPrice(): number {
return this.price * this.count
}
}UI:
Text(`总价:${this.order.totalPrice}`)修改:
this.order.count = 3链路应该是:
@Trace count
↓
Computed依赖失效
↓
totalPrice重新计算
↓
读取totalPrice的UI刷新如果写成:
@ObservedV2
class Order {
price: number = 100
count: number = 2
@Computed
get totalPrice(): number {
return this.price * this.count
}
}那么:
price/count并没有进入正确的 V2 追踪链。
即使你手动:
console.info(`${this.order.totalPrice}`)打印得到新值,也只能证明:
getter 重新执行时算出来是新的。
不能证明:
ArkUI 知道什么时候应该重新执行它。
这是你第二个现象最值得检查的地方。
6. @Computed 不要依赖“响应式体系外”的普通数据
例如:
let globalDiscount = 0.8
@ObservedV2
class Order {
@Trace price: number = 100
@Computed
get total(): number {
return this.price * globalDiscount
}
}修改:
globalDiscount = 0.5然后你手动:
console.info(`${order.total}`)当然会算出:
50但 UI 不知道:
globalDiscount发生变化。
因此 Computed 最好依赖明确的响应式状态:
@Trace discount: number = 0.8而不是:
普通全局变量
普通 static
普通 singleton 字段
未观察的普通 class 字段7. 不要在 @Computed 里面做副作用
比如:
@Computed
get total(): number {
this.requestData() // ❌
this.cache = xxx // ❌
console大量日志 // 不推荐
return ...
}Computed 应该尽量是:
输入状态
↓
纯计算
↓
派生值例如:
@Computed
get displayName(): string {
return `${this.firstName} ${this.lastName}`
}不要把它当生命周期回调。
8. @Monitor 也不要承担“所有业务状态同步”
例如:
@Monitor('user.name')
onChanged() {
this.saveDatabase()
this.requestNetwork()
this.updateAnotherStore()
}如果状态连续变化:
A
→ B
→ C
→ DMonitor 可能变成一个非常重的隐式副作用入口。
更推荐:
@Monitor
→ 轻量派生/校验/通知
明确业务操作
→ Repository / Service尤其网络请求不要因为某个 @Trace 字段每次变化就自动发。
一个最小正确模型
你可以先拿下面这种结构验证:
@ObservedV2
class Student {
@Trace firstName: string = ''
@Trace lastName: string = ''
@Trace age: number = 18
@Computed
get fullName(): string {
return `${this.firstName} ${this.lastName}`
}
@Monitor('age')
onAgeChanged(monitor: IMonitor): void {
console.info(`age changed`)
}
}页面:
@Entry
@ComponentV2
struct Index {
@Local student: Student = new Student()
build() {
Column() {
Text(this.student.fullName)
Text(`${this.student.age}`)
Button('修改')
.onClick(() => {
this.student.firstName = '张'
this.student.lastName = '三'
this.student.age = 20
})
}
}
}如果这个最小模型正常,而你的业务模型不正常,就沿着:
① 是否真的是 @Trace
② Monitor路径是否正确
③ Computed依赖是否全部可追踪
④ 是否修改了另一份Model实例
⑤ 中间有没有普通对象断掉观察链往下查。
你这三个问题可以分别这样定性
@Monitor 完全不触发:
优先检查:
被监听字段是否 @Trace
→ Monitor所在作用域
→ path是否正确
→ 修改的是否同一个实例@Computed 手动打印变了但 UI 不变:
这个现象非常典型,说明 getter 本身没有问题,重点查:
Computed读取的所有依赖
是否属于V2可追踪状态“重新读取能算出新值”和“状态变化能主动通知 UI 重新读取”是两回事。
监听多个属性部分漏掉:
不要只写末级属性名。按 @Monitor 所在对象/组件为起点,把路径写完整,例如:
user.name
user.address.city
config.theme.mode最后可以记成一条 V2 状态链:
@ObservedV2
↓
@Trace
↓
状态变化
↙ ↘
@Monitor @Computed失效
↓
依赖它的UI刷新V2 迁移最容易犯的错误,就是只把 V1 装饰器名字替换了,却没有重新建立这条字段级依赖链。
小草飞上天开发者你好:
针对你这几个问题,一一回复一下:
1、@Monitor 回调死活不触发
根据官方文档,@Monitor 的回调要触发,必须同时满足以下条件,你针对性排查一下:
| 条件 | 说明 |
|---|---|
组件必须是 @ComponentV2 | 在 V1 的 @Component 里用 V2 状态管理,@Monitor 不会生效 |
| 被监听的必须是状态变量 | 即 @Local、@Param、@Provider、@Consumer 或 @Computed |
@ObservedV2 实例必须通过 new 创建 | 不能是 JSON.parse 或 Object.assign 得到的普通对象 |
变化的字段必须加 @Trace | 没有 @Trace 的属性,@Monitor 无法感知其变化 |
@Monitor 参数必须是字符串字面量 | 不能用变量作为参数 |
2、@Computed 值变了但 UI 不刷新
@Computed 只会跟踪 getter 中实际读取到的可观测依赖。如果 getter 里读取的某个属性不是 @Trace 字段,或者依赖链上有一层不是 V2 可观测数据,@Computed 就不会在那些属性变化时重新计算。
3、可能是@Monitor 监听多个属性时路径写错
@Monitor 支持同时监听多个属性,属性之间用逗号分隔。但关键是:每个属性都必须写完整路径,不能只写属性名。
星桥似海@Monitor 与 @Computed 只能观察 V2 响应式源:被 @Local、@Param、@Provider、@Consumer 装饰的变量,以及 @ObservedV2 类中被 @Trace 修饰的属性。它们不能观察 V1 的 @State/@Prop,也不能观察普通类字段或函数内局部变量。常见“不触发”原因如下:
1. 观察对象是普通 @State 或局部变量 → 根本没接入 V2 响应式系统。
2. 观察的是“派生值”而非“源”。@Monitor 监听源的变化;想监听 getter 结果,应监听它依赖的 @Trace 字段。
3. @Computed getter 里读取了非响应式值(普通字段、V1 状态),依赖链断裂导致不重算。
4. 嵌套对象没用 @ObservedV2 + @Trace 包裹,属性变化不被感知。
5. @Monitor 用 Object.is 比较,引用没变时不触发(例如监听的是数组本身,却只在内部 push;应监听数组或对该层加 @Trace)。
@ObservedV2
class User {
@Trace name: string = 'A';
@Trace age: number = 1;
}
@ComponentV2
struct Page {
@Local u: User = new User();
@Computed get info(): string { return this.u.name + this.u.age; }
build() {
Column() {
// 监听嵌套属性变化
Text(this.info).onClick(() => { this.u.age++; }) // @Computed 自动重算
}
}
}排查步骤:① 确认被观察变量是 @Local/@Param/@Trace 之一;② @Monitor(() => this.x.y) 里 x 必须是 @ObservedV2 实例、y 是 @Trace;③ 用 console.info 在赋值处确认确实执行且值变化。
大雷神@Monitor 与 @Computed 不触发的断点定位
三条现象是三个独立机制:@Monitor 不触发多在监听根不是状态变量、目标属性没有 @Trace、变化方式不在监听范围内;@Computed 值变而 UI 不动多在依赖不可观测或 build 没读它;多属性漏听还牵涉同属性重复监听去重。
根因机制
官方《@Monitor装饰器》的判定顺序:
- 组件内监听目标必须被 @Local、@Param、@Provider、@Consumer、@Computed 装饰,"未被状态变量装饰器装饰的变量在变化时无法被监听"。故目标不存在或只是普通成员变量时,
@Monitor('name')、@Monitor('user.name')都不触发(目标若是从状态变量派生的普通 getter,官方反例显示仍可能被连带触发)——写全路径只是必要条件。 - 类内监听要求 @ObservedV2 类 + @Trace 属性:未被 @Trace 装饰的属性变化监听不到,也不允许在未被 @ObservedV2 装饰的类中使用 @Monitor;监听对象整体只感知整体赋值。
- 默认监听不到 Array、Map、Date、Set 的 API 调用变化,监听整体数组只在整体赋值时触发;数组增删要监听 length,或用 API 26.0.0 起的通配符路径;变量可访问↔不可访问切换默认不触发(需 API 20 的 addMonitor 或 API 26 配置项)。
- 判等用严格相等,赋相同值不触发;一次事件内多次改同一属性按初值、终值比较,改回原值也不触发。
- 生效时机:类中 @Monitor 在实例创建完成后生效(晚于 constructor、早于 aboutToAppear),故构造函数里赋值监听不到;组件中 @Monitor 随状态变量初始化生效、销毁即失效。
实例可观测性还要求:@ObservedV2 类经 new 实例化才有观测能力;JSON.stringify 会给 @Trace 属性加 __ob_ 前缀,JSON.parse 结果不是类实例、无观察能力;router 传参对象不能 as 强转,需反序列化重建 @ObservedV2 实例(官方用 class-transformer);makeObserved 只用于把 JSON.parse 的普通对象转为可观察数据。
@Computed 只能装饰 getter,且只能在 @ComponentV2 与 @ObservedV2 中使用;只读,自实现 setter 或与 !! 连用都会编译报错;getter 中不能改参与计算的属性,否则循环重算至 appfreeze;多个 @Computed 不能形成循环依赖(互相成环会死循环),单向链式引用(一个 @Computed 读另一个)是官方支持的写法;只在初始化或依赖变化时重算一次;UI 刷新依赖只在 build 读取后建立,未被 build 读取时仍会随依赖重算,只是不驱动 UI;禁止从父组件初始化,可初始化子组件 @Param。
两处修正:其一,"类实例必须 @Local 才能刷新 @Computed"不是官方要求——官方示例中 name1 就是普通成员变量,界面照样随 @Trace 属性刷新;@Local/@Param 只是 @Monitor 的硬性要求。其二,"初始化赋值挪到 aboutToAppear"对应的是 @Monitor(其生效晚于构造函数);@Computed 在 @ObservedV2 类中官方只提"实例创建后异步初始化",无"构造函数内赋值导致不刷新"之说。
最小工程
把 Index.ets 作为元服务入口页,按"验证方法"点击:
import { hilog } from '@kit.PerformanceAnalysisKit';
const DOMAIN: number = 0xFF00;
const TAG: string = 'V2Demo';
@ObservedV2
class Detail {
@Trace city: string = '北京';
}
@ObservedV2
class UserModel {
@Trace name: string = 'Tom';
@Trace age: number = 18;
@Trace detail: Detail = new Detail();
@Trace tags: string[] = ['a', 'b'];
notTrace: string = 'raw'; // 无 @Trace:改它既不刷新 UI,也不触发 @Monitor
constructor() {
// 此时类中的 @Monitor 尚未生效(其生效晚于 constructor),这次赋值不会被监听到
this.name = 'ctor-name';
}
// 类内监听:自身属性只写属性名,跨对象写点号路径
@Monitor('name')
onNameChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `class name: ${mon.value()?.before} -> ${mon.value()?.now}`);
}
@Monitor('detail.city')
onCityChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `class city: ${mon.value()?.before} -> ${mon.value()?.now}`);
}
// 数组 API(push/pop 等)不会触发对数组整体的监听,监听长度才有效
@Monitor('tags.length')
onTagsLenChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `class tags.length=${this.tags.length}`);
}
@Computed
get summary(): string {
return `${this.name}/${this.age}/${this.detail.city}`;
}
}
@Entry
@ComponentV2
struct Index {
@Local user: UserModel = new UserModel();
@Local tick: number = 0;
// 组件内监听:路径必须从状态变量名开始写全
@Monitor('user.name', 'user.age')
onUserFieldChange(mon: IMonitor) {
mon.dirty.forEach((p: string) => {
hilog.info(DOMAIN, TAG, '%{public}s',
`comp ${p}: ${mon.value(p)?.before} -> ${mon.value(p)?.now}`);
});
}
@Monitor('user.detail.city')
onUserCityChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `comp city -> ${mon.value()?.now}`);
}
@Monitor('user.tags.length')
onTagsLenChange() {
hilog.info(DOMAIN, TAG, '%{public}s', `comp tags.length=${this.user.tags.length}`);
}
@Computed
get title(): string {
return `[${this.tick}] ${this.user.name} (${this.user.age})`;
}
build() {
Column({ space: 10 }) {
Text(this.user.summary) // 读类内 @Computed
.fontSize(20)
Text(this.title) // 读组件内 @Computed
.fontSize(20)
Button('改 name').onClick(() => {
this.user.name = 'Jerry';
})
Button('改 age(同值)').onClick(() => {
this.user.age = this.user.age; // 严格相等,不触发
})
Button('改 city').onClick(() => {
this.user.detail.city = '上海';
})
Button('push tag').onClick(() => {
this.user.tags.push('c'); // 只有 length 监听会触发
})
Button('改 notTrace').onClick(() => {
this.user.notTrace = 'changed';
})
Button('tick+1').onClick(() => {
this.tick++;
})
}
.width('100%')
.padding(16)
}
}错误对照
第 1、2 条替换最小工程 Index 即可复现,日志一条都不打;第 3–5 条只是写法说明,无需建工程:
// 第 1、2 条分别替换最小工程的 Index 组件(同一文件不能有两个 @Entry)
// ❌ 1. 组件里只写属性名:路径的根不是状态变量,不会触发
@Entry
@ComponentV2
struct Bad1 {
@Local user: UserModel = new UserModel();
@Monitor('name') // 错:应写 'user.name'
onName() {
hilog.info(DOMAIN, TAG, '%{public}s', 'never');
}
build() {
Column() {
Text(this.user.name)
}
}
}
// ❌ 2. 实例不是状态变量:路径写全也监听不到
@Entry
@ComponentV2
struct Bad2 {
user: UserModel = new UserModel(); // 错:缺 @Local/@Param
@Monitor('user.name')
onName() {
hilog.info(DOMAIN, TAG, '%{public}s', 'never');
}
build() {
Column() {
Text(this.user.name) // 直接读 @Trace 属性仍会刷新 UI,@Monitor 却不会
}
}
}
// ❌ 3. 非 new 得到的实例没有观察能力
// const u: UserModel = JSON.parse(jsonStr) as UserModel; // 错:不是 UserModel 实例
// const u: UserModel = this.getUIContext().getRouter().getParams() as UserModel; // 错:不能 as 强转
// ❌ 4. 监听数组整体,push/pop 不触发
// @Monitor('user.tags') onTags() {} // 错:应改监听 'user.tags.length'
// ❌ 5. 同一属性在一个类里写两个 @Monitor,只有最后一个生效API 26.0.0 起可用配置项覆盖该层对象内部变化,作为第 3 条的替代思路(dirty 含通配符路径,但 before/now 均为 undefined):
// obj.* 官方列出的触发时机:obj 整体赋值、obj 任意 @Trace 属性变化
@Monitor({}, 'user.*')
onUserChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `dirty=${mon.dirty.toString()}`);
}
// 要覆盖数组的元素变化、长度变化与数组 API 调用,通配符前的确定值必须是数组本身
@Monitor({}, 'user.tags.*')
onTagsChange(mon: IMonitor) {
hilog.info(DOMAIN, TAG, '%{public}s', `dirty=${mon.dirty.toString()}`);
}版本边界
- @ObservedV2/@Trace/@Computed 均 API 12 起(含元服务);卡片支持:前两者自 API 12 起、@Computed 自 API 23 起。
- @Monitor:API 12 起(含元服务),ArkTS 卡片要 API 23 起;API 23 起对入参做编译时校验,非状态变量或不存在的变量会告警
The '@Monitor' decorator needs to monitor the state variables that exist.,但回调仍会被触发;API 26.0.0 起有 MonitorDecoratorOptions 与通配符。 - 通配符只能位于路径末尾、最多一个;用配置项后各路径互相独立、非状态变量被忽略,不再连带触发。
- 同一属性在一个类里多次 @Monitor 只有最后一个生效;判重按入参全拼接(参数间加空格)比较,故
('name','age')与('name','position')可并存;参数只能是字面量、const、enum,用 let 变量时目标初始化即固定。 - @Trace 不能用在 struct 或未被 @ObservedV2 装饰的类;@ObservedV2/@Trace 不能与 @Observed/@Track 或 @State 等 V1 装饰器混用(编译报错,继承类配 V1 为运行时报错);@ObservedV2 类可独立在 V1 @Component 使用,但 V1 装饰器不能接收其实例;API 19 起有 enableV2Compatibility/makeV1Observed 桥接。
- 单个 @Monitor 的参数个数上限官方指南未给出,以 API 参考页或实测为准。
异常边界
- 在 @Monitor 回调里再改被监听属性会无限循环。
- 类里的 @Monitor 靠 GC 才失效,组件销毁而实例未回收时回调仍会触发;建议定义在组件里或销毁前置空目标。
- @Monitor 是"异步监听",不与某一次 build 绑定,别假设日志顺序等于渲染顺序;需同步时序请查 @SyncMonitor(API 23 起)。
- 一次事件改多个被监听属性只触发一次回调,变的是哪些路径只能看
monitor.dirty。
验证方法
Log 窗口按统一 TAG(本例 V2Demo,hilog 域 0xFF00)过滤后逐一点击:
| 操作 | 预期日志 | UI |
|---|---|---|
| 改 name | comp user.name: ctor-name -> Jerry、class name: ctor-name -> Jerry 各 1 条 | 两个 Text 变 Jerry |
| 改 age 同值 | 无日志 | 无变化 |
| 改 city | class city: 北京 -> 上海、comp city -> 上海 | summary 变上海 |
| push tag | 两条 tags.length=3;(错误对照第 4 条的 @Monitor('user.tags') 写法)无日志 | 页面不变 |
| tick+1 | 无 @Monitor 日志 | title 变 [1],@Computed 已重算 |
日志为空但 UI 变了,说明只断在监听侧(数组 API 变化、构造函数内赋值、根不是状态变量最典型);日志打了 UI 不动,说明组件没读那个 @Computed。再用 ArkUI Inspector 看组件树与属性,按官方《状态变量改变不触发组件刷新问题常用定位方法》收敛。
官方资料
- @Monitor
- @Computed
- @ObservedV2/@Trace
- @Monitor API
- @Computed API
- V1/V2混用
- V1-V2迁移
- makeObserved
- @SyncMonitor
- addMonitor/clearMonitor
- 定位方法
- FAQ
- ArkUI Inspector
- HiLog
arkui-v2-monitor-computed-20260917-1
6Jerries
@Monitor 和 @Computed 不触发:路径写法和依赖追踪两个坑(附真机验证)
原问题链接:查看原帖
验证设备:HUAWEI Mate 80 Pro Max,HarmonyOS 7.0
三个问题根因不同,但都和 V2 的观测机制、路径语法有关。我用一个最小 Demo 把正确和错误写法都跑了,结论对上了。
问题一:@Monitor 不触发
最常见的原因有两个。在 @ComponentV2 组件里监听类属性时必须写完整路径,不能只写属性名。比如有 @Local user: UserModel,想监听 user.name 就得写 @Monitor('user.name'),不能写 @Monitor('name')。只有 @Monitor 写在 @ObservedV2 类内部时才能只写属性名。
被监听的属性必须被 @Trace 装饰。没加 @Trace 的普通属性即使变了也监听不到。类实例必须通过 new 创建。
还有个坑:同一属性在同一个类里被多个 @Monitor 监听时,只有最后定义的那个生效。
问题二:@Computed 值变了但 UI 不刷新
值变了说明 @Computed 重新计算了,问题在组件没感知到。最可能的原因是 @Computed 依赖了非状态变量——只有参与计算的状态变量变化才会触发重算,getter 里读了没加 @Trace 的属性,那个属性变了 @Computed 不会重算,UI 自然不更新。
另外两种:类实例不是组件的状态变量(建议声明为 @Local);@Computed 在 @ObservedV2 类中是异步初始化的,如果在 constructor 里赋值,依赖追踪还没建立,把初始赋值挪到 aboutToAppear 就好。
问题三:@Monitor 监听多属性只写属性名,部分捕获不到
这就是路径语法的问题:
- @ObservedV2 类内部:写属性名就行,@Monitor('name', 'age');嵌套属性用点号 @Monitor('detail.city')
- @ComponentV2 组件内:必须从状态变量名开始写完整路径 @Monitor('user.name'),嵌套写 @Monitor('user.detail.city')
- 数组用点号索引:@Monitor('list.0.name');监听数组长度用 @Monitor('list.length')
只写属性名在组件里是监听不到的,因为组件的 @Monitor 需要从状态变量出发建立监听路径。
真机验证
我写了个 Demo,三个场景一起跑:
- @ObservedV2 类 UserModel 有 @Trace name/age/detail(city),类内部 @Monitor('name','age') 和 @Monitor('detail.city') 打日志,@Computed get info() 拼字符串
- 组件 @Local user,@Monitor('user.name','user.age') 记数,@Monitor('user.detail.city') 记深层变化
- 故意写了一个 @Monitor('name')(只写属性名)看会不会触发
点按钮改 name、age、city 后:
- @Computed info 从 Tom, age 18, from Beijing 变成 Jerry, age 19, from Shanghai,UI 正常刷新
- 组件级 @Monitor 触发 2 次(name + age)
- 深层 @Monitor('user.detail.city') 触发,日志打出 Beijing -> Shanghai
- @Monitor('name') 这个错误写法 0 次触发,和预期一致——组件里只写属性名确实监听不到
截图见下方。
参考文档
真机验证截图
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS 通过设置visibility属性为Visibility.None时可以触发转场动画吗(API12+)
HarmonyOS V1和V2的混用问题(API12+)
HarmonyOS 是否有深色模式切换后触发的回调(API12+)
HarmonyOS 状态管理V1和V2上面有什么区别吗,监听List里面的对象属性变化用哪个?(API12+)
HarmonyOS 状态管理V2中@ObservedV2和@trace封装的数据管理类,监听@trace装饰的变量的数据更新 (API12+)
HarmonyOS v2状态管理@ObservedV2,@Trace修饰对象数组的时候,数组里的对象属性发生变化,UI不刷新问题,怎么解决?(API12+)
HarmonyOS 使用@ObservedV2和@trace封装的类,如何监听到自定义类中MembersMedia类中@trace装饰的变量的数据更新?(API12+)
HarmonyOS TaskPool是否支持状态管理V2 (API12+)




































苏公安网备 32011402010933号