1# State Variable Change Listening 2 3The state variable listening module provides the capability to observe changes in state variables. 4 5This document is solely for API reference. For details about the usage guidelines and constraints, see the development guide of each API. 6 7> **NOTE** 8> 9> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 10 11## Watch 12 13 Watch: (value: string) => PropertyDecorator 14 15The @Watch decorator is used to listen for state variable changes in state management V1. For details about how to use @Watch, see [@Watch Decorator: Getting Notified of State Variable Changes](../../../ui/state-management/arkts-watch.md). 16 17**Widget capability**: This API can be used in ArkTS widgets since API version 9. 18 19**Atomic service API**: This API can be used in atomic services since API version 11. 20 21**System capability**: SystemCapability.ArkUI.ArkUI.Full 22 23**Parameters** 24 25| Name| Type | Mandatory| Description | 26| ------ | ------ | ---- | ---------------------------------------- | 27| value | string | Yes | Name of the callback function used for listening. The value is specified by you.| 28 29**Return value** 30 31| Type | Description | 32| ----------------- | ------------------------------------ | 33| PropertyDecorator | Property decorator. You do not need to concern yourself with this return value.| 34 35**Example** 36 37```ts 38@Entry 39@Component 40struct Index { 41 @State @Watch('onChange') num: number = 0; // The @Watch input parameter is the function name. 42 onChange() { 43 console.info(`num change to ${this.num}`); 44 } 45 build() { 46 Column() { 47 Text(`num is: ${this.num}`) 48 .onClick(() => { 49 this.num++; // This triggers the onChange callback. 50 }) 51 } 52 } 53} 54``` 55 56## Monitor<sup>12+</sup> 57 58Monitor: MonitorDecorator 59 60The @Monitor decorator is used to listen for state variable changes in state management V2. For details about how to use @Monitor, see [@Monitor Decorator: Listening for Value Changes of the State Variables](../../../ui/state-management/arkts-new-monitor.md). 61 62**Atomic service API**: This API can be used in atomic services since API version 12. 63 64**System capability**: SystemCapability.ArkUI.ArkUI.Full 65 66## MonitorDecorator<sup>12+</sup> 67 68type MonitorDecorator = (value: string, ...args: string[]) => MethodDecorator 69 70Represents the actual type of the @Monitor decorator. 71 72**Atomic service API**: This API can be used in atomic services since API version 12. 73 74**System capability**: SystemCapability.ArkUI.ArkUI.Full 75 76**Parameters** 77 78| Name| Type | Mandatory| Description | 79| ------ | -------- | ---- | ------------------------------------------------------------ | 80| value | string | Yes | Variable path name used for listening, specified by you. When only one string is passed, this is the parameter type.| 81| args | string[] | Yes | Array of variable path names used for listening, specified by you. When multiple strings are passed, this is the parameter type.| 82 83**Return value** 84 85| Type | Description | 86| --------------- | ------------------------------------ | 87| MethodDecorator | Method decorator. You do not need to concern yourself with this return value.| 88 89**Example** 90 91```ts 92@ObservedV2 93class Info { 94 @Trace name: string = 'Tom'; 95 @Trace age: number = 25; 96 @Trace height: number = 175; 97 @Monitor('name') // Listen for one variable. 98 onNameChange(monitor: IMonitor) { 99 console.info(`name change to ${this.name}`); 100 } 101 @Monitor('age', 'height') // Listen for multiple variables. 102 onRecordChange(monitor: IMonitor) { 103 monitor.dirty.forEach((path: string) => { 104 console.info(`${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`); 105 }) 106 } 107} 108@Entry 109@ComponentV2 110struct Index { 111 @Local info: Info = new Info(); 112 build() { 113 Column() { 114 Text(`info.name: ${this.info.name}`) 115 .onClick(() => { 116 this.info.name = 'Bob'; // Output log: name change to Bob 117 }) 118 Text(`info.age: ${this.info.age}, info.name: ${this.info.height}`) 119 .onClick(() => { 120 this.info.age++; // Output log: age change from 25 to 26 121 this.info.height++; // Output log: height change from 175 to 176 122 }) 123 } 124 } 125} 126``` 127 128## IMonitor<sup>12+</sup> 129 130When the monitored variable changes, the state management framework will call the registered function and pass the change information of the IMonitor type. 131 132**Atomic service API**: This API can be used in atomic services since API version 12. 133 134**System capability**: SystemCapability.ArkUI.ArkUI.Full 135 136### Properties 137 138**Atomic service API**: This API can be used in atomic services since API version 12. 139 140**System capability**: SystemCapability.ArkUI.ArkUI.Full 141 142| Name | Type | Mandatory| Description | 143| ------------------- | --------------- | ---- | ---------------- | 144| dirty<sup>12+</sup> | Array\<string\> | Yes | Array of changed paths.| 145 146### value<sup>12+</sup> 147 148value\<T\>(path?: string): IMonitorValue\<T\> | undefined 149 150Obtains the change information for the specified path. 151 152**Atomic service API**: This API can be used in atomic services since API version 12. 153 154**System capability**: SystemCapability.ArkUI.ArkUI.Full 155 156**Parameters** 157 158| Name| Type | Mandatory| Description | 159| ------ | ------ | ---- | ------------------------------------------------------------ | 160| path | string | No | Path name of the monitored variable. If it is not specified, the first path in the **dirty** array is used by default.| 161 162**Return value** 163 164| Type | Description | 165| ----------------------------------------------------- | ------------------------------------------------------------ | 166| [IMonitorValue\<T\>](#imonitorvaluet12) \| undefined | Path and change information for the monitored variable.<br>**T** is the type of the monitored variable.<br>If the monitored path does not exist, **undefined** is returned.<br>If no path is specified, the information corresponding to the first path in the **dirty** array is returned by default.| 167 168**Example** 169 170```ts 171@ObservedV2 172class Info { 173 @Trace name: string = 'Tom'; 174 @Trace age: number = 25; 175 @Trace height: number = 175; 176 @Monitor('name') // Listen for one variable. 177 onNameChange(monitor: IMonitor) { 178 // If no path is specified for value, the first path in the dirty array is used by default. 179 console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`); 180 } 181 @Monitor('age', 'height') // Listen for multiple variables. 182 onRecordChange(monitor: IMonitor) { 183 // If a path is specified for value, the change information for the specified path is returned. 184 monitor.dirty.forEach((path: string) => { 185 console.info(`path: ${path} change from ${monitor.value(path)?.before} to ${monitor.value(path)?.now}`); 186 }) 187 } 188} 189@Entry 190@ComponentV2 191struct Index { 192 @Local info: Info = new Info(); 193 build() { 194 Column() { 195 Text(`info.name: ${this.info.name}`) 196 .onClick(() => { 197 this.info.name = 'Bob'; // Output log: path: name change from Tom to Bob 198 }) 199 Text(`info.age: ${this.info.age}, info.name: ${this.info.height}`) 200 .onClick(() => { 201 this.info.age++; // Output log: path: age change from 25 to 26 202 this.info.height++; // Output log: path: height change from 175 to 176 203 }) 204 } 205 } 206} 207``` 208 209## IMonitorValue\<T\><sup>12+</sup> 210 211Provides the specific change information for the monitored variable, obtained through the **value** API of **IMonitor**. **T** is the type of the variable. 212 213**Atomic service API**: This API can be used in atomic services since API version 12. 214 215**System capability**: SystemCapability.ArkUI.ArkUI.Full 216 217### Properties 218 219**Atomic service API**: This API can be used in atomic services since API version 12. 220 221**System capability**: SystemCapability.ArkUI.ArkUI.Full 222 223| Name | Type | Mandatory| Description | 224| -------------------- | ------ | ---- | ---------------- | 225| before<sup>12+</sup> | T | Yes | Variable value before change.| 226| now<sup>12+</sup> | T | Yes | Current variable value. | 227| path<sup>12+</sup> | string | Yes | Variable path. | 228 229**Example** 230 231```ts 232@ObservedV2 233class Info { 234 @Trace name: string = 'Tom'; 235 @Monitor('name') 236 onNameChange(monitor: IMonitor) { 237 // The return value of value is of the IMonitorValue type, through which the variable change information can be obtained. 238 console.info(`path: ${monitor.value()?.path} change from ${monitor.value()?.before} to ${monitor.value()?.now}`); 239 } 240} 241@Entry 242@ComponentV2 243struct Index { 244 @Local info: Info = new Info(); 245 build() { 246 Column() { 247 Text(`info.name: ${this.info.name}`) 248 .onClick(() => { 249 this.info.name = 'Bob'; // Output log: path: name change from Tom to Bob 250 }) 251 } 252 } 253} 254``` 255