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### connect<sup>12+</sup> 30 31static connect\<T extends object\>( </br > 32 type: TypeConstructorWithArgs\<T\>, </br > 33 keyOrDefaultCreator?: string | StorageDefaultCreator\<T\>, </br > 34 defaultCreator?: StorageDefaultCreator\<T\> </br > 35): T | undefined; 36 37将键值对数据储存在应用内存中。如果给定的key已经存在于[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)中，返回对应的值；否则，通过获取默认值的构造器构造默认值，并返回。 38 39**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 40 41**系统能力：** SystemCapability.ArkUI.ArkUI.Full 42 43**参数：** 44 45| 参数名 | 类型 | 必填 | 参数描述 | 46| -------- | ------ | ---- | ---------------------- | 47| type | TypeConstructorWithArgs\<T\> | 是 | 指定的类型，若未指定key，则使用type的name作为key。 | 48| keyOrDefaultCreater | string \| StorageDefaultCreator\<T\> | 否 | 指定的key，或者是获取默认值的构造器。 | 49| defaultCreator | StorageDefaultCreator\<T\> | 否 | 获取默认值的构造器。 | 50 51>**说明：** 52> 53>1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器； 54> 55>2、确保数据已经存储在AppStorageV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常； 56> 57>3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配； 58> 59>4、key建议使用有意义的值，长度不超过255，使用非法字符或空字符的行为是未定义的。 60 61**返回值：** 62 63| 类型 | 描述 | 64| -------------------------------------- | ------------------------------------------------------------ | 65| T | 创建或获取AppStorageV2数据成功时，返回数据；否则返回undefined。 | 66 67**示例：** 68 69```ts 70import { AppStorageV2 } from '@kit.ArkUI'; 71 72@ObservedV2 73class SampleClass { 74 @Trace p: number = 0; 75} 76 77// 将key为SampleClass、value为new SampleClass()对象的键值对存储到内存中，并赋值给as1 78const as1: SampleClass | undefined = AppStorageV2.connect(SampleClass, () => new SampleClass()); 79 80// 将key为key_as2、value为new SampleClass()对象的键值对存储到内存中，并赋值给as2 81const as2: SampleClass = AppStorageV2.connect(SampleClass, 'key_as2', () => new SampleClass())!; 82 83// key为SampleClass已经在AppStorageV2中，将key为SampleClass的值返回给as3 84const as3: SampleClass = AppStorageV2.connect(SampleClass) as SampleClass; 85``` 86 87### remove<sup>12+</sup> 88 89static remove\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void; 90 91将指定的键值对数据从[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)里面删除。如果指定的键值不存在于AppStorageV2中，将删除失败。 92 93**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 参数描述 | 100| -------- | ------ | ---- | ---------------------- | 101| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要删除的key；如果指定的是type类型，删除的key为type的name。 | 102 103>**说明：** 104> 105>删除AppStorageV2中不存在的key会报警告。 106 107 108**示例：** 109 110```ts 111// 假设AppStorageV2中存在key为key_as2的键，从AppStorageV2中删除该键值对数据 112AppStorageV2.remove('key_as2'); 113 114// 假设AppStorageV2中存在key为SampleClass的键，从AppStorageV2中删除该键值对数据 115AppStorageV2.remove(SampleClass); 116 117// 假设AppStorageV2中不存在key为key_as1的键，报警告 118AppStorageV2.remove('key_as1'); 119``` 120 121### keys<sup>12+</sup> 122 123static keys(): Array\<string\>; 124 125获取[AppStorageV2](../../quick-start/arkts-new-appstoragev2.md)中的所有key。 126 127**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 128 129**系统能力：** SystemCapability.ArkUI.ArkUI.Full 130 131**参数：** 132 133无。 134 135**返回值：** 136 137| 类型 | 描述 | 138| -------------------------------------- | ------------------------------------------------------------ | 139| Array\<string\> | 所有AppStorageV2中的key。 | 140 141>**说明：** 142> 143>key在Array中的顺序是无序的，与key插入到AppStorageV2中的顺序无关。 144 145**示例：** 146 147```ts 148// 假设AppStorageV2中存在两个key（key_as1、key_as2），返回[key_as1、key_as2]赋值给keys 149const keys: Array<string> = AppStorageV2.keys(); 150``` 151 152 153 154## PersistenceV2 155 156PersistenceV2具体UI使用说明，详见[PersistenceV2(持久化存储UI状态)](../../quick-start/arkts-new-persistencev2.md) 157 158### connect<sup>12+</sup> 159 160static connect\<T extends object\>( </br > 161 type: TypeConstructorWithArgs\<T\>, </br > 162 keyOrDefaultCreator?: string | StorageDefaultCreator\<T\>, </br > 163 defaultCreator?: StorageDefaultCreator\<T\> </br > 164): T | undefined; 165 166将键值对数据储存在应用磁盘中（持久化）。如果给定的key已经存在于[PersistenceV2](../../quick-start/arkts-new-persistencev2.md)中，返回对应的值；否则，通过获取默认值的构造器构造默认值，并返回。如果connect的是[\@ObservedV2](../../quick-start/arkts-new-observedV2-and-trace.md)对象，该对象的[\@Trace](../../quick-start/arkts-new-observedV2-and-trace.md)属性的变化，会触发**整个关联对象的自动持久化**；非\@Trace属性的变化则不会，如有必要，可调用PersistenceV2.save接口手动持久化。 167 168**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.ArkUI.ArkUI.Full 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 参数描述 | 175| -------- | ------ | ---- | ---------------------- | 176| type | TypeConstructorWithArgs\<T\> | 是 | 指定的类型，若未指定key，则使用type的name作为key。 | 177| keyOrDefaultCreater | string \| StorageDefaultCreator\<T\> | 否 | 指定的key，或者是获取默认值的构造器。 | 178| defaultCreator | StorageDefaultCreator\<T\> | 否 | 获取默认值的构造器。 | 179 180>**说明：** 181> 182>1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器（第二个参数非法也使用第三个参数作为默认构造器）； 183> 184>2、确保数据已经存储在PersistenceV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常； 185> 186>3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配； 187> 188>4、key建议使用有意义的值，可由字母、数字、下划线组成，长度不超过255，使用非法字符或空字符的行为是未定义的。 189 190**返回值：** 191 192| 类型 | 描述 | 193| -------------------------------------- | ------------------------------------------------------------ | 194| T | 创建或获取AppStorageV2数据成功时，返回数据；否则返回undefined。 | 195 196**示例：** 197 198```ts 199import { PersistenceV2, Type } from '@kit.ArkUI'; 200 201@ObservedV2 202class SampleClass { 203 @Trace p1: number = 0; 204 p2: number = 1; 205} 206 207@ObservedV2 208class FatherSampleClass { 209 @Trace f: SampleClass = new SampleClass(); 210} 211 212// 将key为SampleClass、value为new SampleClass()对象的键值对持久化，并赋值给as1 213const as1: FatherSampleClass | undefined = PersistenceV2.connect(FatherSampleClass, () => new FatherSampleClass()); 214 215// 将key为key_as2、value为new SampleClass()对象的键值对持久化，并赋值给as2 216const as2: FatherSampleClass = PersistenceV2.connect(FatherSampleClass, 'key_as2', () => new FatherSampleClass())!; 217 218// key为SampleClass已经在PersistenceV2中，将key为SampleClass的值返回给as3 219const as3: FatherSampleClass = PersistenceV2.connect(FatherSampleClass) as FatherSampleClass; 220 221@Entry 222@Component 223struct SampleComp { 224 v: FatherSampleClass = as2; 225 226 build() { 227 Column() { 228 Text(`${this.v.f.p1}`) 229 .onClick(() => { 230 // 自动持久化 231 this.v.f.p1++; 232 }) 233 Text(`${this.v.f.p2}`) 234 .onClick(() => { 235 // 不能自动持久化，需要调用PersistenceV2.save 236 this.v.f.p2++; 237 }) 238 } 239 } 240} 241``` 242 243### remove<sup>12+</sup> 244 245static remove\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void; 246 247将指定的键值对数据从[PersistenceV2](../../quick-start/arkts-new-persistencev2.md)里面删除。如果指定的键值不存在于PersistenceV2中，将删除失败。 248 249**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 250 251**系统能力：** SystemCapability.ArkUI.ArkUI.Full 252 253**参数：** 254 255| 参数名 | 类型 | 必填 | 参数描述 | 256| -------- | ------ | ---- | ---------------------- | 257| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要删除的key；如果指定的是type类型，删除的key为type的name。 | 258 259>**说明：** 260> 261>删除PersistenceV2中不存在的key会报警告。 262 263 264**示例：** 265 266```ts 267// 假设PersistenceV2中存在key为key_as2的键，从PersistenceV2中删除该键值对数据 268PersistenceV2.remove('key_as2'); 269 270// 假设PersistenceV2中存在key为SampleClass的键，从PersistenceV2中删除该键值对数据 271PersistenceV2.remove(SampleClass); 272 273// 假设PersistenceV2中不存在key为key_as1的键，报警告 274PersistenceV2.remove('key_as1'); 275``` 276 277### keys<sup>12+</sup> 278 279static keys(): Array\<string\>; 280 281获取[PersistenceV2](../../quick-start/arkts-new-persistencev2.md)中的所有key。 282 283**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 284 285**系统能力：** SystemCapability.ArkUI.ArkUI.Full 286 287**参数：** 288 289无。 290 291**返回值：** 292 293| 类型 | 描述 | 294| -------------------------------------- | ------------------------------------------------------------ | 295| Array\<string\> | 所有PersistenceV2中的key。 | 296 297>**说明：** 298> 299>key在Array中的顺序是无序的，与key插入到PersistenceV2中的顺序无关。 300 301**示例：** 302 303```ts 304// 假设PersistenceV2中存在两个key（key_as1、key_as2），返回[key_as1、key_as2]赋值给keys 305const keys: Array<string> = PersistenceV2.keys(); 306``` 307 308### save<sup>12+</sup> 309 310static save\<T\>(keyOrType: string | TypeConstructorWithArgs\<T\>): void; 311 312将指定的键值对数据持久化一次。 313 314**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 315 316**系统能力：** SystemCapability.ArkUI.ArkUI.Full 317 318**参数：** 319 320| 参数名 | 类型 | 必填 | 参数描述 | 321| -------- | ------ | ---- | ---------------------- | 322| keyOrType | string \| TypeConstructorWithArgs\<T\> | 是 | 需要持久化的key；如果指定的是type类型，持久化的key为type的name。 | 323 324>**说明：** 325> 326>由于非[\@Trace](../../quick-start/arkts-new-observedV2-and-trace.md)的数据改变不会触发[PersistenceV2](../../quick-start/arkts-new-persistencev2.md)的自动持久化，如有必要，可调用该接口持久化对应key的数据； 327> 328>手动持久化当前内存中不处于connect状态的key是无意义的。 329 330 331**示例：** 332 333```ts 334// 假设PersistenceV2中存在key为key_as2的键，持久化该键值对数据 335PersistenceV2.save('key_as2'); 336 337// 假设PersistenceV2中存在key为SampleClass的键，持久化该键值对数据 338PersistenceV2.remove(SampleClass); 339 340// 假设PersistenceV2中不存在key为key_as1的键，无意义的操作 341PersistenceV2.remove('key_as1'); 342``` 343 344## UIUtils 345 346UIUtils提供一些方法，用于处理状态管理相关的数据转换。 347 348### getTarget<sup>12+</sup> 349 350static getTarget\<T extends object\>(source: T): T; 351 352从状态管理框架包裹的代理对象中获取原始对象。详见[getTarget接口：获取状态管理框架代理前的原始对象](../../quick-start/arkts-new-getTarget.md)。 353 354**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 355 356**系统能力：** SystemCapability.ArkUI.ArkUI.Full 357 358**参数：** 359 360| 参数名 | 类型 | 必填 | 参数描述 | 361| ------ | ---- | ---- | ------------ | 362| source | T | 是 | 数据源对象。 | 363 364**返回值：** 365 366| 类型 | 描述 | 367| ---- | ------------------------------------------------ | 368| T | 数据源对象去除状态管理框架所加代理后的原始对象。 | 369 370**示例：** 371 372```ts 373import { UIUtils } from '@kit.ArkUI'; 374class NonObservedClass { 375 name: string = "Tom"; 376} 377let nonObservedClass: NonObservedClass = new NonObservedClass(); 378@Entry 379@Component 380struct Index { 381 @State someClass: NonObservedClass = nonObservedClass; 382 build() { 383 Column() { 384 Text(`this.someClass === nonObservedClass: ${this.someClass === nonObservedClass}`) // false 385 Text(`UIUtils.getTarget(this.someClass) === nonObservedClass: ${UIUtils.getTarget(this.someClass) === 386 nonObservedClass}`) // true 387 } 388 } 389} 390``` 391### makeObserved<sup>12+</sup> 392 393static makeObserved\<T extends object\>(source: T): T; 394 395将普通不可观察数据变为可观察数据。详见[makeObserved接口：将非观察数据变为可观察数据](../../quick-start/arkts-new-makeObserved.md)。 396 397**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 398 399**系统能力：** SystemCapability.ArkUI.ArkUI.Full 400 401**参数：** 402 403| 参数名 | 类型 | 必填 | 参数描述 | 404| ------ | ---- | ---- | ------------ | 405| 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)。 | 406 407**返回值：** 408 409| 类型 | 描述 | 410| ---- | ------------------------------------------------ | 411| T | 可观察的数据。 | 412 413**示例：** 414 415```ts 416import { UIUtils } from '@kit.ArkUI'; 417class NonObservedClass { 418 name: string = 'Tom'; 419} 420 421@Entry 422@ComponentV2 423struct Index { 424 observedClass: NonObservedClass = UIUtils.makeObserved(new NonObservedClass()); 425 nonObservedClass: NonObservedClass = new NonObservedClass(); 426 build() { 427 Column() { 428 Text(`observedClass: ${this.observedClass.name}`) 429 .onClick(() => { 430 this.observedClass.name = 'Jane'; // 刷新 431 }) 432 Text(`observedClass: ${this.nonObservedClass.name}`) 433 .onClick(() => { 434 this.nonObservedClass.name = 'Jane'; // 不刷新 435 }) 436 } 437 } 438} 439```