鸿蒙开发：V2版本装饰器之@Monitor装饰器

其他
2025-08-26 05:12:02

前言

本文代码案例基于Api13。

随着官方的迭代，在新的Api中，对于新的应用开发，官方已经建议直接使用V2所属的装饰器进行开发了，所以，能上手V2的尽量上手V2吧，毕竟，V2是V1的增强版本，为开发者提供更多功能和灵活性，由V1升成V2，肯定是大势所趋；但是，毕竟V1有着大量的应用基础，使用的也非常广泛，如果V1版本的功能和性能已能满足需求，其实也不用切换，总之就一句话：新的应用尽量使用V2，老的应用，如果V1满足可以不切换V2，如果功能受限，建议循序渐进的进行切换。

本篇文章主要概述下V2版本装饰器中的@Monitor装饰器，它对标的是V1中的@Watch装饰器，但是使用上和功能上均有所不同。

记得之前在写刷新组件的时候，有一个功能，需要监听当前刷新或加载的关闭状态，然后去执行关闭动画等逻辑，使用的就是@Watch装饰器，简单的逻辑如下：

class RefreshController { closeRefresh: boolean = false closeLoadMore: boolean = false } @Entry @Component struct Index { @State @Watch("listenerController") refreshController: RefreshController = new RefreshController() listenerController() { console.log("==当前刷新状态：" + this.refreshController.closeRefresh) console.log("==当前加载状态：" + this.refreshController.closeLoadMore) } build() { Column() { Button("关闭刷新") .onClick(() => { this.refreshController.closeRefresh = true }) Button("关闭加载") .margin({ top: 20 }) .onClick(() => { this.refreshController.closeLoadMore = true }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }

运行后，我们点击按钮进行打印日志：

虽然执行的状态，我们通过@Watch装饰器监听到了，也能实现我们的逻辑，但是存在一个问题，本身我们只想监听到某一个状态的改变，比如只监听刷新状态，或者只监听加载状态，但是@Watch装饰器是，你无论监听哪一个，都统统给你返回，显然会影响我们做针对性的逻辑判断。

除此之外，还存在一个问题，变量更改前的值是什么，在这里无法获取，在业务逻辑复杂的场景下，我们是无法准确知道是哪一个属性或元素发生了改变从而触发了@Watch事件，这非常不便于我们对变量的更改进行准确监听。

针对以上的弊端，V2版本中的@Monitor装饰器，则弥补了这一缺陷，实现对对象、数组中某一单个属性或数组项变化的监听，并且能够获取到变化之前的值。

更改为@Monitor装饰器后，针对属性单独监听。

@ObservedV2 class RefreshController { @Trace closeRefresh: boolean = false @Trace closeLoadMore: boolean = false } @Entry @ComponentV2 struct Index { @Local refreshController: RefreshController = new RefreshController() @Monitor("refreshController.closeRefresh") closeRefreshChange() { console.log("==当前刷新状态：" + this.refreshController.closeRefresh) } @Monitor("refreshController.closeLoadMore") closeLoadMoreChange() { console.log("==当前加载状态：" + this.refreshController.closeLoadMore) } build() { Column() { Button("关闭刷新") .onClick(() => { this.refreshController.closeRefresh = true }) Button("关闭加载") .margin({ top: 20 }) .onClick(() => { this.refreshController.closeLoadMore = true }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }

使用方式

首先需要注意，@Monitor监听的变量，一定是被@Local、@Param、@Provider、@Consumer、@Computed装饰，否则是无法监听的，这一点，务必须知。

第一步，使用@Local、@Param、@Provider、@Consumer、@Computed等其中之一，修饰你的变量，例如下代码：

@Local testContent: string = "测试数据一"

第二步，使用@Monitor装饰器进行监听，方法名自己定义，要求，@Monitor("变量名")，其中变量名一定要和第一步的变量名字保持一致，例如下代码：

@Monitor("testContent") testContentChange() { console.log("==属性testContent发生了改变：" + this.testContent) }

动态改变属性testContent，就会触发@Monitor装饰器修饰的函数；@Monitor装饰器支持监听多个状态变量，直接逗号分隔即可，多个属性中，任意一个属性发生了改变都会进行回调。

@Monitor("testContent","testNumber") testChange() { console.log("==testContent属性：" + this.testContent + ",testNumber属性：" + this.testNumber) }

获取改变之前的值

如果你想拿到当前属性改变之前的值，那么就需要在函数中传递IMonitor类型的参数。

IMonitor类型的变量用作@Monitor装饰方法的参数。

属性

类型

参数

返回值

说明

dirty

Array<string>

无

保存发生变化的属性名。

value<T>

function

path?: string

IMonitorValue<T>

获得指定属性（path）的变化信息。当不填path时返回@Monitor监听顺序中第一个改变的属性的变化信息。

MonitorValue<T>类型

IMonitorValue<T>类型保存了属性变化的信息，包括属性名、变化前值、当前值。

属性

类型

说明

before

监听属性变化之前的值。

now

监听属性变化之后的当前值。

path

string

监听的属性名。

@Monitor("testContent") testChange(monitor: IMonitor) { monitor.dirty.forEach((path: string) => { console.log("==属性值改变之前：" + monitor.value(path)?.before + ",属性值改变之后：" + monitor.value(path)?.now) }) }

如果只想监听改变之后的值，IMonitor参数可以省略。

对象监听

在前言中，我们可以看到，监听对象中的属性变化时，需要使用@Trace装饰，如果未被装饰，则是无法进行监听的，所以在实际的开发中，如果需要针对对象的单一属性进行监听时，@Trace装饰务必使用。

如果不装饰，那么就需要重新创建对象，虽然这种方式也能正常的监听到，但是并不是唯一属性的监听，在实际的开发中是不推荐的。

以下案例未使用@Trace装饰，不建议使用。

class RefreshController { closeRefresh: boolean = false closeLoadMore: boolean = false } @Entry @ComponentV2 struct Index { @Local refreshController: RefreshController = new RefreshController() @Monitor("refreshController.closeRefresh") closeRefreshChange() { console.log("==当前刷新状态：" + this.refreshController.closeRefresh) } @Monitor("refreshController.closeLoadMore") closeLoadMoreChange() { console.log("==当前加载状态：" + this.refreshController.closeLoadMore) } build() { Column() { Button("关闭刷新") .onClick(() => { this.refreshController = new RefreshController() this.refreshController.closeRefresh = true }) Button("关闭加载") .margin({ top: 20 }) .onClick(() => { this.refreshController = new RefreshController() this.refreshController.closeLoadMore = true }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }

如果你想监听整个对象的属性变化，@Trace装饰可以不使用。

class RefreshController { closeRefresh: boolean = false closeLoadMore: boolean = false } @Entry @ComponentV2 struct Index { @Local refreshController: RefreshController = new RefreshController() @Monitor("refreshController") statusChange() { console.log("==当前刷新状态：" + this.refreshController.closeRefresh) console.log("==当前加载状态：" + this.refreshController.closeLoadMore) } build() { Column() { Button("关闭刷新") .onClick(() => { this.refreshController = new RefreshController() this.refreshController.closeRefresh = true }) Button("关闭加载") .margin({ top: 20 }) .onClick(() => { this.refreshController = new RefreshController() this.refreshController.closeLoadMore = true }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }

除了在UI组件可以进行监听，在自身对象中也是可以进行监听的，方便在对象中做一些逻辑，同样也支持在继承类场景下，同一个属性进行多次监听。

@ObservedV2 class RefreshController { @Trace closeRefresh: boolean = false @Trace closeLoadMore: boolean = false @Monitor("closeRefresh") closeRefreshChange() { console.log("==监听对象中的当前刷新状态：" + this.closeRefresh) } }

通用监听能力

@Monitor装饰器，除了正常的数据监听之外，还支持对数组中的元素进行监听，包括多维数组，对象数组，虽然可以正常监听其值的变化，但是无法监听内置类型（Array、Map、Date、Set）的API调用引起的变化。

还有一点需要注意，当@Monitor监听数组整体变化时，只能通过监听数组的长度变化来判断数组是否有插入、删除等变化，以下是一个简单的二位数组数据改变案例：

@Entry @ComponentV2 struct Index { @Local numberArray: number[][] = [[1, 1, 1], [2, 2, 2], [3, 3, 3]]; @Monitor("numberArray.0.0", "numberArray.1.1") statusChange() { console.log("==数据改变：" + this.numberArray) } build() { Column() { Button("改变") .onClick(() => { this.numberArray[0][0]++ }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }

可以发现以上的案例，只要数据发生了变化，就会执行数据监听方法。

监听对象整体改变时，如果当前属性未发生改变时，则不会触发@Monitor回调。

如下案例，依次点击按钮，会发生，按钮一不会执行任何方法，因为属性的值一样，未发生变化，按钮二和按钮三则可以正常执行。

@ObservedV2 class RefreshController { @Trace closeRefresh: boolean = false @Trace closeLoadMore: boolean = false constructor(closeRefresh: boolean, closeLoadMore: boolean) { this.closeRefresh = closeRefresh; this.closeLoadMore = closeLoadMore; } } @Entry @ComponentV2 struct Index { @Local refreshController: RefreshController = new RefreshController(false, false) @Monitor("refreshController.closeRefresh") closeRefreshChange() { console.log("==当前刷新状态：" + this.refreshController.closeRefresh) } @Monitor("refreshController.closeLoadMore") closeLoadMoreChange() { console.log("==当前加载状态：" + this.refreshController.closeLoadMore) } build() { Column() { Button("不会走") .onClick(() => { this.refreshController = new RefreshController(false, false) }) Button("关闭刷新") .margin({ top: 20 }) .onClick(() => { this.refreshController = new RefreshController(true, false) }) Button("关闭加载") .margin({ top: 20 }) .onClick(() => { this.refreshController = new RefreshController(false, true) }) } .height('100%') .width('100%') .justifyContent(FlexAlign.Center) } }