• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 通过键值型数据库实现数据持久化
2
3
4## 场景介绍
5
6键值型数据库存储键值对形式的数据，当需要存储的数据没有复杂的关系模型，比如存储商品名称及对应价格、员工工号及今日是否已出勤等，由于数据复杂度低，更容易兼容不同数据库版本和设备类型，因此推荐使用键值型数据库持久化此类数据。
7
8
9## 约束限制
10
11- 设备协同数据库，针对每条记录，Key的长度≤896 Byte，Value的长度<4 MB。
12
13- 单版本数据库，针对每条记录，Key的长度≤1 KB，Value的长度<4 MB。
14
15- 每个应用程序最多支持同时打开16个键值型分布式数据库。
16
17- 键值型数据库事件回调方法中不允许进行阻塞操作，例如修改UI组件。
18
19
20## 接口说明
21
22以下是键值型数据库持久化功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[分布式键值数据库](../reference/apis-arkdata/js-apis-distributedKVStore.md)。
23
24| 接口名称 | 描述 |
25| -------- | -------- |
26| createKVManager(config: KVManagerConfig): KVManager | 创建一个KVManager对象实例，用于管理数据库对象。 |
27| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | 指定Options和storeId，创建并得到指定类型的KVStore数据库。 |
28| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void | 添加指定类型的键值对到数据库。 |
29| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void | 获取指定键的值。 |
30| delete(key: string, callback: AsyncCallback<void>): void | 从数据库中删除指定键值的数据。 |
31
32
33## 开发步骤
34
351. 若要使用键值型数据库，首先要获取一个KVManager实例，用于管理数据库对象。示例代码如下所示：
36
37   Stage模型示例：
38
39
40   ```js
41   // 导入模块
42   import distributedKVStore from '@ohos.data.distributedKVStore';
43
44   // Stage模型
45   import window from '@ohos.window';
46   import UIAbility from '@ohos.app.ability.UIAbility';
47   import { BusinessError } from '@ohos.base';
48
49   let kvManager: distributedKVStore.KVManager | undefined = undefined;
50
51   export default class EntryAbility extends UIAbility {
52     onCreate() {
53       let context = this.context;
54       const kvManagerConfig: distributedKVStore.KVManagerConfig = {
55         context: context,
56         bundleName: 'com.example.datamanagertest'
57       };
58       try {
59         // 创建KVManager实例
60         kvManager = distributedKVStore.createKVManager(kvManagerConfig);
61         console.info('Succeeded in creating KVManager.');
62         // 继续创建获取数据库
63       } catch (e) {
64         let error = e as BusinessError;
65         console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
66       }
67     }
68   }
69   if (kvManager !== undefined) {
70      kvManager = kvManager as distributedKVStore.KVManager;
71     //进行后续操作
72     //...
73   }
74   ```
75
76   FA模型示例：
77
78
79   ```js
80   // 导入模块
81   import distributedKVStore from '@ohos.data.distributedKVStore';
82
83   // FA模型
84   import featureAbility from '@ohos.ability.featureAbility';
85
86   let kvManager: distributedKVStore.KVManager | undefined = undefined;
87   let context = featureAbility.getContext(); // 获取context
88   const kvManagerConfig: distributedKVStore.KVManagerConfig = {
89     context: context,
90     bundleName: 'com.example.datamanagertest'
91   };
92   try {
93     kvManager = distributedKVStore.createKVManager(kvManagerConfig);
94     console.info('Succeeded in creating KVManager.');
95     // 继续创建获取数据库
96   } catch (e) {
97      let error = e as BusinessError;
98      console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
99   }
100   if (kvManager !== undefined) {
101     kvManager = kvManager as distributedKVStore.KVManager;
102     //进行后续操作
103     //...
104   }
105
106   ```
107
1082. 创建并获取键值数据库。示例代码如下所示：
109
110   ```js
111   let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
112   try {
113     const options: distributedKVStore.Options = {
114       createIfMissing: true,
115       encrypt: false,
116       backup: false,
117       autoSync: false,
118       // kvStoreType不填时，默认创建多设备协同数据库
119       kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
120       // 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
121       securityLevel: distributedKVStore.SecurityLevel.S1
122     };
123     kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
124       if (err) {
125         console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
126         return;
127       }
128       console.info('Succeeded in getting KVStore.');
129       kvStore = store;
130       // 请确保获取到键值数据库实例后，再进行相关数据操作
131     });
132   } catch (e) {
133     let error = e as BusinessError;
134     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
135   }
136   if (kvStore !== undefined) {
137     kvStore = kvStore as distributedKVStore.SingleKVStore;
138       //进行后续操作
139       //...
140   }
141   ```
142
1433. 调用put()方法向键值数据库中插入数据。示例代码如下所示：
144
145   ```js
146   const KEY_TEST_STRING_ELEMENT = 'key_test_string';
147   const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
148   try {
149     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
150       if (err !== undefined) {
151         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
152         return;
153       }
154       console.info('Succeeded in putting data.');
155     });
156   } catch (e) {
157     let error = e as BusinessError;
158     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
159   }
160   ```
161
162   > **说明：**
163   >
164   > 当Key值存在时，put()方法会修改其值，否则新增一条数据。
165
1664. 调用get()方法获取指定键的值。示例代码如下所示：
167
168   ```js
169   const KEY_TEST_STRING_ELEMENT = 'key_test_string';
170   const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
171   try {
172     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
173       if (err !== undefined) {
174         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
175         return;
176       }
177       console.info('Succeeded in putting data.');
178       kvStore = kvStore as distributedKVStore.SingleKVStore;
179       kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
180         if (err != undefined) {
181           console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
182           return;
183         }
184         console.info(`Succeeded in getting data. Data:${data}`);
185       });
186     });
187   } catch (e) {
188     let error = e as BusinessError;
189     console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
190   }
191   ```
192
1935. 调用delete()方法删除指定键值的数据。示例代码如下所示：
194
195   ```js
196   const KEY_TEST_STRING_ELEMENT = 'key_test_string';
197   const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
198   try {
199     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
200       if (err !== undefined) {
201         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
202         return;
203       }
204       console.info('Succeeded in putting data.');
205       kvStore = kvStore as distributedKVStore.SingleKVStore;
206       kvStore.delete(KEY_TEST_STRING_ELEMENT, (err) => {
207         if (err !== undefined) {
208           console.error(`Failed to delete data. Code:${err.code},message:${err.message}`);
209           return;
210         }
211         console.info('Succeeded in deleting data.');
212       });
213     });
214   } catch (e) {
215     let error = e as BusinessError;
216     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
217   }
218   ```
219