1# PersistentStorage：持久化存储UI状态 2 3 4前两个小节介绍的LocalStorage和AppStorage都是运行时的内存，但是在应用退出再次启动后，依然能保存选定的结果，是应用开发中十分常见的现象，这就需要用到PersistentStorage。 5 6 7PersistentStorage是应用程序中的可选单例对象。此对象的作用是持久化存储选定的AppStorage属性，以确保这些属性在应用程序重新启动时的值与应用程序关闭时的值相同。 8 9 10## 概述 11 12PersistentStorage将选定的AppStorage属性保留在设备磁盘上。应用程序通过API，以决定哪些AppStorage属性应借助PersistentStorage持久化。UI和业务逻辑不直接访问PersistentStorage中的属性，所有属性访问都是对AppStorage的访问，AppStorage中的更改会自动同步到PersistentStorage。 13 14PersistentStorage和AppStorage中的属性建立双向同步。应用开发通常通过AppStorage访问PersistentStorage，另外还有一些接口可以用于管理持久化属性，但是业务逻辑始终是通过AppStorage获取和设置属性的。 15 16## 限制条件 17 18PersistentStorage允许的类型和值有： 19 20- `number, string, boolean, enum` 等简单类型。 21- 可以被`JSON.stringify()`和`JSON.parse()`重构的对象。例如`Date, Map, Set`等内置类型则不支持，以及对象的属性方法不支持持久化。 22 23PersistentStorage不允许的类型和值有： 24 25- 不支持嵌套对象（对象数组，对象的属性是对象等）。因为目前框架无法检测AppStorage中嵌套对象（包括数组）值的变化，所以无法写回到PersistentStorage中。 26- 不支持`undefined` 和 `null` 。 27 28持久化数据是一个相对缓慢的操作，应用程序应避免以下情况： 29 30- 持久化大型数据集。 31 32- 持久化经常变化的变量。 33 34PersistentStorage的持久化变量最好是小于2kb的数据，不要大量的数据持久化，因为PersistentStorage写入磁盘的操作是同步的，大量的数据本地化读写会同步在UI线程中执行，影响UI渲染性能。如果开发者需要存储大量的数据，建议使用数据库api。 35 36PersistentStorage和UIContext相关联，需要在[UIContext](../reference/apis/js-apis-arkui-UIContext.md#uicontext)明确的时候才可以调用，可以通过在[runScopedTask](../reference/apis/js-apis-arkui-UIContext.md#runscopedtask)里明确上下文。如果没有在UIContext明确的地方调用，将导致无法持久化数据。 37 38## 使用场景 39 40 41### 从AppStorage中访问PersistentStorage初始化的属性 42 431. 初始化PersistentStorage： 44 45 ```ts 46 PersistentStorage.persistProp('aProp', 47); 47 ``` 48 492. 在AppStorage获取对应属性： 50 51 ```ts 52 AppStorage.get<number>('aProp'); // returns 47 53 ``` 54 55 或在组件内部定义： 56 57 58 ```ts 59 @StorageLink('aProp') aProp: number = 48; 60 ``` 61 62完整代码如下： 63 64 65```ts 66PersistentStorage.persistProp('aProp', 47); 67 68@Entry 69@Component 70struct Index { 71 @State message: string = 'Hello World' 72 @StorageLink('aProp') aProp: number = 48 73 74 build() { 75 Row() { 76 Column() { 77 Text(this.message) 78 // 应用退出时会保存当前结果。重新启动后，会显示上一次的保存结果 79 Text(`${this.aProp}`) 80 .onClick(() => { 81 this.aProp += 1; 82 }) 83 } 84 } 85 } 86} 87``` 88 89- 新应用安装后首次启动运行： 90 1. 调用persistProp初始化PersistentStorage，首先查询在PersistentStorage本地文件中是否存在“aProp”，查询结果为不存在，因为应用是第一次安装。 91 2. 接着查询属性“aProp”在AppStorage中是否存在，依旧不存在。 92 3. 在AppStorge中创建名为“aProp”的number类型属性，属性初始值是定义的默认值47。 93 4. PersistentStorage将属性“aProp”和值47写入磁盘，AppStorage中“aProp”对应的值和其后续的更改将被持久化。 94 5. 在Index组件中创建状态变量\@StorageLink('aProp') aProp，和AppStorage中“aProp”双向绑定，在创建的过程中会在AppStorage中查找，成功找到“aProp”，所以使用其在AppStorage找到的值47。 95 96 **图1** PersistProp初始化流程 97 98 99 100- 触发点击事件后： 101 1. 状态变量\@StorageLink('aProp') aProp改变，触发Text组件重新刷新。 102 2. \@StorageLink装饰的变量是和AppStorage中建立双向同步的，所以\@StorageLink('aProp') aProp的变化会被同步回AppStorage中。 103 3. AppStorage中“aProp”属性的改变会同步到所有绑定该“aProp”的单向或者双向变量，在本示例中没有其他的绑定“aProp”的变量。 104 4. 因为“aProp”对应的属性已经被持久化，所以在AppStorage中“aProp”的改变会触发PersistentStorage，将新的改变写入本地磁盘。 105 106- 后续启动应用： 107 1. 执行PersistentStorage.persistProp('aProp', 47)，在首先查询在PersistentStorage本地文件查询“aProp”属性，成功查询到。 108 2. 将在PersistentStorage查询到的值写入AppStorage中。 109 3. 在Index组件里，\@StorageLink绑定的“aProp”为PersistentStorage写入AppStorage中的值，即为上一次退出应用存入的值。 110 111 112### 在PersistentStorage之前访问AppStorage中的属性 113 114该示例为反例。在调用PersistentStorage.persistProp或者persistProps之前使用接口访问AppStorage中的属性是错误的，因为这样的调用顺序会丢失上一次应用程序运行中的属性值： 115 116 117```ts 118let aProp = AppStorage.setOrCreate('aProp', 47); 119PersistentStorage.persistProp('aProp', 48); 120``` 121 122应用在非首次运行时，先执行AppStorage.setOrCreate('aProp', 47)：属性“aProp”在AppStorage中创建，其类型为number，其值设置为指定的默认值47。“aProp”是持久化的属性，所以会被写回PersistentStorage磁盘中，PersistentStorage存储的上次退出应用的值丢失。 123 124PersistentStorage.persistProp('aProp', 48)：在PersistentStorage中查找到“aProp”，值为刚刚使用AppStorage接口写入的47。 125 126### 在PersistentStorage之后访问AppStorage中的属性 127 128开发者可以先判断是否需要覆盖上一次保存在PersistentStorage中的值，如果需要覆盖，再调用AppStorage的接口进行修改，如果不需要覆盖，则不调用AppStorage的接口。 129 130```ts 131PersistentStorage.persistProp('aProp', 48); 132if (AppStorage.get('aProp') > 50) { 133 // 如果PersistentStorage存储的值超过50，设置为47 134 AppStorage.setOrCreate('aProp',47); 135} 136``` 137 138示例代码在读取PersistentStorage储存的数据后判断“aProp”的值是否大于50，如果大于50的话使用AppStorage的接口设置为47。 139
