1# AppStorage：应用全局的UI状态存储 2 3 4AppStorage是应用全局的UI状态存储，是和应用的进程绑定的，由UI框架在应用程序启动时创建，为应用程序UI状态属性提供中央存储。 5 6 7和LocalStorage不同的是，LocalStorage是页面级的，通常应用于页面内的数据共享。而对于AppStorage，是应用级的全局状态共享。AppStorage还相当于整个应用的“中枢”，[持久化数据PersistentStorage](arkts-persiststorage.md)和[环境变量Environment](arkts-environment.md)都是通过和AppStorage中转，才可以和UI回交互。 8 9 10本文仅介绍AppStorage使用场景和相关的装饰器：\@StorageProp和\@StorageLink。 11 12 13## 概述 14 15AppStorage是LocalStorage是在应用启动的时候会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorage将在应用运行过程保留其属性。属性通过唯一的键字符串值访问。 16 17AppStorage可以和UI组件同步，且可以在应用业务逻辑中被访问。 18 19AppStorage中的属性可以被双向同步，数据可以是存在于本地或远程设备上，并具有不同的功能，比如数据持久化（详见[PersistentStorage](arkts-persiststorage.md)）。这些数据是通过业务逻辑中实现，与UI解耦，如果希望这些数据在UI中使用，需要用到[@StorageProp](#storageprop)和[@StorageLink](#storagelink)。 20 21 22## \@StorageProp 23 24在上文中已经提到，如果要建立AppStorage和自定义组件的联系，需要使用\@StorageProp和\@StorageLink装饰器。使用\@StorageProp(key)/\@StorageLink(key)装饰组件内的变量，key标识了AppStorage的属性。 25 26当自定义组件初始化的时候，\@StorageProp(key)/\@StorageLink(key)装饰的变量会通过给定的key，绑定在AppStorage对应是属性，完成初始化。本地初始化是必要的，因为无法保证AppStorage一定存在给定的key，这取决于应用逻辑，是否在组件初始化之前在AppStorage实例中存入对应的属性。 27 28 29\@StorageProp(key)是和AppStorage中key对应的属性建立单向数据同步，我们允许本地改变的发生，但是对于\@StorageProp，本地的修改永远不会同步回AppStorage中，相反，如果AppStorage给定key的属性发生改变，改变会被同步给\@StorageProp，并覆盖掉本地的修改。 30 31 32### 装饰器使用规则说明 33 34| \@StorageProp变量装饰器 | 说明 | 35| ------------------ | ---------------------------------------- | 36| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 | 37| 允许装饰的变量类型 | Object class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和LocalStorage中对应属性相同。不支持any，不允许使用undefined和null。 | 38| 同步类型 | 单向同步：从AppStorage的对应属性到组件的状态变量。<br/>组件本地的修改是允许的，但是AppStorage中给定的属性一旦发生变化，将覆盖本地的修改。 | 39| 被装饰变量的初始值 | 必须指定，如果AppStorage实例中不存在属性，则作为初始化默认值，并存入AppStorage中。 | 40 41 42### 变量的传递/访问规则说明 43 44| 传递/访问 | 说明 | 45| ---------- | ---------------------------------------- | 46| 从父节点初始化和更新 | 禁止，\@StorageProp不支持从父节点初始化，只能AppStorage中key对应的属性初始化，如果没有对应key的话，将使用本地默认值初始化 | 47| 初始化子节点 | 支持，可用于初始化\@State、\@Link、\@Prop、\@Provide。 | 48| 是否支持组件外访问 | 否。 | 49 50 51 **图1** \@StorageProp初始化规则图示 52 53 54 55 56 57### 观察变化和行为表现 58 59**观察变化** 60 61 62- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。 63 64- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。 65 66- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。 67 68 69**框架行为** 70 71 72- 当\@StorageProp(key)装饰的数值改变被观察到时，修改不会被同步回AppStorage对应属性键值key的属性中。 73 74- 当前\@StorageProp(key)单向绑定的数据会被修改，即仅限于当前组件的私有成员变量改变，其他的绑定该key的数据不会同步改变。 75 76- 当\@StorageProp(key)装饰的数据本身是状态变量，它的改变虽然不会同步回AppStorage中，但是会引起所属的自定义组件的重新渲染。 77 78- 当AppStorage中key对应的属性发生改变时，会同步给所有\@StorageProp(key)装饰的数据，\@StorageProp(key)本地的修改将被覆盖。 79 80 81## \@StorageLink 82 83\@StorageLink(key)是和AppStorage中key对应的属性建立双向数据同步： 84 851. 本地修改发生，该修改会被回AppStorage中； 86 872. AppStorage中的修改发生后，该修改会被同步到所有绑定AppStorage对应key的属性上，包括单向（\@StorageProp和通过Prop创建的单向绑定变量）、双向（\@StorageLink和通过Link创建的双向绑定变量）变量和其他实例（比如PersistentStorage）。 88 89 90### 装饰器使用规则说明 91 92| \@StorageLink变量装饰器 | 说明 | 93| ------------------ | ---------------------------------------- | 94| 装饰器参数 | key：常量字符串，必填（字符串需要有引号）。 | 95| 允许装饰的变量类型 | Object、class、string、number、boolean、enum类型，以及这些类型的数组。嵌套类型的场景请参考[观察变化和行为表现](#观察变化和行为表现)。<br/>类型必须被指定，且必须和AppStorage中对应属性相同。不支持any，不允许使用undefined和null。 | 96| 同步类型 | 双向同步：从AppStorage的对应属性到自定义组件，从自定义组件到AppStorage对应属性。 | 97| 被装饰变量的初始值 | 必须指定，如果AppStorage实例中不存在属性，则作为初始化默认值，并存入AppStorage中。 | 98 99 100### 变量的传递/访问规则说明 101 102| 传递/访问 | 说明 | 103| ---------- | ---------------------------------------- | 104| 从父节点初始化和更新 | 禁止。 | 105| 初始化子节点 | 支持，可用于初始化常规变量、\@State、\@Link、\@Prop、\@Provide。 | 106| 是否支持组件外访问 | 否。 | 107 108 109 **图2** \@StorageLink初始化规则图示 110 111 112 113 114 115### 观察变化和行为表现 116 117**观察变化** 118 119 120- 当装饰的数据类型为boolean、string、number类型时，可以观察到数值的变化。 121 122- 当装饰的数据类型为class或者Object时，可以观察到赋值和属性赋值的变化，即Object.keys(observedObject)返回的所有属性。 123 124- 当装饰的对象是array时，可以观察到数组添加、删除、更新数组单元的变化。 125 126 127**框架行为** 128 129 1301. 当\@StorageLink(key)装饰的数值改变被观察到时，修改将被同步回AppStorage对应属性键值key的属性中。 131 1322. AppStorage中属性键值key对应的数据一旦改变，属性键值key绑定的所有的数据（包括双向\@StorageLink和单向\@StorageProp）都将同步修改； 133 1343. 当\@StorageLink(key)装饰的数据本身是状态变量，它的改变不仅仅会同步回AppStorage中，还会引起所属的自定义组件的重新渲染。 135 136 137## 使用场景 138 139 140### 从应用逻辑使用AppStorage和LocalStorage 141 142AppStorage是单例，它的所有API都是静态的，使用方法类似于中LocalStorage对应的非静态方法。 143 144 145```ts 146AppStorage.SetOrCreate('PropA', 47); 147 148let storage: LocalStorage = new LocalStorage({ 'PropA': 17 }); 149let propA: number = AppStorage.Get('PropA') // propA in AppStorage == 47, propA in LocalStorage == 17 150var link1: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link1.get() == 47 151var link2: SubscribedAbstractProperty<number> = AppStorage.Link('PropA'); // link2.get() == 47 152var prop: SubscribedAbstractProperty<number> = AppStorage.Prop('PropA'); // prop.get() = 47 153 154link1.set(48); // two-way sync: link1.get() == link2.get() == prop.get() == 48 155prop.set(1); // one-way sync: prop.get()=1; but link1.get() == link2.get() == 48 156link1.set(49); // two-way sync: link1.get() == link2.get() == prop.get() == 49 157 158storage.get('PropA') // == 17 159storage.set('PropA', 101); 160storage.get('PropA') // == 101 161 162AppStorage.Get('PropA') // == 49 163link1.get() // == 49 164link2.get() // == 49 165prop.get() // == 49 166``` 167 168 169### 从UI内部使用AppStorage和LocalStorage 170 171\@StorageLink变量装饰器与AppStorage配合使用，正如\@LocalStorageLink与LocalStorage配合使用一样。此装饰器使用AppStorage中的属性创建双向数据同步。 172 173 174```ts 175AppStorage.SetOrCreate('PropA', 47); 176let storage = new LocalStorage({ 'PropA': 48 }); 177 178@Entry(storage) 179@Component 180struct CompA { 181 @StorageLink('PropA') storLink: number = 1; 182 @LocalStorageLink('PropA') localStorLink: number = 1; 183 184 build() { 185 Column({ space: 20 }) { 186 Text(`From AppStorage ${this.storLink}`) 187 .onClick(() => this.storLink += 1) 188 189 Text(`From LocalStorage ${this.localStorLink}`) 190 .onClick(() => this.localStorLink += 1) 191 } 192 } 193} 194``` 195 196 197## 限制条件 198 199AppStorage与[PersistentStorage](arkts-persiststorage.md)以及[Environment](arkts-environment.md)配合使用时，需要注意以下几点： 200 201- 在AppStorage中创建属性后，调用PersistentStorage.PersistProp()接口时，会使用在AppStorage中已经存在的值，并覆盖PersistentStorage中的同名属性，所以建议要使用相反的调用顺序，反例可见[在PersistentStorage之前访问AppStorage中的属性](arkts-persiststorage.md#在persistentstorage之前访问appstorage中的属性)； 202 203- 如果在AppStorage中已经创建属性后，再调用Environment.EnvProp()创建同名的属性，会调用失败。因为AppStorage已经有同名属性，Environment环境变量不会再写入AppStorage中，所以建议AppStorage中属性不要使用Environment预置环境变量名。 204
