1# AppStorageV2: 应用全局UI状态存储
2
3为了增强状态管理框架对应用全局UI状态变量存储的能力，开发者可以使用AppStorageV2存储应用全局UI状态变量数据。
4
5AppStorageV2是提供状态变量在应用级全局共享的能力，开发者可以通过connect绑定同一个key，进行跨ability的数据共享。
6
7在阅读本文当前，建议提前阅读：[\@ComponentV2](./arkts-new-componentV2.md)，[\@ObservedV2和\@Trace](./arkts-new-observedV2-and-trace.md)，配合阅读：[AppStorageV2-API文档](../reference/apis-arkui/js-apis-StateManagement.md#appstoragev2)。
8
9>**说明：**
10>
11>AppStorageV2从API version 12开始支持。
12>
13
14
15## 概述
16
17AppStorageV2是在应用UI启动时会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorageV2将在应用运行过程保留其数据。数据通过唯一的键字符串值访问。
18
19AppStorageV2可以和UI组件同步，且可以在应用业务逻辑中被访问。
20
21AppStorageV2支持应用的[主线程](../application-models/thread-model-stage.md)内多个UIAbility实例间的状态共享。
22
23
24## 使用说明
25
26### connect：创建或获取储存的数据
27
28```JavaScript
29static connect<T extends object>(
30    type: TypeConstructorWithArgs<T>,
31    keyOrDefaultCreator?: string | StorageDefaultCreator<T>,
32    defaultCreator?: StorageDefaultCreator<T>
33): T | undefined;
34```
35
36| connect      | 说明                                                  |
37| ------------ | ----------------------------------------------------- |
38| 参数         | type：指定的类型，若未指定key，则使用type的name作为key；</br > keyOrDefaultCreater：指定的key，或者是默认数据的构造器；</br > defaultCreator：默认数据的构造器。                                          |
39| 返回值       | 创建或获取数据成功时，返回数据；否则返回undefined。 |
40
41>**说明：**
42>
43>1、若未指定key，使用第二个参数作为默认构造器；否则使用第三个参数作为默认构造器（第二个参数非法也使用第三个参数作为默认构造器）；
44>
45>2、确保数据已经存储在AppStorageV2中，可省略默认构造器，获取存储的数据；否则必须指定默认构造器，不指定将导致应用异常；
46>
47>3、同一个key，connect不同类型的数据会导致应用异常，应用需要确保类型匹配；
48>
49>4、key建议使用有意义的值，可由字母、数字、下划线组成，长度不超过255，使用非法字符或空字符的行为是未定义的；
50>
51>5、关联[\@Observed](arkts-observed-and-objectlink.md)对象时，由于该类型的name属性未定义，需要指定key或者自定义name属性。
52
53### remove：删除指定key的储存数据
54
55```JavaScript
56static remove<T>(keyOrType: string | TypeConstructorWithArgs<T>): void;
57```
58
59| remove       | 说明                                                  |
60| ------------ | ----------------------------------------------------- |
61| 参数         | keyOrType：需要删除的key；如果指定的是type类型，删除的key为type的name。                                          |
62| 返回值       | 无。 |
63
64>**说明：**
65>
66>删除AppStorageV2中不存在的key会报警告。
67
68### keys：返回所有AppStorageV2中的key
69
70```JavaScript
71static keys(): Array<string>;
72```
73
74| keys         | 说明                                                  |
75| ------------ | ----------------------------------------------------- |
76| 参数         | 无。                                         |
77| 返回值       | 所有AppStorageV2中的key。 |
78
79
80## 使用限制
81
821、需要配合UI使用（UI线程），不能在其他线程使用，如不支持@Sendable；
83
842、不支持collections.Set、collections.Map等类型；
85
863、不支持非buildin类型，如PixelMap、NativePointer、ArrayList等Native类型。
87
88## 使用场景
89
90### 在两个页面之间存储数据
91
92页面1
93```ts
94import { AppStorageV2 } from '@kit.ArkUI';
95import { Sample } from '../Sample';
96
97@Entry
98@ComponentV2
99struct Page1 {
100  // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联
101  @Local prop: Sample = AppStorageV2.connect(Sample, () => new Sample())!;
102  pageStack: NavPathStack = new NavPathStack();
103
104  build() {
105    Navigation(this.pageStack) {
106      Column() {
107        Button('Go to page2')
108          .onClick(() => {
109            this.pageStack.pushPathByName('Page2', null);
110          })
111
112        Button('Page1 connect the key Sample')
113          .onClick(() => {
114            // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联
115            this.prop = AppStorageV2.connect(Sample, 'Sample', () => new Sample())!;
116          })
117
118        Button('Page1 remove the key Sample')
119          .onClick(() => {
120            // 从AppStorageV2中删除后，prop将不会再与key为Sample的值关联
121            AppStorageV2.remove(Sample);
122          })
123
124        Text(`Page1 add 1 to prop.p1: ${this.prop.p1}`)
125          .fontSize(30)
126          .onClick(() => {
127            this.prop.p1++;
128          })
129
130        Text(`Page1 add 1 to prop.p2: ${this.prop.p2}`)
131          .fontSize(30)
132          .onClick(() => {
133            // 页面不刷新，但是p2的值改变了
134            this.prop.p2++;
135          })
136
137        // 获取当前AppStorageV2里面的所有key
138        Text(`all keys in AppStorage: ${AppStorageV2.keys()}`)
139          .fontSize(30)
140      }
141    }
142  }
143}
144```
145
146页面2
147```ts
148import { AppStorageV2 } from '@kit.ArkUI';
149import { Sample } from '../Sample';
150
151@Builder
152export function Page2Builder() {
153  Page2()
154}
155
156@ComponentV2
157struct Page2 {
158  // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联
159  @Local prop: Sample = AppStorageV2.connect(Sample, () => new Sample())!;
160  pathStack: NavPathStack = new NavPathStack();
161
162  build() {
163    NavDestination() {
164      Column() {
165        Button('Page2 connect the key Sample1')
166          .onClick(() => {
167            // 在AppStorageV2中创建一个key为Sample1的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联
168            this.prop = AppStorageV2.connect(Sample, 'Sample1', () => new Sample())!;
169          })
170
171        Text(`Page2 add 1 to prop.p1: ${this.prop.p1}`)
172          .fontSize(30)
173          .onClick(() => {
174            this.prop.p1++;
175          })
176
177        Text(`Page2 add 1 to prop.p2: ${this.prop.p2}`)
178          .fontSize(30)
179          .onClick(() => {
180            // 页面不刷新，但是p2的值改变了；只有重新初始化才会改变
181            this.prop.p2++;
182          })
183
184        // 获取当前AppStorageV2里面的所有key
185        Text(`all keys in AppStorage: ${AppStorageV2.keys()}`)
186          .fontSize(30)
187      }
188    }
189    .onReady((context: NavDestinationContext) => {
190      this.pathStack = context.pathStack;
191    })
192  }
193}
194```
195使用Navigation时，需要添加配置系统路由表文件src/main/resources/base/profile/route_map.json，并替换pageSourceFile为Page2页面的路径，并且在module.json5中添加："routerMap": "$profile:route_map"。
196```json
197{
198  "routerMap": [
199    {
200      "name": "Page2",
201      "pageSourceFile": "src/main/ets/pages/PersistenceV2-2.ets",
202      "buildFunction": "Page2Builder",
203      "data": {
204        "description" : "PersistenceV2 example"
205      }
206    }
207  ]
208}
209```
210
211数据页面
212```ts
213// 数据中心
214@ObservedV2
215export class Sample {
216  @Trace p1: number = 0;
217  p2: number = 10;
218}
219```
220