鸿蒙数据持久化方案

📅 2025-05-13 · ⏱ 15 分钟 · 数据存储

应用开发中经常需要将数据持久化存储到设备本地。HarmonyOS 提供了多种存储方案，本文介绍最常用的三种：Preferences、分布式数据管理和关系型数据库。

一、Preferences（轻量级键值存储）

适合存储少量配置数据，如用户设置、开关状态等。数据以键值对形式存储在内存中，支持自动持久化。

使用步骤

import { preferences } from "@kit.ArkData"

// 获取 Preferences 实例
async function getPrefs(context: Context) {
  return await preferences.getPreferences(context, "app_settings")
}

// 写入数据
async function saveSetting(context: Context) {
  let prefs = await getPrefs(context)
  await prefs.put("theme", "dark")
  await prefs.put("fontSize", 16)
  await prefs.put("notifications", true)
  await prefs.flush()  // 持久化到磁盘
}

// 读取数据
async function loadSetting(context: Context) {
  let prefs = await getPrefs(context)
  let theme = await prefs.get("theme", "light")  // 第二个参数为默认值
  let fontSize = await prefs.get("fontSize", 14)
  return { theme, fontSize }
}

支持的数据类型

💡 Preferences 数据全部加载到内存中，不适合存储大量数据。单个文件建议不超过 2MB。

二、关系型数据库（RDB）

适合存储结构化数据，如用户信息、订单记录等。支持标准 SQL 语法。

创建数据库和表

import { relationalStore } from "@kit.ArkData"

// 创建 RDB 存储
const STORE_CONFIG = {
  name: "app.db",
  securityLevel: relationalStore.SecurityLevel.S1
}

async function createDB(context: Context) {
  let rdbStore = await relationalStore.getRdbStore(context, STORE_CONFIG)

  // 创建用户表
  await rdbStore.executeSql(`
    CREATE TABLE IF NOT EXISTS users (
      id INTEGER PRIMARY KEY AUTOINCREMENT,
      name TEXT NOT NULL,
      email TEXT UNIQUE,
      age INTEGER DEFAULT 0,
      created_at TEXT DEFAULT (datetime('now'))
    )
  `)

  return rdbStore
}

增删改查操作

// 插入数据
async function insertUser(rdbStore, name, email, age) {
  let bucket = {
    name: name,
    email: email,
    age: age
  }
  let rowId = await rdbStore.insert("users", bucket)
  return rowId
}

// 查询数据
async function getUsers(rdbStore) {
  let predicates = new relationalStore.RdbPredicates("users")
  predicates.greaterThan("age", 18)
  let resultSet = await rdbStore.query(predicates, ["id", "name", "email", "age"])

  let users = []
  while (resultSet.goToNextRow()) {
    users.push({
      id: resultSet.getLong(resultSet.getColumnIndex("id")),
      name: resultSet.getString(resultSet.getColumnIndex("name")),
      email: resultSet.getString(resultSet.getColumnIndex("email")),
      age: resultSet.getLong(resultSet.getColumnIndex("age"))
    })
  }
  resultSet.close()
  return users
}

// 更新数据
async function updateUser(rdbStore, id, newName) {
  let bucket = { name: newName }
  let predicates = new relationalStore.RdbPredicates("users")
  predicates.equalTo("id", id)
  await rdbStore.update(bucket, predicates)
}

// 删除数据
async function deleteUser(rdbStore, id) {
  let predicates = new relationalStore.RdbPredicates("users")
  predicates.equalTo("id", id)
  await rdbStore.delete(predicates)
}

三、选择建议

方案适用场景数据量查询能力
Preferences配置项、开关、缓存小（< 2MB）按 key 读写
RDB结构化业务数据中等完整 SQL

四、最佳实践