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

适用版本 ：HarmonyOS 6.1（API 12）及以上 验证环境 ：Pura 90 Pro 模拟器（HarmonyOS 6.1.1，API 24） 关键概念 ：@ohos.data.preferences、getPreferences、put、get、flush、clear

前言

@ohos.data.preferences 是 HarmonyOS 轻量级键值对持久化方案，数据以文件形式存储在应用沙箱内，重启后依然存在。适合保存用户设置、登录状态、功能开关等少量配置数据。

一、核心 API

typescript 复制代码

import 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()

二、支持的值类型

类型	示例
`string`	`'HarmonyOS 6.1'`
`number`	`42`、`3.14`
`boolean`	`true`、`false`
`string[]`	`['a', 'b']`
`number[]`	`[1, 2, 3]`

三、完整示例：记住用户设置

typescript 复制代码

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): Promise<void> {
  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): Promise<UserSettings> {
  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_version（string）、launch_count（number）、dark_mode（boolean）三条记录及其类型标签。

实测结果：

键名	类型	写入值	读回值
app_version	string	"HarmonyOS 6.1"	"HarmonyOS 6.1"
launch_count	number	42	42
dark_mode	boolean	true	true

重启模拟器后重新读取，数据依然存在（持久化验证通过）。

常见问题

Q：put 之后不调用 flush() 会怎样？ A：数据只在内存中，进程终止（应用退出/崩溃/系统回收）后数据丢失。flush() 将内存数据同步写入磁盘文件，确保持久化。

Q：Preferences 是线程安全的吗？ A：同一进程内的 Preferences 实例是线程安全的（ArkTS 会序列化并发操作）。在 TaskPool 中也可以使用，但建议在主线程统一管理 Preferences 读写。

Q：如何监听 Preferences 某个键的变化？ A：使用 store.on('change', (key: string) => { ... }) 注册监听器，当指定键被修改（并 flush）后触发回调。适合多页面共用同一个 Preferences 时自动同步状态。

上一篇：HTTP 网络请求 下一篇：页面路由：Router