当前位置：首页 > news >正文

【鸿蒙HarmonyOS NEXT】数据存储之分布式键值数据库

news 2025/8/8 4:00:18

【鸿蒙HarmonyOS NEXT】数据存储之分布式键值数据库

一、环境说明
二、分布式键值数据库介绍
三、示例代码加以说明
四、小结

一、环境说明

DevEco Studio 版本：
API版本：以12为主

二、分布式键值数据库介绍

KVStore简介：

分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。该模块提供以下分布式键值数据库相关的常用功能：

KVManager：分布式键值数据库管理实例，用于获取数据库的相关信息。
KVStoreResultSet：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。
Query：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。
SingleKVStore：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和同步数据的方法。
DeviceKVStore：设备协同数据库，继承自SingleKVStore，以设备维度对数据进行区分，提供查询数据和同步数据的方法。

应用场景：

键值型数据库存储键值对形式的数据，当需要存储的数据没有复杂的关系模型，比如存储商品名称及对应价格、员工工号及今日是否已出勤等，由于数据复杂度低，更容易兼容不同数据库版本和设备类型，因此推荐使用键值型数据库持久化此类数据。

常用接口说明：

键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，其他接口请查看官网：分布式键值数据库接口说明

三、示例代码加以说明

沿用【鸿蒙HarmonyOS NEXT】页面之间相互传递参数博文中的代码，进行测试。
使用场景说明：用户信息需要在整个app中全局获取到，需要将用户信息在登录的时候存储到分布式键值数据库中。

代码改写如下：

LoginPage完整代码如下：

import { router } from '@kit.ArkUI';// 引入Context相关
import { common } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';// 引入preferences相关
import { distributedKVStore } from '@kit.ArkData';
import { util } from '@kit.ArkTS';
import { BusinessError } from '@kit.BasicServicesKit';// 定义ihlog日志常量相关
const TAG: string = '[LoginPage_Context]';
const DOMAIN_NUMBER: number = 0xFF00;@Preview
@Entry
@Component
struct LoginPage {@State message: string = '登录页';@State btnMsg: string = '登录';@State account: string = ''; // 账号状态变量@State password: string = ''; // 密码状态变量@State isShowProgress: boolean = false; // 显示进度指示器的状态变量// 获取Contextprivate context = getContext(this) as common.UIAbilityContext;build() {Column() {Text(this.message).id('HelloWorld').fontSize(20).fontWeight(FontWeight.Bold).width('100%').height(50).textAlign(TextAlign.Center).backgroundColor(0xF1F3F5)Image($r('app.media.startIcon')).width(150).height(150).margin({ top: 40, bottom: 40 })TextInput({ placeholder: '请输入手机号' }).maxLength(11)// 最大长度.type(InputType.Number)// 输入类型为数字.inputStyle()// 应用自定义样式.onChange((value: string) => {this.account = value; // 更新账号状态})Line().lineStyle() // 应用自定义Line样式// 密码输入框TextInput({ placeholder: '请输入密码' }).maxLength(12)// 最大长度.type(InputType.Password)// 输入类型为密码.inputStyle()// 应用自定义样式.onChange((value: string) => {// TODO: 生产环境需要使用正则表达式对手机号进行验证this.password = value; // 更新密码状态})Line().lineStyle() // 应用自定义Line样式Button(this.btnMsg).width('80%').margin({ top: 100 }).height(50).onClick(() => {if (this.account === undefined || this.account === '') {console.info('请输入账号')return}if (this.password === undefined || this.password === '') {console.info('请输入密码')return}// 使用ArkData分布式键值数据库 以Key/Value形式存储用户信息数据let kvManager: distributedKVStore.KVManager | undefined = undefined;const kvManagerConfig: distributedKVStore.KVManagerConfig = {context: this.context,bundleName: 'com.suben.hellotest'};try {// 创建KVManager实例kvManager = distributedKVStore.createKVManager(kvManagerConfig);console.info('Succeeded in creating KVManager.');} catch (e) {let error = e as BusinessError;console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);}// 继续创建获取数据库if (kvManager !== undefined) {kvManager = kvManager as distributedKVStore.KVManager;//进行后续操作let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;try {const options: distributedKVStore.Options = {createIfMissing: true,encrypt: false,backup: false,autoSync: false,// kvStoreType不填时，默认创建多设备协同数据库kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,// 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,securityLevel: distributedKVStore.SecurityLevel.S1};kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options,(err, store: distributedKVStore.SingleKVStore) => {if (err) {console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);return;}console.info('Succeeded in getting KVStore.');kvStore = store; // 请确保获取到键值数据库实例后，再进行相关数据操作if (kvStore !== undefined) {kvStore = kvStore as distributedKVStore.SingleKVStore;//进行后续操作，如将用户信息插入数据库中进行保存const KEY_ACCOUNT = 'account';const VALUE_ACCOUNT = this.account;const KEY_PASSWORD = 'password';const VALUE_PASSWORD = this.password;try {kvStore.put(KEY_ACCOUNT, VALUE_ACCOUNT, (err) => {if (err !== undefined) {console.error(`Failed to put account data. Code:${err.code},message:${err.message}`);return;}console.info('Succeeded in putting account data.');});kvStore.put(KEY_PASSWORD, VALUE_PASSWORD, (err) => {if (err !== undefined) {console.error(`Failed to put password data. Code:${err.code},message:${err.message}`);return;}console.info('Succeeded in putting password data.');});} catch (e) {let error = e as BusinessError;console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);}}});} catch (e) {let error = e as BusinessError;console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);}}// 跳转到首页router.pushUrl({url: 'pages/HomePage',params: {account: this.account,password: this.password}})})}.height('100%').width('100%').padding(0)}
}// TextInput组件的自定义样式扩展
@Extend(TextInput)
function inputStyle() {.placeholderColor(Color.Gray) // 占位符颜色.height(50) // 输入框高度.fontSize(15) // 字体大小.backgroundColor(0xF1F3F5) // 背景颜色.width('90%') // 宽度为父组件的100%.padding({ left: 12 }) // 左侧填充.margin({ top: 15 }) // 上方边距
}// Line组件的自定义样式扩展
@Extend(Line)
function lineStyle() {.width('100%') // 宽度为父组件的100%.height(1) // 高度.backgroundColor(0xF1F3F5) // 背景颜色
}

HomePage完整代码如下：

import { router } from '@kit.ArkUI';
import { distributedKVStore } from '@kit.ArkData';
import { common } from '@kit.AbilityKit'
import { util } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';// 定义ihlog日志常量相关
const TAG: string = '[HomePage_Context]';
const DOMAIN_NUMBER: number = 0xFF01;@Preview
@Entry
@Component
struct HomePage {@State message: string = '首页';// 获取前一个页面传递过来的数据@State account: string = ''@State password: string = ''// 获取Contextprivate context = getContext(this) as common.UIAbilityContext;aboutToAppear(): void {// 使用ArkData KV数据库 获取用户数据// this.account = this.dataPreferences.getSync('account', 'default').toString(); // 'default' 可以换成其他的，如null，但这个参数必须给// hilog.info(DOMAIN_NUMBER, TAG, `account: ${this.account}`);// // 当获取的值为带有特殊字符的字符串时，需要将获取到的Uint8Array转换为字符串// let uInt8Array2 : preferences.ValueType = this.dataPreferences.getSync('password', new Uint8Array(0));// let textDecoder = util.TextDecoder.create('utf-8');// this.password = textDecoder.decodeToString(uInt8Array2 as Uint8Array);// hilog.info(DOMAIN_NUMBER, TAG, `password: ${this.password}`);let kvManager: distributedKVStore.KVManager | undefined = undefined;const kvManagerConfig: distributedKVStore.KVManagerConfig = {context: this.context,bundleName: 'com.suben.hellotest'};try {// 创建KVManager实例kvManager = distributedKVStore.createKVManager(kvManagerConfig);console.info('Succeeded in creating KVManager.');} catch (e) {let error = e as BusinessError;console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);}// 继续创建获取数据库if (kvManager !== undefined) {kvManager = kvManager as distributedKVStore.KVManager;//进行后续操作let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;try {const options: distributedKVStore.Options = {createIfMissing: true,encrypt: false,backup: false,autoSync: false,// kvStoreType不填时，默认创建多设备协同数据库kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,// 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,securityLevel: distributedKVStore.SecurityLevel.S1};kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options,(err, store: distributedKVStore.SingleKVStore) => {if (err) {console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);return;}console.info('Succeeded in getting KVStore.');kvStore = store; // 请确保获取到键值数据库实例后，再进行相关数据操作if (kvStore !== undefined) {kvStore = kvStore as distributedKVStore.SingleKVStore;const KEY_ACCOUNT = 'account';const KEY_PASSWORD = 'password';// 获取账户kvStore.get(KEY_ACCOUNT, (err, data) => {if (err != undefined) {console.error(`Failed to get ACCOUNT data. Code:${err.code},message:${err.message}`);return;}console.info(`Succeeded in getting ACCOUNT data. Data:${data}`);this.account = data.toString()});//获取密码kvStore.get(KEY_PASSWORD, (err, data) => {if (err != undefined) {console.error(`Failed to get PASSWORD data. Code:${err.code},message:${err.message}`);return;}console.info(`Succeeded in getting PASSWORD data. Data:${data}`);this.password = data.toString()});}});} catch (e) {let error = e as BusinessError;console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);}}}build() {Column() {Text(this.message).fontSize(30).width('100%').height(50).textAlign(TextAlign.Center).backgroundColor(0xF1F3F5)Blank().height(120)Text(`接收到的用户名：${this.account}`).fontSize(20).width('100%').height(50).padding({ left: 12, right: 12 })Text(`接收到的密码：${this.password}`).fontSize(20).width('100%').height(50).padding({ left: 12, right: 12 })Button('返回上一页').width('80%').margin({ top: 120 }).height(50).onClick(() => {// 返回登录页面router.showAlertBeforeBackPage({ message: '确认返回上一页吗？' })router.back({url: 'pages/LoginPage',params: {msg: 'homepage'}})})}.height('100%').width('100%')}
}