鸿蒙三方库 | harmony-utils之KvUtil键值型数据库操作详解

前言

键值型数据库（KV-Store）是HarmonyOS提供的轻量级数据存储方案，适合存储结构简单的数据。@pura/harmony-utils 的 KvUtil 封装了KV数据库的增删改查方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、KvUtil核心API

KvUtil 提供了以下键值型数据库操作方法：

方法	说明	返回类型	使用场景
`put(key, value)`	写入键值对	void	数据存储
`get(key)`	读取值	string	数据查询
`delete(key)`	删除键值对	void	数据清理
`sync()`	同步数据	void	多设备同步

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
分布式同步：支持多设备间的数据同步

1.2 KV数据库与Preferences对比

特性	KV数据库	Preferences
数据量	大	小
数据类型	多样	基本类型
分布式	支持	不支持
适用场景	复杂数据存储	简单配置存储

二、完整使用步骤

2.1 安装依赖

bash 复制代码

ohpm install @pura/harmony-utils

2.2 写入数据

typescript 复制代码

import { KvUtil } from '@pura/harmony-utils';

Button('写入数据')
  .width('100%')
  .onClick(async () => {
    try {
      await KvUtil.put('user_name', '张三');
      await KvUtil.put('user_age', '25');
      this.result = '数据写入成功 ✅\nkey: user_name, user_age';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 读取数据

typescript 复制代码

Button('读取数据')
  .width('100%')
  .onClick(async () => {
    try {
      let name = await KvUtil.get('user_name');
      let age = await KvUtil.get('user_age');
      this.result = `姓名: ${name}\n年龄: ${age}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 删除数据

typescript 复制代码

Button('删除数据')
  .width('100%')
  .onClick(async () => {
    try {
      await KvUtil.delete('user_name');
      this.result = '数据已删除 🗑️';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

typescript 复制代码

import { KvUtil } from '@pura/harmony-utils';

@Entry
@Component
struct KvDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('写入数据').width('100%').onClick(async () => {
        try {
          await KvUtil.put('demo_key', 'Hello KV!');
          this.result = '写入成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('读取数据').width('100%').onClick(async () => {
        try {
          let value = await KvUtil.get('demo_key');
          this.result = `值: ${value}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 数据仓库封装

typescript 复制代码

import { KvUtil } from '@pura/harmony-utils';

class UserRepository {
  private static PREFIX = 'user_';

  static async saveUser(user: Record<string, string>): Promise<void> {
    await KvUtil.put(UserRepository.PREFIX + 'name', user.name);
    await KvUtil.put(UserRepository.PREFIX + 'age', user.age);
  }

  static async getUser(): Promise<Record<string, string>> {
    return {
      name: await KvUtil.get(UserRepository.PREFIX + 'name') || '',
      age: await KvUtil.get(UserRepository.PREFIX + 'age') || ''
    };
  }
}

4.2 数据同步

typescript 复制代码

async function syncData(): Promise<void> {
  await KvUtil.sync();
  ToastUtil.showToast('数据同步完成');
}

五、注意事项

异步操作：KV操作为异步方法，需使用await
Key规范：建议使用有意义的key命名
数据大小：单个value不宜过大
初始化依赖 ：使用前需确保 AppUtil.init() 已调用
分布式：分布式同步需设备在同一网络

六、常见问题

Q1: put()写入后get()读不到？

可能是异步操作未完成，确保使用await等待写入完成。

Q2: KV数据库初始化失败？

检查是否配置了分布式权限，以及数据库创建是否成功。

Q3: 如何批量写入数据？

可以循环调用put方法，或使用事务批量提交。

Q4: 数据同步延迟大？

分布式同步依赖网络环境，建议在WiFi下进行同步。

总结

KvUtil 的键值型数据库操作方法为数据存储提供了轻量级方案。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以根据数据复杂度选择KV数据库或Preferences。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。