鸿蒙Next键值型数据库如何使用

最近在学习鸿蒙Next的键值型数据库，但遇到了一些问题：

  1. 如何初始化键值型数据库？是否需要先创建表结构？
  2. 键值对的数据类型支持哪些？能存储复杂对象吗？
  3. 增删改查操作的具体API该怎么调用？
  4. 数据库文件默认存储在什么路径？能自定义存储位置吗？
  5. 有没有事务处理机制？如何保证数据操作的原子性？
  6. 性能方面有什么需要注意的优化点？ 希望有经验的朋友能分享下具体的使用方法和最佳实践，谢谢！
2 回复

鸿蒙Next键值型数据库？简单说就是“存键值，像存快递”：

  1. 用getKVStore打开“快递柜”；
  2. putString存包裹（键是取件码，值是包裹）；
  3. getString凭码取件；
  4. 不用时closeKVStore关柜门。

记住：别把取件码弄丢，否则包裹永远在柜子里吃灰！🚪📦

更多关于鸿蒙Next键值型数据库如何使用的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


鸿蒙Next（HarmonyOS NEXT）的键值型数据库基于非关系型数据模型，通过键（Key）来高效存取值（Value）。以下是核心使用方法：

1. 环境配置

在 module.json5 配置文件中声明数据库权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC"
      }
    ]
  }
}

2. 创建数据库

通过 KVManager 和 KVStore 管理数据库：

import { distributedKVStore } from '@kit.ArkData';

// 获取 KVManager 实例
const kvManager: distributedKVStore.KVManager = ...;

// 配置数据库选项
const options: distributedKVStore.Options = {
  createIfMissing: true,  // 不存在时自动创建
  encrypt: false,         // 是否加密
  backup: false,          // 是否备份
  autoSync: true,         // 是否自动同步（分布式场景）
  kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION
};

// 创建并打开数据库
let kvStore: distributedKVStore.SingleKVStore;
kvManager.getKVStore<distributedKVStore.SingleKVStore>('myStoreId', options, (err, store) => {
  if (err) {
    console.error(`Failed to get KVStore. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  kvStore = store;
  console.info('Succeeded in getting KVStore');
});

3. 基础操作

写入数据

// 存储字符串
kvStore.put('key1', 'value1', (err) => {
  if (err) {
    console.error(`Failed to put data. Code: ${err.code}`);
    return;
  }
  console.info('Succeeded in putting data');
});

// 存储数字
kvStore.put('key2', 123);

// 存储对象（自动序列化）
kvStore.put('key3', { name: 'HarmonyOS', version: 4.0 });

读取数据

kvStore.get('key1', (err, data) => {
  if (err) {
    console.error(`Failed to get data. Code: ${err.code}`);
    return;
  }
  console.info(`Succeeded in getting data: ${data}`);
});

删除数据

kvStore.delete('key1', (err) => {
  if (err) {
    console.error(`Failed to delete data. Code: ${err.code}`);
    return;
  }
  console.info('Succeeded in deleting data');
});

4. 订阅数据变更

// 监听指定键的变化
kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
  console.info(`Data changed: ${data.key}, ${data.value}`);
});

// 取消订阅
kvStore.off('dataChange');

5. 关闭数据库

kvStore.close((err) => {
  if (err) {
    console.error(`Failed to close KVStore. Code: ${err.code}`);
    return;
  }
  console.info('Succeeded in closing KVStore');
});

注意事项

  • 数据类型：键必须为字符串，值支持字符串、数字、布尔值及可序列化对象。
  • 错误处理：所有操作需处理回调错误（如权限不足、存储空间不足等）。
  • 分布式同步：若需跨设备同步，需确保设备组网并开启 autoSync。

通过以上步骤，可快速实现鸿蒙Next键值型数据库的增删改查及数据监听功能。

回到顶部