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&nbsp;connect\<T extends object\>( </br >
36  &nbsp;&nbsp;&nbsp;&nbsp;type:&nbsp;TypeConstructorWithArgs\<T\>, </br >
37  &nbsp;&nbsp;&nbsp;&nbsp;keyOrDefaultCreator?:&nbsp;string&nbsp;|&nbsp;StorageDefaultCreator\<T\>, </br >
38  &nbsp;&nbsp;&nbsp;&nbsp;defaultCreator?:&nbsp;StorageDefaultCreator\<T\> </br >
39):&nbsp;T&nbsp;|&nbsp;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&nbsp;\|&nbsp;[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&nbsp;remove\<T\>(keyOrType:&nbsp;string&nbsp;|&nbsp;TypeConstructorWithArgs\<T\>):&nbsp;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&nbsp;keys():&nbsp;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&nbsp;save\<T\>(keyOrType:&nbsp;string&nbsp;|&nbsp;TypeConstructorWithArgs\<T\>):&nbsp;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.Setcollection.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