鸿蒙Next持久化存储PersistentStorage用法总结

一、概述

PersistentStorage是应用程序中的可选单例对象，用于持久化存储选定的AppStorage属性，确保这些属性在应用程序重新启动时的值与关闭时相同。它将属性保留在设备磁盘上，UI和业务逻辑通过AppStorage访问其属性，AppStorage中的更改会自动同步到PersistentStorage，二者建立双向同步。

二、限制条件

1. 允许的类型和值
   • 简单类型如number、string、boolean、enum等。
   • 可被JSON.stringify()和JSON.parse()重构的对象（成员方法不支持持久化）。
   • API12及以上支持Map、Set、Date类型，以及undefined和null、联合类型。
2. 不允许的类型和值
   • 不支持嵌套对象（对象数组、对象属性为对象等），因框架无法检测其值变化，无法写回PersistentStorage。
3. 性能相关限制
   • 持久化数据相对缓慢，应避免持久化大型数据集和经常变化的变量。建议持久化变量小于2kb，大量数据持久化会影响UI渲染性能，如需存储大量数据，建议使用数据库API。
4. 调用时机限制
   • 持久化操作需在UI实例初始化成功（loadContent传入的回调被调用时）后才可调用，早于该时机调用会导致持久化失败。

三、使用场景

（一）从AppStorage中访问PersistentStorage初始化的属性

1. 初始化PersistentStorage
   • 使用PersistentStorage.persistProp('aProp', 47);初始化属性。
2. 在AppStorage获取对应属性
   • 可以通过AppStorage.get<number>('aProp');获取，或在组件内部使用@StorageLink('aProp') aProp: number = 48;定义双向绑定变量。
   • 新应用安装后首次启动运行时，会依次查询PersistentStorage本地文件和AppStorage中是否存在属性，若不存在则创建并初始化，然后将属性持久化。之后在组件中创建双向绑定变量时会使用AppStorage中的值。
   • 触发点击事件等改变绑定变量时，变化会同步到AppStorage，进而触发PersistentStorage将新值写入磁盘。后续启动应用时，会先从PersistentStorage查询值并写入AppStorage，组件中的绑定变量获取到相应值。

（二）在PersistentStorage之前访问AppStorage中的属性（反例）

• 例如let aProp = AppStorage.setOrCreate('aProp', 47);PersistentStorage.persistProp('aProp', 48);这种调用顺序会导致问题。在非首次运行时，先执行AppStorage.setOrCreate('aProp', 47)会创建属性并写回PersistentStorage，导致之前存储的值丢失，然后PersistentStorage.persistProp('aProp', 48)会使用新创建的值。

（三）在PersistentStorage之后访问AppStorage中的属性

• 开发者可先判断是否需要覆盖上一次保存在PersistentStorage中的值，如PersistentStorage.persistProp('aProp', 48);if (AppStorage.get('aProp') > 50) { AppStorage.setOrCreate('aProp',47); }，根据判断结果决定是否调用AppStorage接口修改值。

（四）支持联合类型

• 例如PersistentStorage.persistProp("P", undefined);初始化属性为undefined，然后在组件中通过@StorageLink("P") p: number | undefined | null = 10;绑定变量，点击按钮改变变量值时，视图会刷新且值被持久化存储。

（五）装饰Date类型变量

• 使用PersistentStorage.persistProp("persistedDate", new Date());初始化Date类型属性，在组件中通过@StorageLink("persistedDate") persistedDate: Date = new Date();绑定变量，点击按钮更新Date值时，视图刷新且值被持久化存储，可通过相关接口获取Date的具体信息（如年月日、时间等）并显示。

（六）装饰Map类型变量

• 如PersistentStorage.persistProp("persistedMapString", new Map<number, string>([]));初始化Map类型属性，组件中通过@StorageLink("persistedMapString") persistedMapString: Map<number, string> = new Map<number, string>([]);绑定变量，点击按钮改变Map值（如添加键值对）时，视图刷新且值被持久化存储，可通过循环遍历显示Map中的元素。

（七）装饰Set类型变量

• 以PersistentStorage.persistProp("persistedSet", new Set<number>([]));初始化Set类型属性，组件中通过@StorageLink("persistedSet") persistedSet: Set<number> = new Set<number>([]);绑定变量，点击按钮改变Set值（如添加元素、清空集合）时，视图刷新且值被持久化存储，可通过循环遍历显示Set中的元素。