当前位置：首页 > news >正文

HarmonyOS | 状态管理(八) | PersistentStorage(持久化存储UI状态)

news 2026/1/25 14:37:02

系列文章目录

文章目录

系列文章目录
前言
一、PersistentStorage的作用是什么？
二、PersistentStorage的特性
三、限制条件
四、使用场景
- 1.从AppStorage中访问PersistentStorage初始化的属性
- 2.在PersistentStorage之前访问AppStorage中的属性
- 3.在PersistentStorage之后访问AppStorage中的属性
总结

前言

上一篇我们讲到了应用级UI状态存储(AppStorage),本篇我们来讲下持久化存储UI状态(PersistentStorage)

一、PersistentStorage的作用是什么？

PersistentStorage的作用是：应用退出再次启动后，依然能保存选定的结果。

二、PersistentStorage的特性

PersistentStorage将选定的AppStorage属性保留在设备磁盘上。
应用程序通过API，以决定哪些AppStorage属性应借助PersistentStorage持久化。
UI和业务逻辑不直接访问PersistentStorage中的属性，所有属性访问都是对AppStorage的访问，AppStorage中的更改会自动同步到PersistentStorage。
PersistentStorage和AppStorage中的属性建立双向同步。应用开发通常通过AppStorage访问PersistentStorage。

三、限制条件

PersistentStorage允许的类型和值有：

number, string, boolean, enum 等简单类型。
可以被JSON.stringify()和JSON.parse()重构的对象。例如Date, Map, Set等内置类型则不支持，以及对象的属性方法不支持持久化。

PersistentStorage不允许的类型和值有：

不支持嵌套对象（对象数组，对象的属性是对象等）。因为目前框架无法检测AppStorage中嵌套对象（包括数组）值的变化，所以无法写回到PersistentStorage中。
不支持undefined 和 null 。

持久化数据是一个相对缓慢的操作，应用程序应避免以下情况：

持久化大型数据集。
持久化经常变化的变量。

PersistentStorage的持久化变量最好是小于2kb的数据，不要大量的数据持久化，因为PersistentStorage写入磁盘的操作是同步的，大量的数据本地化读写会同步在UI线程中执行，影响UI渲染性能。如果开发者需要存储大量的数据，建议使用数据库api。

PersistentStorage只能在UI页面内使用，否则将无法持久化数据。

四、使用场景

1.从AppStorage中访问PersistentStorage初始化的属性

PersistentStorage.PersistProp('aProp', 47);@Entry
@Component
struct PersistentStoragePage {@StorageLink('aProp') aProp: number = 48build() {Row() {Column() {// 应用退出时会保存当前结果。重新启动后，会显示上一次的保存结果Text(`${this.aProp}`).onClick(() => {this.aProp += 1;})}}}
}

2.在PersistentStorage之前访问AppStorage中的属性

在调用PersistentStorage.PersistProp或者PersistProps之前使用接口访问AppStorage中的属性是错误的，因为这样的调用顺序会丢失上一次应用程序运行中的属性值。

let aProp = AppStorage.SetOrCreate('aProp', 47);
PersistentStorage.PersistProp('aProp', 48);

3.在PersistentStorage之后访问AppStorage中的属性

开发者可以先判断是否需要覆盖上一次保存在PersistentStorage中的值，如果需要覆盖，再调用AppStorage的接口进行修改，如果不需要覆盖，则不调用AppStorage的接口。

PersistentStorage.PersistProp('aProp', 48);
if (AppStorage.Get('aProp') > 50) {// 如果PersistentStorage存储的值超过50，设置为47AppStorage.SetOrCreate('aProp',47);
}

总结

PersistentStorage的作用是：应用退出再次启动后，依然能保存选定的结果。