文章目录一、什么是持久化存储二、V1 持久化方案PersistentStorage2.1 核心概念2.2 完整使用示例2.3 PersistentStorage 的适用场景三、V2 持久化方案PersistenceV23.1 核心概念3.2 基本使用3.3 高级用法集合类型持久化3.4 PersistenceV2 的优势四、preferences4.1 preferences 核心特点4.2 使用示例4.3 preferences 与 PersistenceV2 的对比4.4 使用建议五、PersistenceV2 VS PersistentStorage 选型建议与迁移指南5.1 如何选择5.2 V1→V2 迁移步骤5.3 完整迁移示例六、最佳实践要点七、总结一、什么是持久化存储在鸿蒙HarmonyOS应用开发中持久化存储指的是将 UI 相关的状态数据保存到磁盘使得应用重启后这些数据能够自动恢复。持久化存储与普通文件存储不同它专为状态管理设计与组件生命周期、装饰器深度集成开发者无需手动读写文件即可实现状态保活。持久化方案分为两代V1 版本的PersistentStorageAPI 9 引入和 V2 版本的PersistenceV2API 12 引入后者在性能、容量和开发体验上全面升级。二、V1 持久化方案PersistentStorage2.1 核心概念PersistentStorage是一个应用全局单例负责持久化 UI 状态数据。它通过persistProp方法设置初始值并绑定键名UI 组件通过StorageLink或StorageProp装饰器与该键建立连接。数据容量单 key 不超过2KB。操作方式同步磁盘写入可能在主线程产生卡顿。路径隔离仅当前 module 可见。2.2 完整使用示例// 1. 在应用入口或必要处持久化初始值PersistentStorage.persistProp(userScore,0);EntryComponentstruct ScoreBoard{// StorageLink 双向绑定UI 修改会自动写回磁盘StorageLink(userScore)score:number0;build(){Column({space:16}){Text(当前积分${this.score}).fontSize(24)Button(增加积分).onClick((){this.score10;})Button(重置积分).onClick((){this.score0;})}.padding(20).width(100%).height(100%)}}运行效果运行说明修改积分并重启应用后userScore的值为修改后的值而不是初始值。必须在 UI 实例初始化成功后即 loadContent 回调中调用 这一重要约束。根据官方文档早于该时机调用会导致持久化失败。2.3 PersistentStorage 的适用场景保存少量全局配置项如用户偏好、主题选择。简单游戏积分、上次浏览位置等轻量数据。兼容旧项目API 9–12 范围内。三、V2 持久化方案PersistenceV23.1 核心概念PersistenceV2是专为状态管理 V2 设计的新一代持久化方案它支持通过PersistenceV2.connect(type: TypeConstructorWithArgsT, keyOrDefaultCreator?, defaultCreator?)连接一个持久化键。通过PersistenceV2.globalConnect(key, defaultValue)跨 module 共享应用级。PersistenceV2在 API 12 ~ API 22 版本中存在明确限制不支持直接持久化基本数据类型如 string、number、boolean也不支持容器类型如 Array、Map、Set以及内置构造对象如 Date、Number。从 API 23 开始支持集合类型Array、Map、Set、Date、Sendable对象、循环引用对象以及单个 key 超过 8KB 的大数据量。3.2 基本使用import{PersistenceV2}fromkit.ArkUI;ObservedV2classThemeConfig{TracethemeMode:stringlight;}EntryComponentV2struct SettingsPage{LocalthemeConfig:ThemeConfigPersistenceV2.connect(ThemeConfig,()newThemeConfig())!;build(){Column({space:20}){Text(当前主题${this.themeConfig.themeModelight?浅色模式:深色模式}).fontSize(20).fontColor(Color.Red)Button(切换为深色模式).onClick((){this.themeConfig.themeModedark;})Button(切换为浅色模式).onClick((){this.themeConfig.themeModelight;})}.padding(20).width(100%).height(100%).backgroundColor(this.themeConfig.themeModelight?Color.White:Color.Black)}}运行效果3.3 高级用法集合类型持久化import{PersistenceV2}fromkit.ArkUI;EntryComponentV2struct FavoritesPage{LocalfavoriteIds:number[](PersistenceV2.globalConnect({type:Arraynumber,defaultCreator:()[]})??[]);build(){Column({space:12}){Text(已收藏的文章数${this.favoriteIds.length}).fontSize(20)Button(添加收藏 (ID1001)).width(80%).onClick((){this.favoriteIds[...this.favoriteIds,1001];})Button(清空收藏).width(80%).onClick((){this.favoriteIds[];})}.padding(20).width(100%)}}运行效果上面的代码存在问题虽然点击添加收藏按钮收藏数量会实时变化但是重新启动应用后已收藏的文章数量清零了。这是因为this.favoriteIds [...this.favoriteIds, 1001]会创建一个全新的数组对象切断了与PersistenceV2的连接。PersistenceV2.globalConnect() 返回的对象是框架代理后的可观察对象。当咱们用整体赋值一个新数组时✅ Local 检测到引用变化 → UI 刷新❌ 新数组与 PersistenceV2 失去连接 → 不会触发自动持久化❌ 应用重启后PersistenceV2 读到的仍是旧数据怎么解决这个问题呢咱们可以利用ObservedV2 Trace装饰器让数组作为 class 的 属性被观测而不是直接作为顶层类型持久化。修改后的代码如下import{PersistenceV2}fromkit.ArkUI;// 1. 用 class 包装数组Trace 追踪变化ObservedV2classFavoriteIds{Traceids:number[][];}EntryComponentV2struct FavoritesPage{// 2. globalConnect 连接 class 实例LocalfavoriteData:FavoriteIds(PersistenceV2.globalConnect({type:FavoriteIds,defaultCreator:()newFavoriteIds()})??newFavoriteIds());build(){Column({space:12}){Text(已收藏的文章数${this.favoriteData.ids.length}).fontSize(20)Button(添加收藏 (ID1001)).width(80%).onClick((){// 3. 修改 Trace 属性的值 → 触发自动持久化this.favoriteData.ids[...this.favoriteData.ids,1001];})Button(清空收藏).width(80%).onClick((){this.favoriteData.ids[];})}.padding(20).width(100%)}}修改后的数据流向图应用重启启动 ↓ PersistenceV2.globalConnect({ type: FavoriteIds }) ↓ 从磁盘读取持久化数据 favoriteData 框架代理后的 FavoriteIds 实例 ↓ 用户点击按钮 → this.favoriteData.ids [...newArray] ↓ Trace 检测到 ids 属性变化 ↓ ┌─────────────────────┐ │ ① → UI 自动刷新 ✅ │ │ ② → 自动写入磁盘 ✅ │ └─────────────────────┘3.4 PersistenceV2 的优势丰富的数据类型数组、Map、Set、Date 原生支持无需手动序列化。大数据支持单 key 可存储超过 8KBAPI 23。全局共享通过globalConnect可在不同 HAP/Module 间共享同一持久化数据。自管理序列化状态管理引擎自动完成序列化与反序列化。四、preferences除了PersistentStorage和PersistenceV2鸿蒙还提供了preferences首选项模块用于轻量级键值对数据的持久化存储。它属于kit.ArkData套件适合存储用户配置、设置项等不要求与 UI 状态管理强绑定的数据。4.1 preferences 核心特点轻量级以键值对形式存储适合存储简单的用户配置数据。异步接口所有操作读取、写入、刷新均返回 Promise不会阻塞 UI 线程。手动序列化与状态管理装饰器解耦开发者需自行读取并赋值给状态变量。文件级隔离不同的 preferences 文件通过名称区分可以管理不同类别的配置。4.2 使用示例以下示例演示如何使用preferences实现主题切换功能将用户选择的主题模式持久化到本地并在应用启动时恢复// 导入 preferences 模块用于轻量级键值对数据持久化存储如用户配置import{preferences}fromkit.ArkData;// 导入 AbilityKit 中的 common 模块用于获取 UIAbilityContext以便访问应用上下文import{common}fromkit.AbilityKit;EntryComponentV2struct Index{LocalthemeMode:stringlight;// 获取当前组件的 UIAbility 上下文对象// 通过 getUIContext().getHostContext() 获取宿主 Ability 的上下文// as common.UIAbilityContext 进行类型断言使其具备操作应用数据的能力privatecontextthis.getUIContext().getHostContext()ascommon.UIAbilityContext;asyncaboutToAppear(){// 获取或创建名为 app_settings 的首选项存储实例conststoreawaitpreferences.getPreferences(this.context,app_settings);// 从存储中读取 themeMode 键对应的值若不存在则使用默认值 light// get() 返回 PromiseValueType必须用 await 获取实际值this.themeModeawaitstore.get(themeMode,light)asstring;}// switchTheme 方法切换主题模式并将新值持久化到本地存储// param newMode - 新的主题模式字符串light 或 darkasyncswitchTheme(newMode:string){// 获取首选项存储实例conststoreawaitpreferences.getPreferences(this.context,app_settings);// 将新的主题模式写入存储键为 themeMode值为 newModeawaitstore.put(themeMode,newMode);// 手动刷新flush数据到磁盘确保数据真正持久化保存awaitstore.flush();// 更新组件内部的 themeMode 状态变量触发 UI 刷新this.themeModenewMode;}build(){Column({space:20}){Text(当前主题${this.themeModelight?浅色模式:深色模式}).fontSize(20).fontColor(Color.Red)Button(切换为深色模式).onClick((){this.switchTheme(dark)})Button(切换为浅色模式).onClick((){this.switchTheme(light)})}.padding(20).width(100%).height(100%).backgroundColor(this.themeModelight?Color.White:Color.Black)}}运行效果4.3 preferences 与 PersistenceV2 的对比维度preferencesPersistenceV2设计定位轻量级键值对存储状态管理 V2 的内置持久化引擎与状态管理集成手动读写自动序列化/反序列化与StorageProp集成数据类型基本类型string、number、boolean对象、集合、Sendable、循环引用API 23容量适合少量配置项支持大数据量API 23 单 key 8KB跨 Module需自行管理文件路径内置 module 级 / 应用级 connect4.4 使用建议偏好设置/用户配置优先使用preferences它更轻量不需要引入状态管理 V2 的特性。UI 状态持久化当需要持久化与 UI 绑定的数据如列表项选中状态、表单输入时推荐使用PersistenceV2以简化代码。混合使用两个方案不冲突可以在同一应用中共存——用preferences存配置用PersistenceV2存 UI 状态。五、PersistenceV2 VS PersistentStorage 选型建议与迁移指南5.1 如何选择场景推荐方案理由新项目API 12PersistenceV2性能好、功能全、开发体验佳旧项目API 9–11PersistentStorage兼容已有代码零迁移成本需要跨 Module 共享PersistenceV2 globalConnect路径隔离更灵活存储大数据/集合类型PersistenceV2API 23超 2KB 或数组数据必须用 V25.2 V1→V2 迁移步骤将组件装饰器从Component替换为ComponentV2。将StorageLink/StorageProp替换为 V2 版本注意 API 签名差异。替换PersistentStorage.persistProp()为PersistenceV2.connect()。注意V1 和 V2 的状态管理装饰器不能混用在同一个组件中建议逐个组件迁移。5.3 完整迁移示例// 改造前V1PersistentStorage.persistProp(userName,Guest);EntryComponentstruct Profile{StorageLink(userName)name:stringGuest;// ...}// 改造后V2EntryComponentV2struct Profile{Localname:stringPersistenceV2.connect(userName,Guest);// ...}六、最佳实践要点不要持久化过多数据持久化存储适合 UI 状态不适合业务大文件大文件应使用文件管理 API。避免频繁写入虽然 V2 是异步写入但高频写操作会触发多次磁盘 I/O建议合并写操作。默认值处理connect的第二个参数是默认值仅在磁盘无该 key 时生效如需重置需主动调用PersistenceV2.remove(key)。测试冷启动恢复务必在真机或 DevEco Studio 模拟器上做冷启动测试确认数据恢复逻辑正确。七、总结鸿蒙应用开发中的持久化方案从 V1 的PersistentStorage演进到 V2 的PersistenceV2核心变化在于性能更优、数据类型更丰富、与状态管理引擎集成更紧密。对于新开发的项目应优先选择 V2 方案对于存量 V1 项目可按组件粒度逐步迁移。持久化存储只是鸿蒙状态管理的一部分建议结合State、Prop、Provide/Consume等装饰器综合使用打造流畅且数据不丢失的用户体验。