1# @ohos.arkui.StateManagement (状态管理) 2 3状态管理模块提供了应用程序的数据存储能力、持久化数据管理能力、UIAbility数据存储能力和应用程序需要的环境状态、工具。 4 5>**说明:** 6> 7>本模块首批接口从API version 12开始支持,后续版本的新增接口,采用上角标单独标记接口的起始版本。 8 9 10本文中T和S的含义如下: 11 12 13| 类型 | 说明 | 14| ---- | -------------------------------------- | 15| T | Class,number,boolean,string和这些类型的数组形式。 | 16| S | number,boolean,string。 | 17 18 19## 导入模块 20 21```ts 22import { AppStorageV2,PersistenceV2,UIUtils} from '@kit.ArkUI'; 23``` 24 25## AppStorageV2 26 27AppStorageV2具体UI使用说明,详见[AppStorageV2(应用全局的UI状态存储)](../../quick-start/arkts-new-appstoragev2.md)。 28 29**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 30 31**系统能力:** SystemCapability.ArkUI.ArkUI.Full 32 33### connect 34 35static connect\<T extends object\>( </br > 36 type: TypeConstructorWithArgs\<T\>, </br > 37 keyOrDefaultCreator?: string | StorageDefaultCreator\<T\>, </br > 38 defaultCreator?: StorageDefaultCreator\<T\> </br > 39): T | undefined; 40 41将键值对数据储存在应用内存中。如果给定的key已经存在于[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)中,返回对应的值;否则,通过获取默认值的构造器构造默认值,并返回。 42 43**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 44 45**系统能力:** SystemCapability.ArkUI.ArkUI.Full 46 47**参数:** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| -------- | ------ | ---- | ---------------------- | 51| type | [TypeConstructorWithArgs\<T\>](#typeconstructorwithargst) | 是 | 指定的类型,若未指定key,则使用type的name作为key。 | 52| keyOrDefaultCreator | string \| [StorageDefaultCreator\<T\>](#storagedefaultcreatort) | 否 | 指定的key,或者是获取默认值的构造器。 | 53| defaultCreator | StorageDefaultCreator\<T\> | 否 | 获取默认值的构造器。 | 54 55>**说明:** 56> 57>1、若未指定key,使用第二个参数作为默认构造器;否则使用第三个参数作为默认构造器; 58> 59>2、确保数据已经存储在AppStorageV2中,可省略默认构造器,获取存储的数据;否则必须指定默认构造器,不指定将导致应用异常; 60> 61>3、同一个key,connect不同类型的数据会导致应用异常,应用需要确保类型匹配; 62> 63>4、key建议使用有意义的值,长度不超过255,使用非法字符或空字符的行为是未定义的。 64 65**返回值:** 66 67| 类型 | 说明 | 68| -------------------------------------- | ------------------------------------------------------------ | 69| T | 创建或获取AppStorageV2数据成功时,返回数据;否则返回undefined。 | 70 71**示例:** 72 73```ts 74import { AppStorageV2 } from '@kit.ArkUI'; 75 76@ObservedV2 77class SampleClass { 78 @Trace p: number = 0; 79} 80 81// 将key为SampleClass、value为new SampleClass()对象的键值对存储到内存中,并赋值给as1 82const as1: SampleClass | undefined = AppStorageV2.connect(SampleClass, () => new SampleClass()); 83 84// 将key为key_as2、value为new SampleClass()对象的键值对存储到内存中,并赋值给as2 85const as2: SampleClass = AppStorageV2.connect(SampleClass, 'key_as2', () => new SampleClass())!; 86 87// key为SampleClass已经在AppStorageV2中,将key为SampleClass的值返回给as3 88const as3: SampleClass = AppStorageV2.connect(SampleClass) as SampleClass; 89``` 90 91### remove 92 93static remove\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void; 94 95将指定的键值对数据从[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)里面删除。如果指定的键值不存在于AppStorageV2中,将删除失败。 96 97**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 98 99**系统能力:** SystemCapability.ArkUI.ArkUI.Full 100 101**参数:** 102 103| 参数名 | 类型 | 必填 | 说明 | 104| -------- | ------ | ---- | ---------------------- | 105| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要删除的key;如果指定的是type类型,删除的key为type的name。 | 106 107>**说明:** 108> 109>删除AppStorageV2中不存在的key会报警告。 110 111 112**示例:** 113 114<!--code_no_check--> 115```ts 116// 假设AppStorageV2中存在key为key_as2的键,从AppStorageV2中删除该键值对数据 117AppStorageV2.remove('key_as2'); 118 119// 假设AppStorageV2中存在key为SampleClass的键,从AppStorageV2中删除该键值对数据 120AppStorageV2.remove(SampleClass); 121 122// 假设AppStorageV2中不存在key为key_as1的键,报警告 123AppStorageV2.remove('key_as1'); 124``` 125 126### keys 127 128static keys(): Array\<string\>; 129 130获取[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)中的所有key。 131 132**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 133 134**系统能力:** SystemCapability.ArkUI.ArkUI.Full 135 136**返回值:** 137 138| 类型 | 说明 | 139| -------------------------------------- | ------------------------------------------------------------ | 140| Array\<string\> | 所有AppStorageV2中的key。 | 141 142>**说明:** 143> 144>key在Array中的顺序是无序的,与key插入到AppStorageV2中的顺序无关。 145 146**示例:** 147 148```ts 149// 假设AppStorageV2中存在两个key(key_as1、key_as2),返回[key_as1、key_as2]赋值给keys 150const keys: Array<string> = AppStorageV2.keys(); 151``` 152 153 154 155## PersistenceV2 156 157继承自[AppStorageV2](#appstoragev2),PersistenceV2具体UI使用说明,详见[PersistenceV2(持久化存储UI状态)](../../quick-start/arkts-new-persistencev2.md)。 158 159**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 160 161**系统能力:** SystemCapability.ArkUI.ArkUI.Full 162 163### save 164 165static save\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void; 166 167将指定的键值对数据持久化一次。 168 169**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 170 171**系统能力:** SystemCapability.ArkUI.ArkUI.Full 172 173**参数:** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| -------- | ------ | ---- | ---------------------- | 177| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要持久化的key;如果指定的是type类型,持久化的key为type的name。 | 178 179>**说明:** 180> 181>由于非[\@Trace](../../quick-start/arkts-new-observedV2-and-trace.md)的数据改变不会触发[PersistenceV2](../../quick-start/arkts-new-persistencev2.md)的自动持久化,如有必要,可调用该接口持久化对应key的数据; 182> 183>手动持久化当前内存中不处于connect状态的key是无意义的。 184 185**示例:** 186 187<!--code_no_check--> 188 189```ts 190// 假设PersistenceV2中存在key为key_as2的键,持久化该键值对数据 191PersistenceV2.save('key_as2'); 192 193// 假设PersistenceV2中存在key为SampleClass的键,持久化该键值对数据 194PersistenceV2.remove(SampleClass); 195 196// 假设PersistenceV2中不存在key为key_as1的键,无意义的操作 197PersistenceV2.remove('key_as1'); 198``` 199 200### notifyOnError 201 202static notifyOnError(callback: PersistenceErrorCallback | undefined): void; 203 204在持久化失败时调用。 205 206**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 207 208**系统能力:** SystemCapability.ArkUI.ArkUI.Full 209 210**参数:** 211 212| 参数名 | 类型 | 必填 | 说明 | 213| -------- | ------ | ---- | ---------------------- | 214| callback | PersistenceErrorCallback \| undefined | 是 | 持久化失败时调用。 | 215 216**示例:** 217 218```ts 219// 持久化失败时调用 220PersistenceV2.notifyOnError((key: string, reason: string, msg: string) => { 221 console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`); 222}); 223``` 224 225## UIUtils 226 227UIUtils提供一些方法,用于处理状态管理相关的数据转换。 228 229**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 230 231**系统能力:** SystemCapability.ArkUI.ArkUI.Full 232 233### getTarget 234 235static getTarget\<T extends object\>(source: T): T; 236 237从状态管理框架包裹的代理对象中获取原始对象。详见[getTarget接口:获取状态管理框架代理前的原始对象](../../quick-start/arkts-new-getTarget.md)。 238 239**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 240 241**系统能力:** SystemCapability.ArkUI.ArkUI.Full 242 243**参数:** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| ------ | ---- | ---- | ------------ | 247| source | T | 是 | 数据源对象。 | 248 249**返回值:** 250 251| 类型 | 说明 | 252| ---- | ------------------------------------------------ | 253| T | 数据源对象去除状态管理框架所加代理后的原始对象。 | 254 255**示例:** 256 257```ts 258import { UIUtils } from '@kit.ArkUI'; 259class NonObservedClass { 260 name: string = "Tom"; 261} 262let nonObservedClass: NonObservedClass = new NonObservedClass(); 263@Entry 264@Component 265struct Index { 266 @State someClass: NonObservedClass = nonObservedClass; 267 build() { 268 Column() { 269 Text(`this.someClass === nonObservedClass: ${this.someClass === nonObservedClass}`) // false 270 Text(`UIUtils.getTarget(this.someClass) === nonObservedClass: ${UIUtils.getTarget(this.someClass) === 271 nonObservedClass}`) // true 272 } 273 } 274} 275``` 276### makeObserved 277 278static makeObserved\<T extends object\>(source: T): T; 279 280将普通不可观察数据变为可观察数据。详见[makeObserved接口:将非观察数据变为可观察数据](../../quick-start/arkts-new-makeObserved.md)。 281 282**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 283 284**系统能力:** SystemCapability.ArkUI.ArkUI.Full 285 286**参数:** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------ | ---- | ---- | ------------ | 290| source | T | 是 | 数据源对象。支持非@Observed和@ObserveV2修饰的class,JSON.parse返回的Object和@Sendable修饰的class。</br>支持Array、Map、Set和Date。</br>支持collection.Array, collection.Set和collection.Map。</br>具体使用规则,详见[makeObserved接口:将非观察数据变为可观察数据](../../quick-start/arkts-new-makeObserved.md)。 | 291 292**返回值:** 293 294| 类型 | 说明 | 295| ---- | ------------------------------------------------ | 296| T | 可观察的数据。 | 297 298**示例:** 299 300```ts 301import { UIUtils } from '@kit.ArkUI'; 302class NonObservedClass { 303 name: string = 'Tom'; 304} 305 306@Entry 307@ComponentV2 308struct Index { 309 observedClass: NonObservedClass = UIUtils.makeObserved(new NonObservedClass()); 310 nonObservedClass: NonObservedClass = new NonObservedClass(); 311 build() { 312 Column() { 313 Text(`observedClass: ${this.observedClass.name}`) 314 .onClick(() => { 315 this.observedClass.name = 'Jane'; // 刷新 316 }) 317 Text(`observedClass: ${this.nonObservedClass.name}`) 318 .onClick(() => { 319 this.nonObservedClass.name = 'Jane'; // 不刷新 320 }) 321 } 322 } 323} 324``` 325 326## StorageDefaultCreator\<T\> 327 328type StorageDefaultCreator\<T\> = () => T; 329 330返回默认构造器的函数。 331 332**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 333 334**系统能力:** SystemCapability.ArkUI.ArkUI.Full 335 336**返回值:** 337 338| 类型 | 说明 | 339| ---- | ------------------------------------------------ | 340| () => T | 返回默认构造器的函数。 | 341 342**示例:** 343 344```ts 345import { PersistenceV2 } from '@kit.ArkUI'; 346 347@ObservedV2 348class SampleClass { 349 @Trace id: number = 0; 350 count: number = 1; 351} 352 353@ObservedV2 354class FatherSampleClass { 355 @Trace sampleClass: SampleClass = new SampleClass(); 356} 357 358// 将key为SampleClass、value为new SampleClass()对象的键值对持久化,并赋值给source 359// StorageDefaultCreator 指的是 () => new FatherSampleClass() 360const source: FatherSampleClass | undefined = PersistenceV2.connect(FatherSampleClass, () => new FatherSampleClass()); 361 362@Entry 363@Component 364struct SampleComp { 365 data: FatherSampleClass | undefined = source; 366 367 build() { 368 Column() { 369 Text(`${this.data?.sampleClass.id}`) 370 } 371 } 372} 373``` 374 375## TypeConstructorWithArgs\<T\> 376 377含有任意入参的类构造器。 378 379**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 380 381**系统能力:** SystemCapability.ArkUI.ArkUI.Full 382 383### new 384 385new(...args: any): T; 386 387**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 388 389**系统能力:** SystemCapability.ArkUI.ArkUI.Full 390 391**参数:** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| ------ | ---- | ---- | ------------ | 395| ...args | any | 是 | 函数入参。 | 396 397**返回值:** 398 399| 类型 | 说明 | 400| ---- | ------------------------------------------------ | 401| T | T类型的实例。 | 402 403**示例:** 404 405```ts 406import { PersistenceV2 } from '@kit.ArkUI'; 407 408@ObservedV2 409 // TypeConstructorWithArgs 指的是 SampleClass 410class SampleClass { 411 @Trace id: number = 0; 412 count: number = 1; 413} 414 415@ObservedV2 416class FatherSampleClass { 417 @Trace sampleClass: SampleClass = new SampleClass(); 418} 419 420// 将key为SampleClass、value为new SampleClass()对象的键值对持久化,并赋值给source 421const source: FatherSampleClass | undefined = PersistenceV2.connect(FatherSampleClass, () => new FatherSampleClass()); 422 423@Entry 424@Component 425struct SampleComp { 426 data: FatherSampleClass | undefined = source; 427 428 build() { 429 Column() { 430 Text(`${this.data?.sampleClass.id}`) 431 } 432 } 433} 434``` 435 436## PersistenceErrorCallback 437 438type PersistenceErrorCallback = (key: string, reason: 'quota' | 'serialization' | 'unknown', message: string) => void; 439 440持久化失败时返回错误原因的回调。 441 442**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 443 444**系统能力:** SystemCapability.ArkUI.ArkUI.Full 445 446**参数:** 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ------ | ---- | ---- | ------------ | 450| key | string | 是 | 出错的键值。 | 451|reason| 'quota' \| 'serialization' \| 'unknown' | 是 | 出错的原因类型。 | 452| message | string | 是 | 出错的更多消息。 | 453 454**示例:** 455 456```ts 457import { PersistenceV2, Type } from '@kit.ArkUI'; 458 459@ObservedV2 460class SampleChild { 461 @Trace id: number = 0; 462 count: number = 10; 463} 464 465@ObservedV2 466export class Sample { 467 // 对于复杂对象需要@Type修饰,确保序列化成功 468 @Type(SampleChild) 469 @Trace sampleChild: SampleChild = new SampleChild(); 470} 471 472// 接受序列化失败的回调 473// PersistenceErrorCallback 指的是 (key: string, reason: string, msg: string) => {console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`);} 474PersistenceV2.notifyOnError((key: string, reason: string, msg: string) => { 475 console.error(`error key: ${key}, reason: ${reason}, message: ${msg}`); 476}); 477 478@Entry 479@ComponentV2 480struct Index { 481 // 在PersistenceV2中创建一个key为Sample的键值对(如果存在,则返回PersistenceV2中的数据),并且和data关联 482 // 对于需要换connect对象的data属性,需要加@Local修饰(不建议对属性换connect的对象) 483 @Local data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 484 pageStack: NavPathStack = new NavPathStack(); 485 486 build() { 487 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 488 .fontSize(30) 489 .onClick(() => { 490 this.data.sampleChild.id++; 491 }) 492 } 493} 494``` 495 496## TypeConstructor\<T\> 497 498类构造函数。 499 500**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 501 502**系统能力:** SystemCapability.ArkUI.ArkUI.Full 503 504### new 505 506new(): T; 507 508**返回值:** 509 510| 类型 | 说明 | 511| ---- | ------------------------------------------------ | 512| T | T类型的实例。 | 513 514**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 515 516**系统能力:** SystemCapability.ArkUI.ArkUI.Full 517 518**示例:** 519 520```ts 521import { PersistenceV2, Type } from '@kit.ArkUI'; 522 523@ObservedV2 524class SampleChild { 525 @Trace id: number = 0; 526 count: number = 10; 527} 528 529@ObservedV2 530export class Sample { 531 // 对于复杂对象需要@Type修饰,确保序列化成功 532 // TypeConstructor 指的是 SampleChild 533 @Type(SampleChild) 534 @Trace sampleChild: SampleChild = new SampleChild(); 535} 536 537@Entry 538@ComponentV2 539struct Index { 540 data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 541 542 build() { 543 Column() { 544 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 545 .fontSize(30) 546 .onClick(() => { 547 this.data.sampleChild.id++; 548 }) 549 } 550 } 551} 552``` 553 554## TypeDecorator 555 556type TypeDecorator = \<T\>(type: TypeConstructor\<T\>) => PropertyDecorator; 557 558属性装饰器。 559 560**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。 561 562**系统能力:** SystemCapability.ArkUI.ArkUI.Full 563 564**参数:** 565 566| 参数名 | 类型 | 必填 | 说明 | 567| ------ | ---- | ---- | ------------ | 568| type | [TypeConstructor\<T\>](#typeconstructort) | 是 | 标记类属性的类型。 | 569 570**返回值:** 571 572| 类型 | 说明 | 573| ---- | ------------------------------------------------ | 574| PropertyDecorator | 属性装饰器。 | 575 576**示例:** 577 578```ts 579import { PersistenceV2, Type } from '@kit.ArkUI'; 580 581@ObservedV2 582class SampleChild { 583 @Trace id: number = 0; 584 count: number = 10; 585} 586 587@ObservedV2 588export class Sample { 589 // 对于复杂对象需要@Type修饰,确保序列化成功 590 // TypeDecorator 指的是 @Type 591 @Type(SampleChild) 592 @Trace sampleChild: SampleChild = new SampleChild(); 593} 594 595@Entry 596@ComponentV2 597struct Index { 598 data: Sample = PersistenceV2.connect(Sample, () => new Sample())!; 599 600 build() { 601 Column() { 602 Text(`Index add 1 to data.id: ${this.data.sampleChild.id}`) 603 .fontSize(30) 604 .onClick(() => { 605 this.data.sampleChild.id++; 606 }) 607 } 608 } 609} 610``` 611