鸿蒙应用开发——AppStorageV2和PersistenceV2的使用

【高心星出品】

AppStorageV2和PersistenceV2的使用

概念

在HarmonyOS鸿蒙开发中，AppStorageV2和PersistenceV2是状态管理V2版本的核心工具，用于实现应用全局状态管理和持久化存储。以下是两者的关键特性和使用指南：

AppStorageV2常用方法

AppStorageV2是在应用UI启动时会被创建的单例。它的目的是为了提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。AppStorageV2将在应用运行过程保留其数据。数据通过唯一的键字符串值访问。需要注意的是，AppStorage与AppStorageV2之间的数据互不共享。

AppStorageV2可以修改connect的返回值，实现与UI组件的同步。

AppStorageV2只能保存class类型的数据。

AppStorageV2支持应用的主线程内多个UIAbility实例间的状态共享。

connect：创建或获取存储的数据。

remove：删除指定key的存储数据。

keys：返回所有AppStorageV2中的key。

PersistenceV2常用方法

PersistenceV2是继承自AppStorageV2，在应用UI启动时会被创建的单例。它的目的是提供应用状态数据的中心存储，这些状态数据在应用级别都是可访问的。数据通过唯一的键值字符串访问。不同于AppStorageV2，PersistenceV2还将最新数据存储在设备磁盘上（持久化）。这意味着，应用退出再次启动后，依然能保存选定的结果。

对于与PersistenceV2关联的@ObservedV2对象，该对象的@Trace属性的变化，会触发整个关联对象的自动持久化；非@Trace属性的变化则不会，如有必要，可调用PersistenceV2 API手动持久化。请注意：被PersistenceV2持久化的类属性必须要有初值，否则不支持持久化。

PersistenceV2可以和UI组件同步，且可以在应用业务逻辑中被访问。

PersistenceV2支持应用的主线程内多个UIAbility实例间的状态共享。

connect：创建或获取存储的数据。

globalConnect：创建或获取存储的数据。

remove：删除指定key的存储数据。删除PersistenceV2中不存在的key会报警告。

keys：返回所有PersistenceV2中的key。包括module级别存储路径和应用级别存储路径中的所有key。

save：手动持久化数据。

notifyOnError：响应序列化或反序列化失败的回调。将数据存入磁盘时，需要对数据进行序列化；当某个key序列化失败时，错误是不可预知的；可调用该接口捕获异常。

在HarmonyOS鸿蒙开发中，PersistenceV2的connect和globalConnect接口均用于持久化数据的管理，但两者在存储路径和应用场景上有显著差异。以下是核心区别和使用建议：

案例

appstoragev2数据存储案例：

包括获取数据，同步更新数据，遍历数据，移除数据等。

import { AppStorageV2 } from '@kit.ArkUI'; // appstorage保存的数据必须是对象 // 后面使用的过程中 每个属性一般都有默认值 @ObservedV2 class Userinfo{ @Trace name:string='gxx' age:number=30 } @Entry @ComponentV2 struct Appstoragepage { // 获取key为ui 类型为Userinfo的数据，如果appstorage中不存在则使用默认构造方法初始化的值 @Local user:Userinfo=AppStorageV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())! // 获取key为 Userinfo的数据 如果appstorage中不存在则使用默认构造方法初始化的值 // @Local user:Userinfo=AppStorageV2.connect<Userinfo>(Userinfo,()=>{return new Userinfo()})! // 获取key为Userinfo的数据 保证Appstorage中一定有该数据 否则出问题 // @Local user:Userinfo=AppStorageV2.connect<Userinfo>(Userinfo)! @Local keys:string='' @Local datas:string='' build() { Column({space:20}){ Button('保存的数据为： '+`name: ${this.user.name}`) .width('60%') .onClick(()=>{ // 数据更新之后 name会刷新ui 而age不会刷新，但是都会同步到appstorage中 this.user.name='ggl' // 重新获取一下appstorage中存储的数据 this.datas=JSON.stringify(AppStorageV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())!) }) Button('保存的数据为： '+`age: ${this.user.age}`) .width('60%') .onClick(()=>{ // 数据更新之后 name会刷新ui 而age不会刷新，但是都会同步到appstorage中 this.user.age+=1 // 重新获取一下appstorage中存储的数据 this.datas=JSON.stringify(AppStorageV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())!) }) Text('当前的数据'+this.datas) Button('所有的key') .width('60%') .onClick(()=>{ // 拿到所有的key this.keys= AppStorageV2.keys().join(' ') }) Text(this.keys) Button('移除某个数据') .width('60%') .onClick(()=>{ // appstorage 移除key为ui的数据 AppStorageV2.remove('ui') }) } .height('100%') .width('100%') } }

PersistenceV2数据持久化案例：

包括数据模块级别的持久化保存，更新和移除功能。

import { PersistenceV2 } from '@kit.ArkUI'; // persidencev2保存的数据必须是对象 // 后面使用的过程中 每个属性一般都有默认值 @ObservedV2 class Userinfo{ // name属性由@Trace装饰，name更新会引起自动持久化 @Trace name:string='gxx' // age 属性不会引起自动持久化，需要手动持久化 age:number=30 } @Entry @ComponentV2 struct Persistencev2 { // 获取key为ui 类型为Userinfo的数据，如果persistencev2中不存在则使用默认构造方法初始化的值 @Local user:Userinfo=PersistenceV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())! // 获取key为 Userinfo的数据 如果persistencev2中不存在则使用默认构造方法初始化的值 // @Local user:Userinfo=PersistenceV2.connect<Userinfo>(Userinfo,()=>{return new Userinfo()})! // 获取key为Userinfo的数据 保证PersistenceV2中一定有该数据 否则出问题 // @Local user:Userinfo=PersistenceV2.connect<Userinfo>(Userinfo)! @Local keys:string='' @Local datas:string='' build() { Column({space:20}){ Button('保存的数据为： '+`name: ${this.user.name}`) .width('60%') .onClick(()=>{ // 数据更新之后 name会刷新ui 而age不会刷新，name会同步到PersistenceV2中而age不会 this.user.name='ggl' // 重新获取persidence中的数据 this.datas=JSON.stringify(PersistenceV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())!) }) Button('保存的数据为： '+`age: ${this.user.age}`) .width('60%') .onClick(()=>{ // 数据更新之后 name会刷新ui 而age不会刷新，name会同步到PersistenceV2中而age不会 this.user.age+=1 // 手动保存数据 PersistenceV2.save('ui') // 重新获取persidence中的数据 this.datas=JSON.stringify(PersistenceV2.connect<Userinfo>(Userinfo,'ui',()=>new Userinfo())!) }) Text('当前数据为： '+this.datas) Button('所有的key') .width('60%') .onClick(()=>{ // 拿到所有的key this.keys= PersistenceV2.keys().join(' ') }) Text(this.keys) Button('移除某个数据') .width('60%') .onClick(()=>{ // PersistenceV2 移除key为ui的数据 try { PersistenceV2.remove('ui') } catch (err) { console.error('Remove failed:', err.code, err.message) } }) } .height('100%') .width('100%') } }