1# @ohos.arkui.StateManagement (状态管理) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiyujia926; @liwenzhen3; @zzq212050299--> 5<!--Designer: @s10021109--> 6<!--Tester: @TerryTsao--> 7<!--Adviser: @HelloCrease--> 8 9状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、UIAbility数据存储能力和应用程序需要的环境状态、工具。 10 11>**说明：** 12> 13>本模块首批接口从API version 12开始支持，后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15 16本文中T和S的含义如下： 17 18 19| 类型 | 说明 | 20| ---- | -------------------------------------- | 21| T | Class，number，boolean，string和这些类型的数组形式。 | 22| S | number，boolean，string。 | 23 24 25## 导入模块 26 27```ts 28import { AppStorageV2, PersistenceV2, UIUtils } from '@kit.ArkUI'; 29``` 30 31## AppStorageV2 32 33AppStorageV2具体UI使用说明，详见[AppStorageV2(应用全局的UI状态存储)](../../ui/state-management/arkts-new-appstoragev2.md)。 34 35**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39### connect 40 41static connect\<T extends object\>( </br > 42 type: TypeConstructorWithArgs\<T\>, </br > 43 keyOrDefaultCreator?: string | StorageDefaultCreator\<T\>, </br > 44 defaultCreator?: StorageDefaultCreator\<T\> </br > 45): T | undefined 46 47将键值对数据储存在应用内存中。如果给定的key已经存在于[AppStorageV2](../../ui/state-management/arkts-new-appstoragev2.md)中，返回对应的值；否则，通过获取默认值的构造器构造默认值，并返回。 48 49**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 50 51**系统能力：** SystemCapability.ArkUI.ArkUI.Full 52 53**参数：** 54 55| 参数名 | 类型 | 必填 | 说明 | 56| -------- | ------ | ---- | ---------------------- | 57| type | [TypeConstructorWithArgs\<T\>](#typeconstructorwithargst) | 是 | 指定的类型，若未指定key，则使用type的name作为key。 | 58| keyOrDefaultCreator | string \| [StorageDefaultCreator\<T\>](#storagedefaultcreatort) | 否 | 指定的key，或者是获取默认值的构造器。 | 59| defaultCreator | StorageDefaultCreator\<T\> | 否 | 获取默认值的构造器。 | 60 61>**说明：** 62> 63>1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器； 64> 65>2、确保数据已经存储在AppStorageV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常； 66> 67>3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配； 68> 69>4、key建议使用有意义的值，长度不超过255，使用非法字符或空字符的行为是未定义的。 70 71**返回值：** 72 73| 类型 | 说明 | 74| -------------------------------------- | ------------------------------------------------------------ | 75| T \| undefined | 创建或获取AppStorageV2数据成功时，返回数据；否则返回undefined。 | 76 77**示例：** 78 79```ts 80import { AppStorageV2 } from '@kit.ArkUI'; 81 82@ObservedV2 83class SampleClass { 84 @Trace p: number = 0; 85} 86 87// 将key为SampleClass、value为new SampleClass()对象的键值对存储到内存中，并赋值给as1 88const as1: SampleClass | undefined = AppStorageV2.connect(SampleClass, () => new SampleClass()); 89 90// 将key为key_as2、value为new SampleClass()对象的键值对存储到内存中，并赋值给as2 91const as2: SampleClass = AppStorageV2.connect(SampleClass, 'key_as2', () => new SampleClass())!; 92 93// key为SampleClass已经在AppStorageV2中，将key为SampleClass的值返回给as3 94const as3: SampleClass = AppStorageV2.connect(SampleClass) as SampleClass; 95``` 96 97### remove 98 99static remove\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void 100 101将指定的键值对数据从[AppStorageV2](../../ui/state-management/arkts-new-appstoragev2.md)里面删除。如果指定的键值不存在于AppStorageV2中，将删除失败。 102 103**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 104 105**系统能力：** SystemCapability.ArkUI.ArkUI.Full 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 说明 | 110| -------- | ------ | ---- | ---------------------- | 111| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要删除的key；如果指定的是type类型，删除的key为type的name。 | 112 113>**说明：** 114> 115>删除AppStorageV2中不存在的key会报警告。 116 117 118**示例：** 119 120<!--code_no_check--> 121```ts 122// 假设AppStorageV2中存在key为key_as2的键，从AppStorageV2中删除该键值对数据 123AppStorageV2.remove('key_as2'); 124 125// 假设AppStorageV2中存在key为SampleClass的键，从AppStorageV2中删除该键值对数据 126AppStorageV2.remove(SampleClass); 127 128// 假设AppStorageV2中不存在key为key_as1的键，报警告 129AppStorageV2.remove('key_as1'); 130``` 131 132### keys 133 134static keys(): Array\<string\> 135 136获取[AppStorageV2](../../ui/state-management/arkts-new-appstoragev2.md)中的所有key。 137 138**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 139 140**系统能力：** SystemCapability.ArkUI.ArkUI.Full 141 142**返回值：** 143 144| 类型 | 说明 | 145| -------------------------------------- | ------------------------------------------------------------ | 146| Array\<string\> | 所有AppStorageV2中的key。 | 147 148>**说明：** 149> 150>key在Array中的顺序是无序的，与key插入到AppStorageV2中的顺序无关。 151 152**示例：** 153 154```ts 155// 假设AppStorageV2中存在两个key（key_as1、key_as2），返回[key_as1、key_as2]赋值给keys 156const keys: Array<string> = AppStorageV2.keys(); 157``` 158 159 160 161## PersistenceV2 162 163继承自[AppStorageV2](#appstoragev2)，PersistenceV2具体UI使用说明，详见[PersistenceV2(持久化存储UI状态)](../../ui/state-management/arkts-new-persistencev2.md)。 164 165**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 166 167**系统能力：** SystemCapability.ArkUI.ArkUI.Full 168 169### globalConnect<sup>18+</sup> 170 171static globalConnect\<T extends object\>(type: ConnectOptions\<T\>): T | undefined 172 173将键值对数据储存在应用磁盘中。如果给定的key已经存在于[PersistenceV2](../../ui/state-management/arkts-new-persistencev2.md)中，返回对应的值；否则，会通过获取默认值的构造器构造默认值，并返回。如果globalConnect的是\@ObservedV2对象，该对象\@Trace属性的变化，会触发整个关联对象的自动刷新；非\@Trace属性变化则不会，如有必要，可调用PersistenceV2.save接口手动存储。 174 175**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 176 177**系统能力：** SystemCapability.ArkUI.ArkUI.Full 178 179**参数：** 180 181| 参数名 |类型 |必填 | 说明 | 182| ------------- | ------------|-------------------|-------------------------- | 183| type |[ConnectOptions\<T\>](#connectoptions18) |是 |传入的connect参数，详细说明见ConnectOptions参数说明。 | 184 185**返回值：** 186 187|类型 |说明 | 188|----------|-----------------------------------| 189|T \| undefined |创建或获取数据成功时，返回数据；否则返回undefined。 | 190 191> **说明：** 192> 193> 1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器（第二个参数非法也使用第三个参数作为默认构造器）。 194> 195> 2、确保数据已经存储在PersistenceV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常。 196> 197> 3、同一个key，globalConnect不同类型的数据会导致应用异常，应用需要确保类型匹配。 198> 199> 4、key建议使用有意义的值，可由字母、数字、下划线组成，长度不超过255，使用非法字符或空字符的行为是未定义的。 200> 201> 5、关联[\@Observed](../../ui/state-management/arkts-observed-and-objectlink.md)对象时，因为该类型的name属性未定义，需要指定key或者自定义name属性。 202> 203> 6、数据的存储路径为应用级别，不同module使用相同的key和相同的加密分区进行globalConnect，存储的数据副本应用仅有一份。 204> 205> 7、globalConnect使用同一个key但设置了不同的加密级别，数据为第一个使用globalConnect的加密级别，并且PersistenceV2中的数据也会存入最先使用key的加密级别。 206> 207> 8、connect和globalConnect不建议混用，因为数据副本路径不同，如果混用，则key不可以一样，否则会crash。 208> 209> 9、EL5加密要想生效，需要开发者在module.json中配置字段ohos.permission.PROTECT_SCREEN_LOCK_DATA，使用说明见[声明权限](../../security/AccessToken/declare-permissions.md)。 210 211**示例：** 212仅供开发者了解globalConnect用法，完整使用需开发者自己写出@Entry组件。 213 214<!--code_no_check--> 215```ts 216import { PersistenceV2, Type, ConnectOptions } from '@kit.ArkUI'; 217import { contextConstant } from '@kit.AbilityKit'; 218 219@ObservedV2 220class SampleChild { 221 @Trace childId: number = 0; 222 groupId: number = 1; 223} 224 225@ObservedV2 226export class Sample { 227 // 对于复杂对象需要@Type修饰，确保序列化成功 228 @Type(SampleChild) 229 @Trace father: SampleChild = new SampleChild(); 230} 231 232// key不传入尝试用为type的name作为key，加密参数不传入默认加密等级为EL2 233const p: Sample = PersistenceV2.globalConnect({ type: Sample, defaultCreator: () => new Sample() })!; 234 235// 使用key:global1连接，传入加密等级为EL1 236const p1: Sample = PersistenceV2.globalConnect({ 237 type: Sample, 238 key: 'global1', 239 defaultCreator: () => new Sample(), 240 areaMode: contextConstant.AreaMode.EL1 241})!; 242 243// 使用key:global2连接，使用构造函数形式，加密参数不传入默认加密等级为EL2 244const p2: Sample = PersistenceV2.globalConnect({ type: Sample, key: 'global2', defaultCreator: () => new Sample() })!; 245 246// 使用key:global3连接，直接写加密数值，范围只能在0-4，否则运行会crash,例如加密设置为EL3 247const p3: Sample = PersistenceV2.globalConnect({ 248 type: Sample, 249 key: 'global3', 250 defaultCreator: () => new Sample(), 251 areaMode: 3 252})!; 253 254``` 255 256### save 257 258static save\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void 259 260将指定的键值对数据持久化一次。 261 262**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 263 264**系统能力：** SystemCapability.ArkUI.ArkUI.Full 265 266**参数：** 267 268| 参数名 | 类型 | 必填 | 说明 | 269| -------- | ------ | ---- | ---------------------- | 270| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要持久化的key；如果指定的是type类型，持久化的key为type的name。 | 271 272>**说明：** 273> 274>由于非[\@Trace](../../ui/state-management/arkts-new-observedV2-and-trace.md)的数据改变不会触发[PersistenceV2](../../ui/state-management/arkts-new-persistencev2.md)的自动持久化，如有必要，可调用该接口持久化对应key的数据。 275> 276>手动持久化当前内存中不处于connect状态的key是无意义的。 277 278**示例：** 279 280<!--code_no_check--> 281 282```ts 283@ObservedV2 284class SampleClass { 285 @Trace p: number = 0; 286} 287 288// 假设PersistenceV2中存在key为key_as2的键，持久化该键值对数据 289PersistenceV2.save('key_as2'); 290 291// 假设PersistenceV2中存在key为SampleClass的键，持久化该键值对数据 292PersistenceV2.save(SampleClass); 293 294// 假设PersistenceV2中不存在key为key_as1的键，无意义的操作 295PersistenceV2.save('key_as1'); 296``` 297 298### notifyOnError 299 300static notifyOnError(callback: PersistenceErrorCallback | undefined): void 301 302在持久化失败时调用。 303 304**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 305 306**系统能力：** SystemCapability.ArkUI.ArkUI.Full 307 308**参数：** 309 310| 参数名 | 类型 | 必填 | 说明 | 311| -------- | ------ | ---- | ---------------------- | 312| callback | PersistenceErrorCallback \| undefined | 是 | 持久化失败时调用。 | 313 314**示例：** 315 316```ts 317// 持久化失败时调用 318PersistenceV2.notifyOnError((key: string, reason: string, msg: string) => { 319 console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`); 320}); 321``` 322 323## ConnectOptions<sup>18+</sup> 324 325globalConnect参数类型。 326 327**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 328 329**系统能力：** SystemCapability.ArkUI.ArkUI.Full 330 331|名称 |类型 |只读 |可选 |说明 | 332|--------|------------|------------|-----------|--------------| 333|type | TypeConstructorWithArgs\<T\> |否 |否 |指定的类型。 | 334|key | string |否 |是 |传入的key，不传则使用type的名字作为key。 | 335|defaultCreator | StorageDefaultCreator\<T\> |否 |是 |默认数据的构造器，建议传递，如果globalConnect是第一次连接key，不传会报错。 | 336|areaMode | contextConstant.AreaMode |否 |是 |加密级别：EL1-EL5，详见[加密级别](../../application-models/application-context-stage.md#获取和修改加密分区)，对应数值：0-4，不传时默认为EL2，不同加密级别对应不同的加密分区，即不同的存储路径，传入的加密等级数值不在0-4会直接运行crash。 | 337 338## UIUtils 339 340UIUtils提供一些方法，用于处理状态管理相关的数据转换。 341 342**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 343 344**系统能力：** SystemCapability.ArkUI.ArkUI.Full 345 346### getTarget 347 348static getTarget\<T extends object\>(source: T): T 349 350从状态管理框架包裹的代理对象中获取原始对象。详见[getTarget接口：获取状态管理框架代理前的原始对象](../../ui/state-management/arkts-new-getTarget.md)。 351 352**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.ArkUI.ArkUI.Full 355 356**参数：** 357 358| 参数名 | 类型 | 必填 | 说明 | 359| ------ | ---- | ---- | ------------ | 360| source | T | 是 | 数据源对象。 | 361 362**返回值：** 363 364| 类型 | 说明 | 365| ---- | ------------------------------------------------ | 366| T | 数据源对象去除状态管理框架所加代理后的原始对象。 | 367 368**示例：** 369 370```ts 371import { UIUtils } from '@kit.ArkUI'; 372class NonObservedClass { 373 name: string = 'Tom'; 374} 375let nonObservedClass: NonObservedClass = new NonObservedClass(); 376@Entry 377@Component 378struct Index { 379 @State someClass: NonObservedClass = nonObservedClass; 380 build() { 381 Column() { 382 Text(`this.someClass === nonObservedClass: ${this.someClass === nonObservedClass}`) // false 383 Text(`UIUtils.getTarget(this.someClass) === nonObservedClass: ${UIUtils.getTarget(this.someClass) === 384 nonObservedClass}`) // true 385 } 386 } 387} 388``` 389### makeObserved 390 391static makeObserved\<T extends object\>(source: T): T 392 393将普通不可观察数据变为可观察数据。详见[makeObserved接口：将非观察数据变为可观察数据](../../ui/state-management/arkts-new-makeObserved.md)。 394 395**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 396 397**系统能力：** SystemCapability.ArkUI.ArkUI.Full 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ------ | ---- | ---- | ------------ | 403| source | T | 是 | 数据源对象。支持非@Observed和@ObservedV2装饰的class，JSON.parse返回的Object和@Sendable修饰的class。</br>支持Array、Map、Set和Date。</br>支持collection.Array, collection.Set和collection.Map。</br>具体使用规则，详见[makeObserved接口：将非观察数据变为可观察数据](../../ui/state-management/arkts-new-makeObserved.md)。 | 404 405**返回值：** 406 407| 类型 | 说明 | 408| ---- | ------------------------------------------------ | 409| T | 可观察的数据。 | 410 411**示例：** 412 413```ts 414import { UIUtils } from '@kit.ArkUI'; 415class NonObservedClass { 416 name: string = 'Tom'; 417} 418 419@Entry 420@ComponentV2 421struct Index { 422 observedClass: NonObservedClass = UIUtils.makeObserved(new NonObservedClass()); 423 nonObservedClass: NonObservedClass = new NonObservedClass(); 424 build() { 425 Column() { 426 Text(`observedClass: ${this.observedClass.name}`) 427 .onClick(() => { 428 this.observedClass.name = 'Jane'; // 刷新 429 }) 430 Text(`observedClass: ${this.nonObservedClass.name}`) 431 .onClick(() => { 432 this.nonObservedClass.name = 'Jane'; // 不刷新 433 }) 434 } 435 } 436} 437``` 438 439### enableV2Compatibility<sup>19+</sup> 440 441static enableV2Compatibility\<T extends object\>(source: T): T 442 443使V1的状态变量能够在\@ComponentV2中观察，主要应用于状态管理V1、V2混用场景。详见[状态管理V1V2混用文档](../../ui/state-management/arkts-v1-v2-mixusage.md)。 444 445**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 446 447**系统能力：** SystemCapability.ArkUI.ArkUI.Full 448 449**参数：** 450 451| 参数名 | 类型 | 必填 | 说明 | 452| ------ | ---- | ---- | ------------ | 453| source | T | 是 | 数据源，仅支持V1状态数据。 | 454 455**返回值：** 456 457| 类型 | 说明 | 458| ---- | ------------------------------------------------ | 459| T | 如果数据源是V1的状态数据，则返回能够在\@ComponentV2中观察的数据。否则返回数据源本身。 | 460 461 462**示例：** 463 464```ts 465import { UIUtils } from '@kit.ArkUI'; 466 467@Observed 468class ObservedClass { 469 name: string = 'Tom'; 470} 471 472@Entry 473@Component 474struct CompV1 { 475 @State observedClass: ObservedClass = new ObservedClass(); 476 477 build() { 478 Column() { 479 Text(`@State observedClass: ${this.observedClass.name}`) 480 .onClick(() => { 481 this.observedClass.name = 'State'; // 刷新 482 }) 483 // 将V1的状态变量使能V2的观察能力 484 CompV2({ observedClass: UIUtils.enableV2Compatibility(this.observedClass) }) 485 } 486 } 487} 488 489@ComponentV2 490struct CompV2 { 491 @Param observedClass: ObservedClass = new ObservedClass(); 492 493 build() { 494 // V1状态变量在使能V2观察能力后，可以在V2观察第一层的变化 495 Text(`@Param observedClass: ${this.observedClass.name}`) 496 .onClick(() => { 497 this.observedClass.name = 'Param'; // 刷新 498 }) 499 } 500} 501``` 502 503### makeV1Observed<sup>19+</sup> 504static makeV1Observed\<T extends object\>(source: T): T 505 506将不可观察的对象包装成状态管理V1可观察的对象，其能力等同于@Observed，可初始化@ObjectLink。 507 508该接口可搭配[enableV2Compatibility](#enablev2compatibility19)应用于状态管理V1和V2混用场景，详见[状态管理V1V2混用文档](../../ui/state-management/arkts-v1-v2-mixusage.md)。 509 510**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 511 512**系统能力：** SystemCapability.ArkUI.ArkUI.Full 513 514**参数：** 515 516| 参数名 | 类型 | 必填 | 说明 | 517| ------ | ---- | ---- | ------------ | 518| source | T | 是 | 数据源。支持普通class、Array、Map、Set、Date类型。</br>不支持[collections类型](../apis-arkts/arkts-apis-arkts-collections.md)和[@Sendable](../../arkts-utils/arkts-sendable.md)修饰的class。</br>不支持undefined和null。不支持状态管理V2的数据和[makeObserved](#makeobserved)的返回值。 | 519 520**返回值：** 521 522| 类型 | 说明 | 523| ---- | ------------------------------------------------ | 524| T | 对于支持的入参类型，返回状态管理V1的观察数据。对于不支持的入参类型，返回数据源对象本身。 | 525 526**示例：** 527 528```ts 529import { UIUtils } from '@kit.ArkUI'; 530 531class Outer { 532 outerValue: string = 'outer'; 533 inner: Inner; 534 535 constructor(inner: Inner) { 536 this.inner = inner; 537 } 538} 539 540class Inner { 541 interValue: string = 'inner'; 542} 543 544@Entry 545@Component 546struct Index { 547 @State outer: Outer = new Outer(UIUtils.makeV1Observed(new Inner())); 548 549 build() { 550 Column() { 551 // makeV1Observed的返回值可初始化@ObjectLink 552 Child({ inner: this.outer.inner }) 553 } 554 .height('100%') 555 .width('100%') 556 } 557} 558 559@Component 560struct Child { 561 @ObjectLink inner: Inner; 562 563 build() { 564 Text(`${this.inner.interValue}`) 565 .onClick(() => { 566 this.inner.interValue += '!'; 567 }) 568 } 569} 570``` 571 572### makeBinding<sup>20+</sup> 573static makeBinding\<T\>(getter: GetterCallback\<T\>): Binding\<T\> 574 575创建只读的单向数据绑定实例，用于构建\@Builder函数中参数类型为`Binding`的对应实参。 576 577**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 578 579**系统能力：** SystemCapability.ArkUI.ArkUI.Full 580 581**参数：** 582 583| 参数名 | 类型 | 必填 | 说明 | 584| ------ | ---- | ---- | ------------ | 585| getter | [GetterCallback\<T\>](#gettercallback20) | 是 | 获取值的回调函数，每次访问值都会重新执行函数，获取最新值。 | 586 587**返回值：** 588 589| 类型 | 说明 | 590| ---- | ------------------------------------------------ | 591| [Binding\<T\>](#bindingt20) | 仅包含一个`value`属性，用于获取当前绑定的值。只能读取值，不能直接修改。 | 592 593**示例：** 594 595```ts 596import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 597 598@Builder 599function CustomButton(num1: Binding<number>) { 600 Row() { 601 Button(`Custom Button: ${num1.value}`) 602 .onClick(() => { 603 // num1.value += 1; 会报错，Binding类型不支持修改 604 }) 605 } 606} 607 608@Entry 609@ComponentV2 610struct CompV2 { 611 @Local number1: number = 5; 612 @Local number2: number = 10; 613 614 build() { 615 Column() { 616 Text('parent component') 617 618 CustomButton( 619 /** 620 * 创建只读绑定实例 621 * @param getter - 返回this.number1的函数 622 * @returns 只读的Binding<number>对象 623 * 624 * 特点： 625 * 1. 每次访问.value时重新计算 626 * 2. 不能直接修改值 627 */ 628 UIUtils.makeBinding<number>( 629 () => this.number1 // GetterCallback 630 ) 631 ) 632 } 633 } 634} 635``` 636 637### makeBinding<sup>20+</sup> 638static makeBinding\<T\>(getter: GetterCallback\<T\>, setter: SetterCallback\<T\>): MutableBinding\<T\> 639 640创建可修改的双向数据绑定实例，用于构建\@Builder函数中参数类型为`MutableBinding`的对应实参。 641 642**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 643 644**系统能力：** SystemCapability.ArkUI.ArkUI.Full 645 646**参数：** 647 648| 参数名 | 类型 | 必填 | 说明 | 649| ------ | ---- | ---- | ------------ | 650| getter | [GetterCallback\<T\>](#gettercallback20) | 是 | 获取值的回调函数，每次访问值都会重新执行函数，获取最新值。 | 651| setter | [SetterCallback\<T\>](#settercallback20) | 是 | 定义如何更新值，当`.value`被修改时自动调用此函数。 | 652 653**返回值：** 654 655| 类型 | 说明 | 656| ---- | ------------------------------------------------ | 657| [MutableBinding\<T\>](#mutablebindingt20) | 包含一个`value`属性，支持通过`.value`读取和修改数据，设置值时会检查类型是否匹配泛型`T`。 | 658 659**示例：** 660 661```ts 662import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 663 664@Builder 665function CustomButton(num2: MutableBinding<number>) { 666 Row() { 667 Button(`Custom Button: ${num2.value}`) 668 .onClick(() => { 669 // MutableBinding类型支持修改 670 num2.value += 1; 671 }) 672 } 673} 674 675@Entry 676@ComponentV2 677struct CompV2 { 678 @Local number1: number = 5; 679 @Local number2: number = 10; 680 681 build() { 682 Column() { 683 Text('parent component') 684 685 CustomButton( 686 /** 687 * 创建可变绑定 688 * @param getter - 返回this.number2的函数 689 * @param setter - 当绑定值修改时调用的回调 690 * @returns 可变的MutableBinding<number>对象 691 * 692 * 特点： 693 * 1. 支持读取和写入操作 694 * 2. 修改.value时会自动调用setter回调 695 */ 696 UIUtils.makeBinding<number>( 697 () => this.number2, // GetterCallback 698 (val: number) => { 699 this.number2 = val; 700 }) // SetterCallback 701 ) 702 } 703 } 704} 705``` 706 707### addMonitor<sup>20+</sup> 708static addMonitor(target: object, path: string | string[], monitorCallback: MonitorCallback, options?: MonitorOptions): void 709 710给状态管理V2的状态变量动态添加监听方法，详见[addMonitor/clearMonitor](../../ui/state-management/arkts-new-addMonitor-clearMonitor.md)。 711 712**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 713 714**系统能力：** SystemCapability.ArkUI.ArkUI.Full 715 716**参数：** 717 718| 参数名 | 类型 | 必填 | 说明 | 719| ------ | ---- | ---- | ------------ | 720| target | object | 是 | 目标对象，仅支持[\@ComponentV2](../../ui/state-management/arkts-new-componentV2.md)和[\@ObservedV2](../../ui/state-management/arkts-new-observedV2-and-trace.md)实例。</br>对于不支持的类型，会抛出运行时错误，错误码见表格。 | 721| path | string \| string[] | 是 | 添加监听的变量名路径。可指定一个路径或者传入string数组用于一次性指定多个监听的变量路径。</br>仅支持string和string数组，对于不支持的类型，会抛出运行时错误，错误码见表格。 | 722| monitorCallback | [MonitorCallback](#monitorcallback20) | 是 | 给对应的状态变量注册的监听函数，即path路径对应的状态变量改变时，会回调对应的函数。</br>对于不支持的类型，会抛出运行时错误，错误码见表格。 | 723| options | [MonitorOptions](#monitoroptions20) | 否 | 监听函数的配置项，具体可见[MonitorOptions](#monitoroptions20)。 | 724 725 726**错误码：** 727以下错误码的详细介绍请参见[状态管理错误码](./errorcode-stateManagement.md)。 728| 错误码ID | 错误信息 | 729| ------- | -------------------------------- | 730|130000|The target is not a custom component instance or V2 class instance.| 731|130001|The path is invalid.| 732|130002|monitorCallback is not a function or an anonymous function.| 733 734**示例：** 735下面的示例： 7361. 在`ObservedClass`的构造方法里，添加对`name`属性的同步监听回调`onChange`。 7372. 点击Text组件，将`name`改为`Jack`和`Jane`，触发两次`onChange`回调，打印日志如下。 738<!--code_no_check--> 739``` 740ObservedClass property name change from Tom to Jack 741ObservedClass property name change from Jack to Jane 742``` 743 744```ts 745import { UIUtils } from '@kit.ArkUI'; 746 747@ObservedV2 748class ObservedClass { 749 @Trace name: string = 'Tom'; 750 751 onChange(mon: IMonitor) { 752 mon.dirty.forEach((path: string) => { 753 console.info(`ObservedClass property ${path} change from ${mon.value(path)?.before} to ${mon.value(path)?.now}`); 754 }); 755 } 756 757 constructor() { 758 // 给当前ObservedClass的实例this添加对属性name的监听回调this.onChange，且当前监听回调是同步监听 759 UIUtils.addMonitor(this, 'name', this.onChange, { isSynchronous: true }); 760 } 761} 762 763@Entry 764@ComponentV2 765struct Index { 766 @Local observedClass: ObservedClass = new ObservedClass(); 767 768 build() { 769 Column() { 770 Text(`name: ${this.observedClass.name}`) 771 .fontSize(20) 772 .onClick(() => { 773 this.observedClass.name = 'Jack'; 774 this.observedClass.name = 'Jane'; 775 }) 776 } 777 } 778} 779``` 780 781### clearMonitor<sup>20+</sup> 782static clearMonitor(target: object, path: string | string[], monitorCallback?: MonitorCallback): void 783 784删除通过[addMonitor](#addmonitor20)给状态管理V2的状态变量添加的监听方法，详见[addMonitor/clearMonitor](../../ui/state-management/arkts-new-addMonitor-clearMonitor.md)。 785 786**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 787 788**系统能力：** SystemCapability.ArkUI.ArkUI.Full 789 790**参数：** 791 792| 参数名 | 类型 | 必填 | 说明 | 793| ------ | ---- | ---- | ------------ | 794| target | object | 是 | 目标对象，仅支持[\@ComponentV2](../../ui/state-management/arkts-new-componentV2.md)和[\@ObservedV2](../../ui/state-management/arkts-new-observedV2-and-trace.md)实例。</br>对于不支持的类型，会抛出运行时错误，错误码见表格。 | 795| path | string \| string[] | 是 | 删除监听的变量名路径。可指定一个路径或者传入string数组用于一次性指定删除多个状态变量的监听函数。</br>仅支持string和数组，对于不支持的类型，会抛出运行时错误，错误码见表格。 | 796| monitorCallback | [MonitorCallback](#monitorcallback20) | 否 | 指定被删除的监听函数。</br>当开发者不传此参数时，将删除path对应变量注册的所有监听函数。</br>对于不支持的类型，会抛出运行时错误，错误码见表格。 | 797 798**错误码：** 799以下错误码的详细介绍请参见[状态管理错误码](./errorcode-stateManagement.md)。 800| 错误码ID | 错误信息 | 801| ------- | -------------------------------- | 802|130000|The target is not a custom component instance or V2 class instance.| 803|130001|The path is invalid.| 804|130002|monitorCallback is not a function or an anonymous function.| 805 806**示例：** 807在下面的示例中： 8081. 在`ObservedClass`的构造方法中，添加对`age`属性的同步监听回调`onChange`。 8092. 点击Text组件，触发`age`自增，`onChange`的监听回调函数被触发。打印日志如下。 810<!--code_no_check--> 811``` 812ObservedClass property age change from 10 to 11 813``` 8143. 点击`clear monitor`，删除`age`的监听函数`onChange`。 8154. 再次点击Text组件，触发`age`自增，`onChange`不会被触发。 816 817```ts 818import { UIUtils } from '@kit.ArkUI'; 819 820@ObservedV2 821class ObservedClass { 822 @Trace age: number = 10; 823 824 onChange(mon: IMonitor) { 825 mon.dirty.forEach((path: string) => { 826 console.info(`ObservedClass property ${path} change from ${mon.value(path)?.before} to ${mon.value(path)?.now}`); 827 }); 828 } 829 830 constructor() { 831 // 给当前ObservedClass的实例this添加对属性name的监听回调this.onChange，且当前监听回调是同步监听 832 UIUtils.addMonitor(this, 'age', this.onChange); 833 } 834} 835 836@Entry 837@ComponentV2 838struct Index { 839 @Local observedClass: ObservedClass = new ObservedClass(); 840 841 build() { 842 Column() { 843 Text(`age: ${this.observedClass.age}`) 844 .fontSize(20) 845 .onClick(() => { 846 // 点击触发age++，触发onChange回调 847 this.observedClass.age++; 848 }) 849 Button('clear monitor') 850 .onClick(() => { 851 // 点击clearMonitor，删除this.observedClass中age的监听函数onChange 852 // 再次点击触发age++，没有触发监听函数onChange 853 UIUtils.clearMonitor(this.observedClass, 'age', this.observedClass.onChange); 854 }) 855 } 856 } 857} 858``` 859 860## MonitorOptions<sup>20+</sup> 861 862[addMonitor](#addmonitor20)的可选参数，用于配置回调类型。 863 864**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 865 866**系统能力：** SystemCapability.ArkUI.ArkUI.Full 867 868| 名称 | 类型 | 只读 | 可选 | 说明 | 869| ------ | ---- | ---- | ---- | ------------ | 870|isSynchronous|boolean|否|是|配置当前回调函数否是为同步回调。true为同步回调。默认值为false，即异步回调。| 871 872## MonitorCallback<sup>20+</sup> 873type MonitorCallback = (monitorValue: IMonitor) => void 874 875参数为[IMonitor](./arkui-ts/ts-state-management-watch-monitor.md#imonitor12)类型的监听回调函数。 876 877**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 878 879**系统能力：** SystemCapability.ArkUI.ArkUI.Full 880 881**参数：** 882 883| 参数名 | 类型 | 必填 | 说明 | 884| ------ | ---- | ---- | ------------ | 885| monitorValue | IMonitor | 是 | 回调函数传入的变化信息。 | 886 887## StorageDefaultCreator\<T\> 888 889type StorageDefaultCreator\<T\> = () => T 890 891返回默认构造器的函数。 892 893**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 894 895**系统能力：** SystemCapability.ArkUI.ArkUI.Full 896 897**返回值：** 898 899| 类型 | 说明 | 900| ---- | ------------------------------------------------ | 901| T | 默认构造器执行得到的返回值。 | 902 903**示例：** 904 905```ts 906import { PersistenceV2 } from '@kit.ArkUI'; 907 908@ObservedV2 909class SampleClass { 910 @Trace id: number = 0; 911 count: number = 1; 912} 913 914@ObservedV2 915class FatherSampleClass { 916 @Trace sampleClass: SampleClass = new SampleClass(); 917} 918 919// 将key为SampleClass、value为new SampleClass()对象的键值对持久化，并赋值给source 920// StorageDefaultCreator 指的是 () => new FatherSampleClass() 921const source: FatherSampleClass | undefined = PersistenceV2.connect(FatherSampleClass, () => new FatherSampleClass()); 922 923@Entry 924@Component 925struct SampleComp { 926 data: FatherSampleClass | undefined = source; 927 928 build() { 929 Column() { 930 Text(`${this.data?.sampleClass.id}`) 931 } 932 } 933} 934``` 935 936## TypeConstructorWithArgs\<T\> 937 938含有任意入参的类构造器。 939 940**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 941 942**系统能力：** SystemCapability.ArkUI.ArkUI.Full 943 944### new 945 946new(...args: any): T 947 948创建并返回一个指定类型T的实例。 949 950**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 951 952**系统能力：** SystemCapability.ArkUI.ArkUI.Full 953 954**参数：** 955 956| 参数名 | 类型 | 必填 | 说明 | 957| ------ | ---- | ---- | ------------ | 958| ...args | any | 否 | 函数入参。 | 959 960**返回值：** 961 962| 类型 | 说明 | 963| ---- | ------------------------------------------------ | 964| T | T类型的实例。 | 965 966**示例：** 967 968```ts 969import { PersistenceV2 } from '@kit.ArkUI'; 970 971@ObservedV2 972 // TypeConstructorWithArgs 指的是 SampleClass 973class SampleClass { 974 @Trace id: number = 0; 975 count: number = 1; 976} 977 978@ObservedV2 979class FatherSampleClass { 980 @Trace sampleClass: SampleClass = new SampleClass(); 981} 982 983// 将key为SampleClass、value为new SampleClass()对象的键值对持久化，并赋值给source 984const source: FatherSampleClass | undefined = PersistenceV2.connect(FatherSampleClass, () => new FatherSampleClass()); 985 986@Entry 987@Component 988struct SampleComp { 989 data: FatherSampleClass | undefined = source; 990 991 build() { 992 Column() { 993 Text(`${this.data?.sampleClass.id}`) 994 } 995 } 996} 997``` 998 999## PersistenceErrorCallback 1000 1001type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void 1002 1003持久化失败时返回错误原因的回调。 1004 1005**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1006 1007**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1008 1009**参数：** 1010 1011| 参数名 | 类型 | 必填 | 说明 | 1012| ------ | ---- | ---- | ------------ | 1013| key | string | 是 | 出错的键值。 | 1014|reason| 'quota' \| 'serialization' \| 'unknown' | 是 | 出错的原因类型。 | 1015| message | string | 是 | 出错的更多消息。 | 1016 1017**示例：** 1018 1019```ts 1020import { PersistenceV2, Type } from '@kit.ArkUI'; 1021 1022@ObservedV2 1023class SampleChild { 1024 @Trace id: number = 0; 1025 count: number = 10; 1026} 1027 1028@ObservedV2 1029export class Sample { 1030 // 对于复杂对象需要@Type修饰，确保序列化成功 1031 @Type(SampleChild) 1032 @Trace sampleChild: SampleChild = new SampleChild(); 1033} 1034 1035// 接受序列化失败的回调 1036// PersistenceErrorCallback 指的是 (key: string, reason: string, msg: string) => {console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`);} 1037PersistenceV2.notifyOnError((key: string, reason: string, msg: string) => { 1038 console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`); 1039}); 1040 1041@Entry 1042@ComponentV2 1043struct Index { 1044 // 在PersistenceV2中创建一个key为Sample的键值对（如果存在，则返回PersistenceV2中的数据），并且和data关联 1045 // 对于需要换connect对象的data属性，需要加@Local修饰（不建议对属性换connect的对象） 1046 @Local data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 1047 pageStack: NavPathStack = new NavPathStack(); 1048 1049 build() { 1050 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 1051 .fontSize(30) 1052 .onClick(() => { 1053 this.data.sampleChild.id++; 1054 }) 1055 } 1056} 1057``` 1058 1059## TypeConstructor\<T\> 1060 1061类构造函数。 1062 1063**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1064 1065**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1066 1067### new 1068 1069new(): T 1070 1071创建并返回一个指定类型T的实例。 1072 1073**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1074 1075**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1076 1077**返回值：** 1078 1079| 类型 | 说明 | 1080| ---- | ------------------------------------------------ | 1081| T | T类型的实例。 | 1082 1083**示例：** 1084 1085```ts 1086import { PersistenceV2, Type } from '@kit.ArkUI'; 1087 1088@ObservedV2 1089class SampleChild { 1090 @Trace id: number = 0; 1091 count: number = 10; 1092} 1093 1094@ObservedV2 1095export class Sample { 1096 // 对于复杂对象需要@Type修饰，确保序列化成功 1097 // TypeConstructor 指的是 SampleChild 1098 @Type(SampleChild) 1099 @Trace sampleChild: SampleChild = new SampleChild(); 1100} 1101 1102@Entry 1103@ComponentV2 1104struct Index { 1105 data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 1106 1107 build() { 1108 Column() { 1109 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 1110 .fontSize(30) 1111 .onClick(() => { 1112 this.data.sampleChild.id++; 1113 }) 1114 } 1115 } 1116} 1117``` 1118 1119## TypeDecorator 1120 1121type TypeDecorator = \<T\>(type: TypeConstructor\<T\>) => PropertyDecorator 1122 1123属性装饰器。 1124 1125**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1126 1127**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1128 1129**参数：** 1130 1131| 参数名 | 类型 | 必填 | 说明 | 1132| ------ | ---- | ---- | ------------ | 1133| type | [TypeConstructor\<T\>](#typeconstructort) | 是 | 标记类属性的类型。 | 1134 1135**返回值：** 1136 1137| 类型 | 说明 | 1138| ---- | ------------------------------------------------ | 1139| PropertyDecorator | 属性装饰器。 | 1140 1141**示例：** 1142 1143```ts 1144import { PersistenceV2, Type } from '@kit.ArkUI'; 1145 1146@ObservedV2 1147class SampleChild { 1148 @Trace id: number = 0; 1149 count: number = 10; 1150} 1151 1152@ObservedV2 1153export class Sample { 1154 // 对于复杂对象需要@Type修饰，确保序列化成功 1155 // TypeDecorator 指的是 @Type 1156 @Type(SampleChild) 1157 @Trace sampleChild: SampleChild = new SampleChild(); 1158} 1159 1160@Entry 1161@ComponentV2 1162struct Index { 1163 data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 1164 1165 build() { 1166 Column() { 1167 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 1168 .fontSize(30) 1169 .onClick(() => { 1170 this.data.sampleChild.id++; 1171 }) 1172 } 1173 } 1174} 1175``` 1176 1177## GetterCallback<sup>20+</sup> 1178 1179type GetterCallback\<T\> = () => T 1180 1181获取值的回调方法。 1182 1183**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1184 1185**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1186 1187**返回值：** 1188 1189| 类型 | 说明 | 1190| ---- | ------------------------------------------------ | 1191| T | T类型的值。 | 1192 1193**示例：** 1194 1195```ts 1196import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 1197 1198@Builder 1199function CustomButton(num1: Binding<number>) { 1200 Row() { 1201 Button(`Custom Button: ${num1.value}`) 1202 .onClick(() => { 1203 // num1.value += 1; 会报错，Binding类型不支持修改 1204 }) 1205 } 1206} 1207 1208@Entry 1209@ComponentV2 1210struct CompV2 { 1211 @Local number1: number = 5; 1212 @Local number2: number = 10; 1213 1214 build() { 1215 Column() { 1216 Text('parent component') 1217 1218 CustomButton( 1219 // 对于UIUtils.makeBinding函数的第一个参数需要传入GetterCallback 1220 UIUtils.makeBinding<number>( 1221 () => this.number1 // GetterCallback 1222 ) 1223 ) 1224 } 1225 } 1226} 1227``` 1228 1229## SetterCallback<sup>20+</sup> 1230 1231type SetterCallback\<T\> = (newValue: T) => void 1232 1233设置值的回调方法。 1234 1235**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1236 1237**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1238 1239**参数：** 1240 1241| 参数名 | 类型 | 必填 | 说明 | 1242| ------ | ---- | ---- | ------------ | 1243| newValue | T | 是 | 类型为T的参数。 | 1244 1245**示例：** 1246 1247```ts 1248import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 1249 1250@Builder 1251function CustomButton(num2: MutableBinding<number>) { 1252 Row() { 1253 Button(`Custom Button: ${num2.value}`) 1254 .onClick(() => { 1255 // MutableBinding支持可变，可以修改num2.value 1256 num2.value += 1; 1257 }) 1258 } 1259} 1260 1261@Entry 1262@ComponentV2 1263struct CompV2 { 1264 @Local number1: number = 5; 1265 @Local number2: number = 10; 1266 1267 build() { 1268 Column() { 1269 Text('parent component') 1270 1271 CustomButton( 1272 // 对于UIUtils.makeBinding函数的第二个参数需要传入SetterCallback 1273 UIUtils.makeBinding<number>( 1274 () => this.number2, // GetterCallback 1275 (val: number) => { 1276 this.number2 = val; 1277 }) // SetterCallback 必须提供，否则触发时会造成运行时错误 1278 ) 1279 } 1280 } 1281} 1282``` 1283 1284## Binding\<T\><sup>20+</sup> 1285 1286只读数据绑定的泛型类，可以绑定任意类型的数据。 1287 1288**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1289 1290### value<sup>20+</sup> 1291get value(): T 1292 1293提供get访问器，用于获取绑定的值。 1294 1295**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1296 1297**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1298 1299**返回值：** 1300 1301| 类型 | 说明 | 1302| -------------------- | ------------------------------------------------------------ | 1303| T |返回值类型为泛型参数T，与Binding\<T\>定义的类型一致。| 1304 1305**示例：** 1306 1307```ts 1308import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 1309 1310@Builder 1311function CustomButton(num1: Binding<number>) { 1312 // CustomButton的第一个参数为Binding，一个只读数据绑定的泛型类 1313 Row() { 1314 // num1.value Binding类可以使用绑定的值 1315 Button(`Custom Button: ${num1.value}`) 1316 .onClick(() => { 1317 // num1.value += 1; 会报错，只读数据绑定的泛型类不能修改值 1318 }) 1319 } 1320} 1321 1322@Entry 1323@ComponentV2 1324struct CompV2 { 1325 @Local number1: number = 5; 1326 @Local number2: number = 10; 1327 1328 build() { 1329 Column() { 1330 Text('parent component') 1331 1332 CustomButton( 1333 UIUtils.makeBinding<number>( 1334 () => this.number1 // GetterCallback 1335 ) 1336 ) 1337 } 1338 } 1339} 1340``` 1341 1342## MutableBinding\<T\><sup>20+</sup> 1343 1344可变数据绑定的泛型类，允许对绑定值进行读写操作，提供完整的get和set访问器。 1345 1346**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1347 1348### value<sup>20+</sup> 1349set value(newValue: T) 1350 1351提供set访问器，用于设置当前绑定值的值。构造MutableBinding类实例时必须提供set访问器，否则触发set访问器会造成运行时错误。 1352 1353**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1354 1355**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1356 1357**参数：** 1358 1359| 参数名 | 类型 | 必填 | 说明 | 1360| ------ | ------ | ---- | -------------------------------------- | 1361| newValue | T | 是 | 参数类型为泛型参数T，与MutableBinding\<T\>定义的类型一致。 | 1362 1363### value<sup>20+</sup> 1364get value(): T 1365 1366提供get访问器，用于获取当前绑定值。 1367 1368**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1369 1370**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1371 1372**返回值：** 1373 1374| 类型 | 说明 | 1375| -------------------- | ------------------------------------------------------------ | 1376| T |返回值类型为泛型参数T，与Binding\<T\>定义的类型一致。| 1377 1378**示例：** 1379 1380```ts 1381import { Binding, MutableBinding, UIUtils } from '@kit.ArkUI'; 1382 1383@Builder 1384function CustomButton(num2: MutableBinding<number>) { 1385 // CustomButton的第二个参数为MutableBinding，一个可变数据绑定的泛型类 1386 Row() { 1387 Button(`Custom Button: ${num2.value}`) 1388 .onClick(() => { 1389 // 可变数据绑定的泛型类可以修改绑定的值 1390 num2.value += 1; 1391 }) 1392 } 1393} 1394 1395@Entry 1396@ComponentV2 1397struct CompV2 { 1398 @Local number1: number = 5; 1399 @Local number2: number = 10; 1400 1401 build() { 1402 Column() { 1403 Text('parent component') 1404 1405 CustomButton( 1406 UIUtils.makeBinding<number>( 1407 () => this.number2, // GetterCallback 1408 (val: number) => { 1409 this.number2 = val; 1410 }) // SetterCallback 必须提供，否则触发时会造成运行时错误 1411 ) 1412 } 1413 } 1414} 1415```