• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 状态变量变化监听
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @jiyujia926-->
5<!--Designer: @s10021109-->
6<!--Tester: @TerryTsao-->
7<!--Adviser: @HelloCrease-->
8
9状态变量监听模块提供了对状态变量变化的感知能力。
10
11本文档仅为API参考说明。实际功能使用与限制见各接口对应的开发指南。
12
13> **说明：**
14>
15> 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
16
17## Watch
18
19 Watch: (value: string) => PropertyDecorator
20
21@Watch装饰器用于状态管理V1中对状态变量变化的监听。@Watch的详细使用方式见[@Watch装饰器：状态变量更改通知](../../../ui/state-management/arkts-watch.md)。
22
23**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
24
25**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
26
27**系统能力：** SystemCapability.ArkUI.ArkUI.Full
28
29**参数：**
30
31| 参数名 | 类型   | 必填 | 说明                                     |
32| ------ | ------ | ---- | ---------------------------------------- |
33| value  | string | 是   | 用于监听的回调函数名，内容由开发者指定。 |
34
35**返回值：**
36
37| 类型              | 说明                                 |
38| ----------------- | ------------------------------------ |
39| PropertyDecorator | 属性装饰器，开发者无需关注该返回值。 |
40
41**示例：**
42
43```ts
44@Entry
45@Component
46struct Index {
47  @State @Watch('onChange') num: number = 0; // @Watch入参为函数名
48  onChange() {
49    console.info(`num change to ${this.num}`);
50  }
51  build() {
52    Column() {
53      Text(`num is: ${this.num}`)
54        .onClick(() => {
55          this.num++; // 会触发onChange函数回调
56        })
57    }
58  }
59}
60```
61
62## Monitor<sup>12+</sup>
63
64Monitor: MonitorDecorator
65
66@Monitor装饰器用于状态管理V2中对状态变量变化的监听。@Monitor相关内容的详细使用方式见[@Monitor装饰器：状态变量修改监听](../../../ui/state-management/arkts-new-monitor.md)。
67
68**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
69
70**系统能力：** SystemCapability.ArkUI.ArkUI.Full
71
72## MonitorDecorator<sup>12+</sup>
73
74type MonitorDecorator = (value: string, ...args: string[]) => MethodDecorator
75
76@Monitor装饰器的实际类型。
77
78**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
79
80**系统能力：** SystemCapability.ArkUI.ArkUI.Full
81
82**参数**：
83
84| 参数名 | 类型     | 必填 | 说明                                                         |
85| ------ | -------- | ---- | ------------------------------------------------------------ |
86| value  | string   | 是   | 用于监听的变量名路径，内容由开发者指定。当开发者仅传入一个字符串时，入参为该类型。 |
87| args   | string[] | 是   | 用于监听的变量名路径数组，内容由开发者指定。当开发者传入多个字符串时，入参为该类型。 |
88
89**返回值：**
90
91| 类型            | 说明                                 |
92| --------------- | ------------------------------------ |
93| MethodDecorator | 方法装饰器，开发者无需关注该返回值。 |
94
95**示例：**
96
97```ts
98@ObservedV2
99class Info {
100  @Trace name: string = 'Tom';
101  @Trace age: number = 25;
102  @Trace height: number = 175;
103  @Monitor('name') // 监听一个变量
104  onNameChange(monitor: IMonitor) {
105    console.info(`name change to ${this.name}`);
106  }
107  @Monitor('age', 'height') // 监听多个变量
108  onRecordChange(monitor: IMonitor) {
109    monitor.dirty.forEach((path: string) => {
110      console.info(`${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`);
111    })
112  }
113}
114@Entry
115@ComponentV2
116struct Index {
117  @Local info: Info = new Info();
118  build() {
119    Column() {
120      Text(`info.name: ${this.info.name}`)
121        .onClick(() => {
122          this.info.name = 'Bob'; // 输出日志：name change to Bob
123        })
124      Text(`info.age: ${this.info.age}, info.height: ${this.info.height}`)
125        .onClick(() => {
126          this.info.age++; // 输出日志：age change from 25 to 26
127          this.info.height++; // 输出日志：height change from 175 to 176
128        })
129    }
130  }
131}
132```
133
134## IMonitor<sup>12+</sup>
135
136当监听的变量变化时，状态管理框架侧将回调开发者注册的函数，并传入变化信息。变化信息的类型即为IMonitor类型。
137
138**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
139
140**系统能力：** SystemCapability.ArkUI.ArkUI.Full
141
142### 属性
143
144**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
145
146**系统能力：** SystemCapability.ArkUI.ArkUI.Full
147
148| 名称                | 类型            | 必填 | 说明             |
149| ------------------- | --------------- | ---- | ---------------- |
150| dirty<sup>12+</sup> | Array\<string\> | 是   | 变化路径的数组。 |
151
152### value<sup>12+</sup>
153
154value\<T\>(path?: string): IMonitorValue\<T\> | undefined
155
156获取指定path的变化信息。
157
158**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
159
160**系统能力：** SystemCapability.ArkUI.ArkUI.Full
161
162**参数：**
163
164| 参数名 | 类型   | 必填 | 说明                                                         |
165| ------ | ------ | ---- | ------------------------------------------------------------ |
166| path   | string | 否   | 可选，被监听的变量路径名。未指定时默认使用变化路径数组dirty中的第一个路径。 |
167
168**返回值：**
169
170| 类型                                                  | 说明                                                         |
171| ----------------------------------------------------- | ------------------------------------------------------------ |
172| [IMonitorValue\<T\>](#imonitorvaluet12)  \| undefined | @Monitor监听变量的路径以及变化前后值信息。<br>T为监听变量的类型。<br>当监听的路径不存在时，返回undefined。<br>当未指定路径时，默认返回变化路径数组dirty中第一个路径对应的信息。 |
173
174**示例：**
175
176```ts
177@ObservedV2
178class Info {
179  @Trace name: string = 'Tom';
180  @Trace age: number = 25;
181  @Trace height: number = 175;
182  @Monitor('name') // 监听一个变量
183  onNameChange(monitor: IMonitor) {
184    // 未指定value的入参时，默认使用dirty中的第一个路径作为入参
185    console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`);
186  }
187  @Monitor('age', 'height') // 监听多个变量
188  onRecordChange(monitor: IMonitor) {
189    // 指定value的入参时，将返回入参路径path对应的变量变化值信息
190    monitor.dirty.forEach((path: string) => {
191      console.info(`path: ${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`);
192    })
193  }
194}
195@Entry
196@ComponentV2
197struct Index {
198  @Local info: Info = new Info();
199  build() {
200    Column() {
201      Text(`info.name: ${this.info.name}`)
202        .onClick(() => {
203          this.info.name = 'Bob'; // 输出日志：path: name change from Tom to Bob
204        })
205      Text(`info.age: ${this.info.age}, info.name: ${this.info.height}`)
206        .onClick(() => {
207          this.info.age++; // 输出日志：path: age change from 25 to 26
208          this.info.height++; // 输出日志：path: height change from 175 to 176
209        })
210    }
211  }
212}
213```
214
215## IMonitorValue\<T\><sup>12+</sup>
216
217@Monitor监听变量变化的具体信息，通过IMonitor的value接口获取。T为变量类型。
218
219**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
220
221**系统能力：** SystemCapability.ArkUI.ArkUI.Full
222
223### 属性
224
225**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
226
227**系统能力：** SystemCapability.ArkUI.ArkUI.Full
228
229| 名称                 | 类型   | 必填 | 说明             |
230| -------------------- | ------ | ---- | ---------------- |
231| before<sup>12+</sup> | T      | 是   | 变量变化前的值。 |
232| now<sup>12+</sup>    | T      | 是   | 变量当前的值。   |
233| path<sup>12+</sup>   | string | 是   | 变量的路径。     |
234
235**示例：**
236
237```ts
238@ObservedV2
239class Info {
240  @Trace name: string = 'Tom';
241  @Monitor('name')
242  onNameChange(monitor: IMonitor) {
243    // value的返回值为IMonitorValue类型，可以通过该返回值获取变量变化的信息
244    console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`);
245  }
246}
247@Entry
248@ComponentV2
249struct Index {
250  @Local info: Info = new Info();
251  build() {
252    Column() {
253      Text(`info.name: ${this.info.name}`)
254        .onClick(() => {
255          this.info.name = 'Bob'; // 输出日志：path: name change from Tom to Bob
256        })
257    }
258  }
259}
260```
261