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 > keyOrDefaultCreator：指定的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数据页面 93```ts 94// 数据中心 95// Sample.ets 96@ObservedV2 97export class Sample { 98 @Trace p1: number = 0; 99 p2: number = 10; 100} 101``` 102 103页面1 104```ts 105// Page1.ets 106import { AppStorageV2 } from '@kit.ArkUI'; 107import { Sample } from '../Sample'; 108 109@Entry 110@ComponentV2 111struct Page1 { 112 // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联 113 @Local prop: Sample = AppStorageV2.connect(Sample, () => new Sample())!; 114 pageStack: NavPathStack = new NavPathStack(); 115 116 build() { 117 Navigation(this.pageStack) { 118 Column() { 119 Button('Go to page2') 120 .onClick(() => { 121 this.pageStack.pushPathByName('Page2', null); 122 }) 123 124 Button('Page1 connect the key Sample') 125 .onClick(() => { 126 // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联 127 this.prop = AppStorageV2.connect(Sample, 'Sample', () => new Sample())!; 128 }) 129 130 Button('Page1 remove the key Sample') 131 .onClick(() => { 132 // 从AppStorageV2中删除后，prop将不会再与key为Sample的值关联 133 AppStorageV2.remove(Sample); 134 }) 135 136 Text(`Page1 add 1 to prop.p1: ${this.prop.p1}`) 137 .fontSize(30) 138 .onClick(() => { 139 this.prop.p1++; 140 }) 141 142 Text(`Page1 add 1 to prop.p2: ${this.prop.p2}`) 143 .fontSize(30) 144 .onClick(() => { 145 // 页面不刷新，但是p2的值改变了 146 this.prop.p2++; 147 }) 148 149 // 获取当前AppStorageV2里面的所有key 150 Text(`all keys in AppStorage: ${AppStorageV2.keys()}`) 151 .fontSize(30) 152 } 153 } 154 } 155} 156``` 157 158页面2 159```ts 160// Page2.ets 161import { AppStorageV2 } from '@kit.ArkUI'; 162import { Sample } from '../Sample'; 163 164@Builder 165export function Page2Builder() { 166 Page2() 167} 168 169@ComponentV2 170struct Page2 { 171 // 在AppStorageV2中创建一个key为Sample的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联 172 @Local prop: Sample = AppStorageV2.connect(Sample, () => new Sample())!; 173 pathStack: NavPathStack = new NavPathStack(); 174 175 build() { 176 NavDestination() { 177 Column() { 178 Button('Page2 connect the key Sample1') 179 .onClick(() => { 180 // 在AppStorageV2中创建一个key为Sample1的键值对（如果存在，则返回AppStorageV2中的数据），并且和prop关联 181 this.prop = AppStorageV2.connect(Sample, 'Sample1', () => new Sample())!; 182 }) 183 184 Text(`Page2 add 1 to prop.p1: ${this.prop.p1}`) 185 .fontSize(30) 186 .onClick(() => { 187 this.prop.p1++; 188 }) 189 190 Text(`Page2 add 1 to prop.p2: ${this.prop.p2}`) 191 .fontSize(30) 192 .onClick(() => { 193 // 页面不刷新，但是p2的值改变了；只有重新初始化才会改变 194 this.prop.p2++; 195 }) 196 197 // 获取当前AppStorageV2里面的所有key 198 Text(`all keys in AppStorage: ${AppStorageV2.keys()}`) 199 .fontSize(30) 200 } 201 } 202 .onReady((context: NavDestinationContext) => { 203 this.pathStack = context.pathStack; 204 }) 205 } 206} 207``` 208使用Navigation时，需要添加配置系统路由表文件src/main/resources/base/profile/route_map.json，并替换pageSourceFile为Page2页面的路径，并且在module.json5中添加："routerMap": "$profile:route_map"。 209```json 210{ 211 "routerMap": [ 212 { 213 "name": "Page2", 214 "pageSourceFile": "src/main/ets/pages/Page2.ets", 215 "buildFunction": "Page2Builder", 216 "data": { 217 "description" : "AppStorageV2 example" 218 } 219 } 220 ] 221} 222``` 223