HarmonyOS 数据持久化：Preferences 键值对存储

适用版本HarmonyOS 6.1API 12及以上验证环境Pura 90 Pro 模拟器HarmonyOS 6.1.1API 24关键概念ohos.data.preferences、getPreferences、put、get、flush、clear前言ohos.data.preferences是 HarmonyOS 轻量级键值对持久化方案数据以文件形式存储在应用沙箱内重启后依然存在。适合保存用户设置、登录状态、功能开关等少量配置数据。一、核心 APIimport preferences from ohos.data.preferences import common from ohos.app.ability.common // 1. 获取或创建Preferences 实例 const ctx getContext(this) as common.UIAbilityContext const store await preferences.getPreferences(ctx, my_store) // 2. 写入支持 string、number、boolean、string[]、number[] await store.put(app_version, 6.1.0) // string await store.put(launch_count, 42) // number await store.put(dark_mode, true) // boolean await store.put(tags, [ArkTS, HarmonyOS]) // string[] // 3. 持久化到磁盘必须调用否则只在内存中 await store.flush() // 4. 读取第二参数为默认值 const version await store.get(app_version, 未知) as string const count await store.get(launch_count, 0) as number const dark await store.get(dark_mode, false) as boolean // 5. 检查键是否存在 const exists await store.has(app_version) // boolean // 6. 删除某个键 await store.delete(temp_key) await store.flush() // 7. 清空所有数据 await store.clear() await store.flush()二、支持的值类型类型示例stringHarmonyOS 6.1number42、3.14booleantrue、falsestring[][a, b]number[][1, 2, 3]三、完整示例记住用户设置import preferences from ohos.data.preferences import common from ohos.app.ability.common const STORE user_settings // 保存设置 async function saveSettings(ctx: common.UIAbilityContext, settings: UserSettings): Promisevoid { const store await preferences.getPreferences(ctx, STORE) await store.put(theme, settings.theme) await store.put(fontSize, settings.fontSize) await store.put(notifications, settings.notifications) await store.flush() // 写入磁盘 } // 读取设置带默认值 async function loadSettings(ctx: common.UIAbilityContext): PromiseUserSettings { const store await preferences.getPreferences(ctx, STORE) const settings new UserSettings() settings.theme (await store.get(theme, light)) as string settings.fontSize (await store.get(fontSize, 16)) as number settings.notifications (await store.get(notifications, true)) as boolean return settings }四、Preferences vs 其他持久化方案方案适用场景数据量Preferences用户设置、开关、Token少量KB 级RelationalStore结构化数据表格大量MB 级KVStore跨设备同步的 K-V 数据中量文件ohos.file)任意格式图片、JSON 文件任意五、存储位置与隔离Preferences 文件存储在应用沙箱路径/data/app/el2/userId/base/bundleName/files/storeName每个应用独立沙箱其他应用不可访问应用卸载时自动删除store_name不同的 Preferences 互相隔离模拟器运行截图初始状态填写表单写入后读取点击「写入 Preferences」将三个键值持久化再点击「读取所有键值」显示app_versionstring、launch_countnumber、dark_modeboolean三条记录及其类型标签。实测结果键名类型写入值读回值app_versionstring“HarmonyOS 6.1”“HarmonyOS 6.1”launch_countnumber4242dark_modebooleantruetrue重启模拟器后重新读取数据依然存在持久化验证通过。常见问题Qput之后不调用flush()会怎样A数据只在内存中进程终止应用退出/崩溃/系统回收后数据丢失。flush()将内存数据同步写入磁盘文件确保持久化。QPreferences 是线程安全的吗A同一进程内的 Preferences 实例是线程安全的ArkTS 会序列化并发操作。在 TaskPool 中也可以使用但建议在主线程统一管理 Preferences 读写。Q如何监听 Preferences 某个键的变化A使用store.on(change, (key: string) { ... })注册监听器当指定键被修改并 flush后触发回调。适合多页面共用同一个 Preferences 时自动同步状态。上一篇HTTP 网络请求下一篇页面路由Router