1# @ohos.data.distributedData (分布式数据管理) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @ding_dong_dong--> 5<!--Designer: @dboy190; @houpengtao1--> 6<!--Tester: @logic42--> 7<!--Adviser: @ge-yafang--> 8 9分布式数据管理为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式数据各个接口，应用程序可将数据保存到分布式数据库中，并可对分布式数据库中的数据进行增加、删除、修改、查询、同步等操作。 10 11该模块提供以下分布式数据管理相关的常用功能： 12 13- [KVManager](#kvmanager)：数据管理实例，用于获取KVStore的相关信息。 14- [KvStoreResultSet<sup>8+</sup>](#kvstoreresultset8)：提供获取KVStore数据库结果集的相关方法，包括查询和移动数据读取位置等。 15- [Query<sup>8+</sup>](#query8)：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 16- [KVStore](#kvstore)：KVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。 17- [SingleKVStore](#singlekvstore)：单版本分布式数据库，继承自[KVStore](#kvstore)，不对数据所属设备进行区分，提供查询数据和同步数据的方法。 18- [DeviceKVStore<sup>8+</sup>](#devicekvstore8)：设备协同数据库，继承自[KVStore](#kvstore)，以设备维度对数据进行区分，提供查询数据和同步数据的方法。 19 20>**说明：** 21> 22>- 从API Version 9开始，该接口不再维护，推荐使用新接口[`@ohos.data.distributedKVStore`](js-apis-distributedKVStore.md)。 23> 24>- 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 25> 26>- 本模块中所有需要获取deviceId的接口，都仅系统应用可用。 27 28 29## 导入模块 30 31```js 32import distributedData from '@ohos.data.distributedData'; 33``` 34 35 36## distributedData.createKVManager 37 38createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void 39 40创建一个KVManager对象实例，用于管理数据库对象，使用callback异步回调。 41 42**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 43 44**参数：** 45 46| 参数名 | 类型 | 必填 | 说明 | 47| ----- | ------ | ------ | ------ | 48| config | [KVManagerConfig](#kvmanagerconfig) | 是 | 提供KVManager实例的配置信息，包括调用方的Bundle名称和用户信息。 | 49| callback | AsyncCallback<[KVManager](#kvmanager)> | 是 | 回调函数。返回创建的KVManager对象实例。 | 50 51**示例：** 52```js 53 54let kvManager; 55try { 56 const kvManagerConfig = { 57 bundleName : 'com.example.datamanagertest', 58 userInfo : { 59 userId : '0', 60 userType : distributedData.UserType.SAME_USER_ID 61 } 62 } 63 distributedData.createKVManager(kvManagerConfig, function (err, manager) { 64 if (err) { 65 console.log("Failed to create KVManager: " + JSON.stringify(err)); 66 return; 67 } 68 console.log("Succeeded in creating KVManager"); 69 kvManager = manager; 70 }); 71} catch (e) { 72 console.log("An unexpected error occurred. Error:" + e); 73} 74``` 75 76## distributedData.createKVManager 77 78createKVManager(config: KVManagerConfig): Promise<KVManager> 79 80创建一个KVManager对象实例，用于管理数据库对象，使用Promise异步回调。 81 82**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| ----- | ------ | ------ | ------ | 88| config |[KVManagerConfig](#kvmanager) | 是 | 提供KVManager实例的配置信息，包括调用方的包名和用户信息。 | 89 90**返回值：** 91 92| 类型 | 说明 | 93| -------- | -------- | 94| Promise<[KVManager](#kvmanager)> | Promise对象。返回创建的KVManager对象实例。 | 95 96**示例：** 97```js 98 99try { 100 const kvManagerConfig = { 101 bundleName: 'com.example.datamanagertest', 102 userInfo: { 103 userId: '0', 104 userType: distributedData.UserType.SAME_USER_ID 105 } 106 } 107 distributedData.createKVManager(kvManagerConfig).then((manager) => { 108 console.log("Succeeded in creating KVManager"); 109 kvManager = manager; 110 }).catch((err) => { 111 console.error("Failed to create KVManager: " + JSON.stringify(err)); 112 }); 113} catch (e) { 114 console.log("An unexpected error occurred. Error:" + e); 115} 116``` 117 118## KVManagerConfig 119 120提供KVManager实例的配置信息，包括调用方的Bundle名称和用户信息。 121 122**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 123 124| 名称 | 类型 | 必填 | 说明 | 125| ----- | ------ | ------ | ------ | 126| userInfo | [UserInfo](#userinfo) | 是 | 调用方的用户信息。 | 127| bundleName | string | 是 | 调用方的Bundle名称。 | 128 129## UserInfo 130 131用户信息。 132 133**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 134 135| 名称 | 类型 | 必填 | 说明 | 136| ----- | ------ |------ | ------ | 137| userId | string | 否 | 指示要设置的用户ID，默认为'0'。 | 138| userType | [UserType](#usertype) | 否 | 指示要设置的用户类型，默认为0。 | 139 140 141## UserType 142 143用户类型枚举。 144 145**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 146 147| 名称 | 值 | 说明 | 148| ----- | ------ | ------ | 149| SAME_USER_ID | 0 | 使用同一账号登录不同设备的用户。 | 150 151 152## KVManager 153 154数据管理实例，用于获取KVStore的相关信息。在调用KVManager的方法前，需要先通过[createKVManager](#distributeddatacreatekvmanager)构建一个KVManager实例。 155 156### getKVStore 157 158getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void 159 160通过指定Options和storeId，创建并获取KVStore数据库，使用callback异步回调。 161 162**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| ----- | ------ | ------ | ------ | 168| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 169| options | [Options](#options) | 是 | 创建KVStore实例的配置信息。 | 170| callback | AsyncCallback<T> | 是 | 回调函数。返回创建的KVStore数据库实例。 | 171 172**示例：** 173 174```js 175let kvStore; 176let kvManager; 177try { 178 const options = { 179 createIfMissing : true, 180 encrypt : false, 181 backup : false, 182 autoSync : true, 183 kvStoreType : distributedData.KVStoreType.SINGLE_VERSION, 184 securityLevel : distributedData.SecurityLevel.S3, 185 }; 186 kvManager.getKVStore('storeId', options, function (err, store) { 187 if (err) { 188 console.log("getKVStore err: " + JSON.stringify(err)); 189 return; 190 } 191 console.log("getKVStore success"); 192 kvStore = store; 193 }); 194} catch (e) { 195 console.log("An unexpected error occurred. Error:" + e); 196} 197``` 198 199 200### getKVStore 201 202getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T> 203 204通过指定Options和storeId，创建并获取KVStore数据库，使用Promise异步回调。 205 206**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| ------- | ---------------------- | ---- | -------------------- | 212| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 213| options | [Options](#options) | 是 | 创建KVStore实例的配置信息。| 214 215 216**返回值：** 217 218| 类型 | 说明 | 219| -------------------------------------- | ------------------------ | 220| Promise<T> ，<T extends [KVStore](#kvstore)> | Promise对象。返回创建的KVStore数据库实例。 | 221 222**示例：** 223 224```js 225let kvStore; 226let kvManager; 227try { 228 const options = { 229 createIfMissing : true, 230 encrypt : false, 231 backup : false, 232 autoSync : true, 233 kvStoreType : distributedData.KVStoreType.SINGLE_VERSION, 234 securityLevel : distributedData.SecurityLevel.S3, 235 }; 236 kvManager.getKVStore('storeId', options).then((store) => { 237 console.log("getKVStore success"); 238 kvStore = store; 239 }).catch((err) => { 240 console.log("getKVStore err: " + JSON.stringify(err)); 241 }); 242} catch (e) { 243 console.log("An unexpected error occurred. Error:" + e); 244} 245``` 246 247### closeKVStore<sup>8+</sup> 248 249closeKVStore(appId: string, storeId: string, kvStore: KVStore, callback: AsyncCallback<void>): void 250 251通过storeId的值关闭指定的KVStore数据库，使用callback异步回调。 252 253**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 254 255**参数：** 256 257 258| 参数名 | 类型 | 必填 | 说明 | 259| ------- | ----------------- | ---- | --------------------------- | 260| appId | string | 是 | 所调用数据库方的包名。 | 261| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 262| kvStore | [KVStore](#kvstore) | 是 | 要关闭的KVStore数据库。 | 263| callback | AsyncCallback<void> | 是 | 回调函数。 | 264 265**示例：** 266 267```js 268let kvStore; 269let kvManager; 270const options = { 271 createIfMissing: true, 272 encrypt: false, 273 backup: false, 274 autoSync: false, 275 kvStoreType: distributedData.KVStoreType.SINGLE_VERSION, 276 schema: undefined, 277 securityLevel: distributedData.SecurityLevel.S3, 278} 279try { 280 kvManager.getKVStore('storeId', options, async function (err, store) { 281 console.log('getKVStore success'); 282 kvStore = store; 283 kvManager.closeKVStore('appId', 'storeId', kvStore, function (err, data) { 284 console.log('closeKVStore success'); 285 }); 286 }); 287} catch (e) { 288 console.log('closeKVStore e ' + e); 289} 290``` 291 292 293### closeKVStore<sup>8+</sup> 294 295closeKVStore(appId: string, storeId: string, kvStore: KVStore): Promise<void> 296 297通过storeId的值关闭指定的KVStore数据库，使用Promise异步回调。 298 299**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| ----- | ------ | ---- | ----------------------------- | 305| appId | string | 是 | 所调用数据库方的包名。 | 306| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 307| kvStore | [KVStore](#kvstore) | 是 | 要关闭的KVStore数据库。 | 308 309**返回值：** 310 311| 类型 | 说明 | 312| ------------- | -------------- | 313| Promise\<void> | 无返回结果的Promise对象。 | 314 315**示例：** 316 317```js 318let kvManager; 319let kvStore; 320const options = { 321 createIfMissing: true, 322 encrypt: false, 323 backup: false, 324 autoSync: false, 325 kvStoreType: distributedData.KVStoreType.SINGLE_VERSION, 326 schema: undefined, 327 securityLevel: distributedData.SecurityLevel.S3, 328} 329try { 330 kvManager.getKVStore('storeId', options).then(async (store) => { 331 console.log('getKVStore success'); 332 kvStore = store; 333 kvManager.closeKVStore('appId', 'storeId', kvStore).then(() => { 334 console.log('closeKVStore success'); 335 }).catch((err) => { 336 console.log('closeKVStore err ' + JSON.stringify(err)); 337 }); 338 }).catch((err) => { 339 console.log('CloseKVStore getKVStore err ' + JSON.stringify(err)); 340 }); 341} catch (e) { 342 console.log('closeKVStore e ' + e); 343} 344``` 345 346 347### deleteKVStore<sup>8+</sup> 348 349deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void 350 351通过storeId的值删除指定的KVStore数据库，使用callback异步回调。 352 353**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 354 355**参数：** 356 357| 参数名 | 类型 | 必填 | 说明 | 358| ----- | ------ | ---- | ----------------------- | 359| appId | string | 是 | 所调用数据库方的包名。 | 360| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 361| callback | AsyncCallback<void> | 是 | 回调函数。 | 362 363**示例：** 364 365```js 366let kvManager; 367let kvStore; 368const options = { 369 createIfMissing : true, 370 encrypt : false, 371 backup : false, 372 autoSync : true, 373 kvStoreType : distributedData.KVStoreType.SINGLE_VERSION, 374 schema : undefined, 375 securityLevel : distributedData.SecurityLevel.S3, 376} 377try { 378 kvManager.getKVStore('store', options, async function (err, store) { 379 console.log('getKVStore success'); 380 kvStore = store; 381 kvManager.deleteKVStore('appId', 'storeId', function (err, data) { 382 console.log('deleteKVStore success'); 383 }); 384 }); 385} catch (e) { 386 console.log('DeleteKVStore e ' + e); 387} 388``` 389 390### deleteKVStore<sup>8+</sup> 391 392deleteKVStore(appId: string, storeId: string): Promise<void> 393 394通过storeId的值删除指定的KVStore数据库，使用Promise异步回调。 395 396**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 397 398**参数：** 399 400| 参数名 | 类型 | 必填 | 说明 | 401| ----- | ------ | ---- | ----------------------- | 402| appId | string | 是 | 所调用数据库方的包名。 | 403| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)。 | 404 405 406**返回值：** 407 408| 类型 | 说明 | 409| ------------- | -------------- | 410| Promise<void> | 无返回结果的Promise对象。 | 411 412**示例：** 413 414```js 415let kvManager; 416let kvStore; 417const options = { 418 createIfMissing : true, 419 encrypt : false, 420 backup : false, 421 autoSync : true, 422 kvStoreType : distributedData.KVStoreType.SINGLE_VERSION, 423 schema : undefined, 424 securityLevel : distributedData.SecurityLevel.S3, 425} 426try { 427 kvManager.getKVStore('storeId', options).then(async (store) => { 428 console.log('getKVStore success'); 429 kvStore = store; 430 kvManager.deleteKVStore('appId', 'storeId').then(() => { 431 console.log('deleteKVStore success'); 432 }).catch((err) => { 433 console.log('deleteKVStore err ' + JSON.stringify(err)); 434 }); 435 }).catch((err) => { 436 console.log('getKVStore err ' + JSON.stringify(err)); 437 }); 438} catch (e) { 439 console.log('deleteKVStore e ' + e); 440} 441``` 442 443 444### getAllKVStoreId<sup>8+</sup> 445 446getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void 447 448获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore8)方法删除的KVStore数据库的storeId，使用callback异步回调。 449 450**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 451 452**参数：** 453 454| 参数名 | 类型 | 必填 | 说明 | 455| ----- | ------ | ---- | ----------------------- | 456| appId | string | 是 | 所调用数据库方的包名。 | 457| callback | AsyncCallback<string[]> | 是 |回调函数。返回所有创建的KvStore数据库的storeId。 | 458 459**示例：** 460 461```js 462let kvManager; 463try { 464 kvManager.getAllKVStoreId('appId', function (err, data) { 465 console.log('GetAllKVStoreId success'); 466 console.log('GetAllKVStoreId size = ' + data.length); 467 }); 468} catch (e) { 469 console.log('GetAllKVStoreId e ' + e); 470} 471``` 472 473 474### getAllKVStoreId<sup>8+</sup> 475 476getAllKVStoreId(appId: string): Promise<string[]> 477 478获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore8)方法删除的KVStore数据库的storeId，使用Promise异步回调。 479 480**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 481 482**参数：** 483 484| 参数名 | 类型 | 必填 | 说明 | 485| ----- | ------ | ---- | ----------------------- | 486| appId | string | 是 | 所调用数据库方的包名。 | 487 488 489**返回值：** 490 491| 类型 | 说明 | 492| ------------- | -------------- | 493| Promise<string[]>| Promise对象。返回所有创建的KvStore数据库的storeId。 | 494 495**示例：** 496 497```js 498let kvManager; 499try { 500 console.log('GetAllKVStoreId'); 501 kvManager.getAllKVStoreId('appId').then((data) => { 502 console.log('getAllKVStoreId success'); 503 console.log('size = ' + data.length); 504 }).catch((err) => { 505 console.log('getAllKVStoreId err ' + JSON.stringify(err)); 506 }); 507} catch(e) { 508 console.log('getAllKVStoreId e ' + e); 509} 510``` 511 512 513### on('distributedDataServiceDie')<sup>8+</sup> 514 515on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void 516 517订阅服务状态变更通知。 518 519**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 520 521**参数：** 522 523| 参数名 | 类型 | 必填 | 说明 | 524| ----- | ------ | ---- | ----------------------- | 525| event | string | 是 | 订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 526| deathCallback | Callback<void> | 是 | 回调函数。 | 527 528**示例：** 529 530```js 531let kvManager; 532try { 533 console.log('KVManagerOn'); 534 const deathCallback = function () { 535 console.log('death callback call'); 536 } 537 kvManager.on('distributedDataServiceDie', deathCallback); 538} catch (e) { 539 console.log("An unexpected error occurred. Error:" + e); 540} 541``` 542 543 544### off('distributedDataServiceDie')<sup>8+</sup> 545 546off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void 547 548取消订阅服务状态变更通知。 549 550**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 551 552**参数：** 553 554| 参数名 | 类型 | 必填 | 说明 | 555| ----- | ------ | ---- | ----------------------- | 556| event | string | 是 | 取消订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 557| deathCallback | Callback<void> | 否 | 取消订阅的函数。如不设置callback，则取消所有已订阅的函数。 | 558 559 560**示例：** 561 562```js 563let kvManager; 564try { 565 console.log('KVManagerOff'); 566 const deathCallback = function () { 567 console.log('death callback call'); 568 } 569 kvManager.off('distributedDataServiceDie', deathCallback); 570} catch (e) { 571 console.log("An unexpected error occurred. Error:" + e); 572} 573 574``` 575 576## Options 577 578用于提供创建数据库的配置信息。 579 580 581| 名称 | 类型 | 必填 | 说明 | 582| ----- | ------ | ------ | -------------------| 583| createIfMissing | boolean | 否 | 当数据库文件不存在时是否创建数据库，默认为true，即创建。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 584| encrypt | boolean | 否 |设置数据库文件是否加密，默认为false，即不加密。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 585| backup | boolean | 否 |设置数据库文件是否备份，默认为true，即备份。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 586| autoSync | boolean | 否 |设置数据库文件是否自动同步。默认为false，即手动同步。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core<br>**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC | 587| kvStoreType | [KVStoreType](#kvstoretype) | 否 |设置要创建的数据库类型，默认为DEVICE_COLLABORATION，即多设备协同数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 588| securityLevel | [SecurityLevel](#securitylevel) | 否 |设置数据库安全级别(S1-S4)。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 589| schema<sup>8+</sup> | [Schema](#schema8) | 否 | 设置定义存储在数据库中的值，默认为undefined，即不使用schema。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 590 591 592## KVStoreType 593 594KVStore数据库类型枚举。 595 596 597| 名称 | 值 | 说明 | 598| --- | ---- | ----------------------- | 599| DEVICE_COLLABORATION | 0 | 表示多设备协同数据库。<br>**数据库特点：** 数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 600| SINGLE_VERSION | 1 | 表示单版本数据库。<br>**数据库特点：** 数据不分设备，设备之间修改相同的key会覆盖。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 601| MULTI_VERSION | 2 | 表示多版本数据库。当前暂不支持使用此接口。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 602 603 604## SecurityLevel 605 606数据库的安全级别枚举。 607 608| 名称 | 值 | 说明 | 609| --- | ---- | ----------------------- | 610| NO_LEVEL | 0 | 表示数据库不设置安全级别(已废弃)。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 611| S0 | 1 | 表示数据库的安全级别为公共级别(已废弃)。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 612| S1 | 2 | 表示数据库的安全级别为低级别，当数据泄露时会产生较低影响。例如，包含壁纸等系统数据的数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 613| S2 | 3 | 表示数据库的安全级别为中级别，当数据泄露时会产生较大影响。例如，包含录音、视频等用户生成数据或通话记录等信息的数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 614| S3 | 5 | 表示数据库的安全级别为高级别，当数据泄露时会产生重大影响。例如，包含用户运动、健康、位置等信息的数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 615| S4 | 6 | 表示数据库的安全级别为关键级别，当数据泄露时会产生严重影响。例如，包含认证凭据、财务数据等信息的数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 616 617 618## Constants 619 620KVStore常量。 621 622**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 623 624| 名称 | 值 | 说明 | 625| --- | ---- | ----------------------- | 626| MAX_KEY_LENGTH | 1024 | 数据库中Key允许的最大长度，单位字节。 | 627| MAX_VALUE_LENGTH | 4194303 | 数据库中Value允许的最大长度，单位字节。 | 628| MAX_KEY_LENGTH_DEVICE | 896 | 最大设备密钥长度，单位字节。 | 629| MAX_STORE_ID_LENGTH | 128 | 数据库标识符允许的最大长度，单位字节。 | 630| MAX_QUERY_LENGTH | 512000 | 最大查询长度，单位字节。 | 631| MAX_BATCH_SIZE | 128 | 最大批处理操作数量。 | 632 633## Schema<sup>8+</sup> 634 635表示数据库模式，可以在创建或打开数据库时创建Schema对象并将它们放入[Options](#options)中。 636 637**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 638 639| 名称 | 类型 | 可读 | 可写 | 说明 | 640| --- | ---- | ---- | ---- | ----------------------- | 641| root<sup>8+</sup> | [FieldNode](#fieldnode8) | 是 | 是 | 表示json根对象。 | 642| indexes<sup>8+</sup> | Array\<string> | 是 | 是 | 表示json类型的字符串数组。 | 643| mode<sup>8+</sup> | number | 是 | 是 | 表示Schema的模式。 | 644| skip<sup>8+</sup> | number | 是 | 是 | Schema的跳跃大小。 | 645 646### constructor<sup>8+</sup> 647 648constructor() 649 650用于创建Schema实例的构造函数。 651 652**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 653 654## FieldNode<sup>8+</sup> 655 656表示 Schema 实例的节点，提供定义存储在数据库中的值的方法。 657 658**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 659 660| 名称 | 类型 | 可读 | 可写 | 说明 | 661| --- | ---- | ---- | ---- | ----------------------- | 662| nullable<sup>8+</sup> | boolean | 是 | 是 | 表示数据库字段是否可以为空。 | 663| default<sup>8+</sup> | string | 是 | 是 | 表示Fieldnode的默认值。 | 664| type<sup>8+</sup> | number | 是 | 是 | 表示指定节点对应数据类型的值。 | 665 666### constructor<sup>8+</sup> 667 668constructor(name: string) 669 670用于创建带有string字段FieldNode实例的构造函数。 671 672**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| ------ | -------- | ---- | --------------- | 678| name | string | 是 | FieldNode的值。 | 679 680### appendChild<sup>8+</sup> 681 682appendChild(child: FieldNode): boolean 683 684在当前 FieldNode 中添加一个子节点。 685 686**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 687 688**参数：** 689 690| 参数名 | 类型 | 必填 | 说明 | 691| ----- | ------ | ---- | ----------------------- | 692| child | [FieldNode](#fieldnode8) | 是 | 要附加的域节点。 | 693 694**返回值：** 695 696| 类型 | 说明 | 697| ------------- | -------------- | 698| boolean |返回true表示子节点成功添加到FieldNode；返回false则表示操作失败。 | 699 700**示例：** 701 702```js 703import ddm from '@ohos.data.distributedData'; 704try { 705 let node = new ddm.FieldNode("root"); 706 let child1 = new ddm.FieldNode("child1"); 707 let child2 = new ddm.FieldNode("child2"); 708 let child3 = new ddm.FieldNode("child3"); 709 node.appendChild(child1); 710 node.appendChild(child2); 711 node.appendChild(child3); 712 console.log("appendNode " + JSON.stringify(node)); 713 child1 = null; 714 child2 = null; 715 child3 = null; 716 node = null; 717} catch (e) { 718 console.log("AppendChild " + e); 719} 720``` 721 722 723## KvStoreResultSet<sup>8+</sup> 724 725提供获取KVStore数据库结果集的相关方法，包括查询和移动数据读取位置等。 726 727在调用KvStoreResultSet的方法前，需要先通过[getKVStore](#getkvstore)构建一个KVStore实例。 728 729 730### getCount<sup>8+</sup> 731 732getCount(): number 733 734获取结果集中的总行数。 735 736**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 737 738**返回值：** 739 740| 类型 | 说明 | 741| ------ | -------------- | 742| number |返回数据的总行数。 | 743 744**示例：** 745 746```js 747let kvStore; 748try { 749 let resultSet; 750 kvStore.getResultSet('batch_test_string_key').then((result) => { 751 console.log('getResultSet succeed.'); 752 resultSet = result; 753 }).catch((err) => { 754 console.log('getResultSet failed: ' + err); 755 }); 756 const count = resultSet.getCount(); 757 console.log("getCount succeed:" + count); 758} catch (e) { 759 console.log("getCount failed: " + e); 760} 761``` 762 763### getPosition<sup>8+</sup> 764 765getPosition(): number 766 767获取结果集中当前的读取位置。 768 769**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 770 771**返回值：** 772 773| 类型 | 说明 | 774| ------ | -------------- | 775| number |返回当前读取位置。 | 776 777**示例：** 778 779```js 780let kvStore; 781try { 782 let resultSet; 783 kvStore.getResultSet('batch_test_string_key').then((result) => { 784 console.log('getResultSet succeeded.'); 785 resultSet = result; 786 }).catch((err) => { 787 console.log('getResultSet failed: ' + err); 788 }); 789 const position = resultSet.getPosition(); 790 console.log("getPosition succeed:" + position); 791} catch (e) { 792 console.log("getPosition failed: " + e); 793} 794``` 795 796 797### moveToFirst<sup>8+</sup> 798 799moveToFirst(): boolean 800 801将读取位置移动到第一行。如果结果集为空，则返回false。 802 803**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 804 805**返回值：** 806 807| 类型 | 说明 | 808| ------ | -------------- | 809| boolean |返回true表示操作成功；返回false则表示操作失败。 | 810 811**示例：** 812 813```js 814let kvStore; 815try { 816 let resultSet; 817 kvStore.getResultSet('batch_test_string_key').then((result) => { 818 console.log('getResultSet succeed.'); 819 resultSet = result; 820 }).catch((err) => { 821 console.log('getResultSet failed: ' + err); 822 }); 823 const moved1 = resultSet.moveToFirst(); 824 console.log("moveToFirst succeed: " + moved1); 825} catch (e) { 826 console.log("moveToFirst failed " + e); 827} 828``` 829 830 831### moveToLast<sup>8+</sup> 832 833moveToLast(): boolean 834 835将读取位置移动到最后一行。如果结果集为空，则返回false。 836 837**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 838 839**返回值：** 840 841| 类型 | 说明 | 842| ------ | -------------- | 843| boolean |返回true表示操作成功；返回false则表示操作失败。 | 844 845**示例：** 846 847```js 848let kvStore; 849try { 850 let resultSet; 851 kvStore.getResultSet('batch_test_string_key').then((result) => { 852 console.log('getResultSet succeed.'); 853 resultSet = result; 854 }).catch((err) => { 855 console.log('getResultSet failed: ' + err); 856 }); 857 const moved2 = resultSet.moveToLast(); 858 console.log("moveToLast succeed:" + moved2); 859} catch (e) { 860 console.log("moveToLast failed: " + e); 861} 862``` 863 864 865### moveToNext<sup>8+</sup> 866 867moveToNext(): boolean 868 869将读取位置移动到下一行。如果结果集为空，则返回false。 870 871**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 872 873**返回值：** 874 875| 类型 | 说明 | 876| ------ | -------------- | 877| boolean |返回true表示操作成功；返回false则表示操作失败。 | 878 879**示例：** 880 881```js 882let kvStore; 883try { 884 let resultSet; 885 kvStore.getResultSet('batch_test_string_key').then((result) => { 886 console.log('getResultSet succeed.'); 887 resultSet = result; 888 }).catch((err) => { 889 console.log('getResultSet failed: ' + err); 890 }); 891 const moved3 = resultSet.moveToNext(); 892 console.log("moveToNext succeed: " + moved3); 893} catch (e) { 894 console.log("moveToNext failed: " + e); 895} 896``` 897 898 899### moveToPrevious<sup>8+</sup> 900 901moveToPrevious(): boolean 902 903将读取位置移动到上一行。如果结果集为空，则返回false。 904 905**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 906 907**返回值：** 908 909| 类型 | 说明 | 910| ------ | -------------- | 911| boolean |返回true表示操作成功；返回false则表示操作失败。 | 912 913**示例：** 914 915```js 916let kvStore; 917try { 918 let resultSet; 919 kvStore.getResultSet('batch_test_string_key').then((result) => { 920 console.log('getResultSet succeed.'); 921 resultSet = result; 922 }).catch((err) => { 923 console.log('getResultSet failed: ' + err); 924 }); 925 const moved4 = resultSet.moveToPrevious(); 926 console.log("moveToPrevious succeed:" + moved4); 927} catch (e) { 928 console.log("moveToPrevious failed: " + e); 929} 930``` 931 932 933### move<sup>8+</sup> 934 935move(offset: number): boolean 936 937将读取位置移动到当前位置的相对偏移量。 938 939**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 940 941**参数：** 942 943| 参数名 | 类型 | 必填 | 说明 | 944| ----- | ------ | ---- | ----------------------- | 945| offset | number | 是 | 表示与当前位置的相对偏移量，负偏移表示向后移动，正偏移表示向前移动。 | 946 947**返回值：** 948 949| 类型 | 说明 | 950| ------ | -------------- | 951| boolean |返回true表示操作成功；返回false则表示操作失败。 | 952 953**示例：** 954 955```js 956let kvStore; 957try { 958 let resultSet; 959 kvStore.getResultSet('batch_test_string_key').then((result) => { 960 console.log('getResultSet succeed.'); 961 resultSet = result; 962 }).catch((err) => { 963 console.log('getResultSet failed: ' + err); 964 }); 965 const moved5 = resultSet.move(1); 966 console.log("move succeed:" + moved5); 967} catch (e) { 968 console.log("move failed: " + e); 969} 970``` 971 972 973### moveToPosition<sup>8+</sup> 974 975moveToPosition(position: number): boolean 976 977将读取位置从 0 移动到绝对位置。 978 979**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 980 981**参数：** 982 983| 参数名 | 类型 | 必填 | 说明 | 984| ----- | ------ | ---- | ----------------------- | 985| position | number | 是 |表示绝对位置。 | 986 987**返回值：** 988 989| 类型 | 说明 | 990| ------ | -------------- | 991| boolean |返回true表示操作成功；返回false则表示操作失败。 | 992 993**示例：** 994 995```js 996let kvStore; 997try { 998 let resultSet; 999 kvStore.getResultSet('batch_test_string_key').then((result) => { 1000 console.log('getResultSet succeed.'); 1001 resultSet = result; 1002 }).catch((err) => { 1003 console.log('getResultSet failed: ' + err); 1004 }); 1005 const moved6 = resultSet.moveToPosition(1); 1006 console.log("moveToPosition succeed: " + moved6); 1007} catch (e) { 1008 console.log("moveToPosition failed: " + e); 1009} 1010``` 1011 1012 1013### isFirst<sup>8+</sup> 1014 1015isFirst(): boolean 1016 1017检查读取位置是否为第一行。 1018 1019**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1020 1021**返回值：** 1022 1023| 类型 | 说明 | 1024| ------ | -------------- | 1025| boolean |返回true表示读取位置为第一行；返回false表示读取位置不是第一行。 | 1026 1027**示例：** 1028 1029```js 1030let kvStore; 1031try { 1032 let resultSet; 1033 kvStore.getResultSet('batch_test_string_key').then((result) => { 1034 console.log('getResultSet succeed.'); 1035 resultSet = result; 1036 }).catch((err) => { 1037 console.log('getResultSet failed: ' + err); 1038 }); 1039 const isfirst = resultSet.isFirst(); 1040 console.log("Check isFirst succeed:" + isfirst); 1041} catch (e) { 1042 console.log("Check isFirst failed: " + e); 1043} 1044``` 1045 1046 1047### isLast<sup>8+</sup> 1048 1049isLast(): boolean 1050 1051检查读取位置是否为最后一行。 1052 1053**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1054 1055**返回值：** 1056 1057| 类型 | 说明 | 1058| ------ | -------------- | 1059| boolean |返回true表示读取位置为最后一行；返回false表示读取位置不是最后一行。 | 1060 1061**示例：** 1062 1063```js 1064let kvStore; 1065try { 1066 let resultSet; 1067 kvStore.getResultSet('batch_test_string_key').then((result) => { 1068 console.log('getResultSet succeed.'); 1069 resultSet = result; 1070 }).catch((err) => { 1071 console.log('getResultSet failed: ' + err); 1072 }); 1073 const islast = resultSet.isLast(); 1074 console.log("Check isLast succeed: " + islast); 1075} catch (e) { 1076 console.log("Check isLast failed: " + e); 1077} 1078``` 1079 1080### isBeforeFirst<sup>8+</sup> 1081 1082isBeforeFirst(): boolean 1083 1084检查读取位置是否在第一行之前。 1085 1086**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1087 1088**返回值：** 1089 1090| 类型 | 说明 | 1091| ------ | -------------- | 1092| boolean |返回true表示读取位置在第一行之前；返回false表示读取位置不在第一行之前。 | 1093 1094**示例：** 1095 1096```js 1097let kvStore; 1098try { 1099 let resultSet; 1100 kvStore.getResultSet('batch_test_string_key').then((result) => { 1101 console.log('getResultSet succeed.'); 1102 resultSet = result; 1103 }).catch((err) => { 1104 console.log('getResultSet failed: ' + err); 1105 }); 1106 const isbeforefirst = resultSet.isBeforeFirst(); 1107 console.log("Check isBeforeFirst succeed: " + isbeforefirst); 1108} catch (e) { 1109 console.log("Check isBeforeFirst failed: " + e); 1110} 1111``` 1112 1113 1114### isAfterLast<sup>8+</sup> 1115 1116isAfterLast(): boolean 1117 1118检查读取位置是否在最后一行之后。 1119 1120**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1121 1122**返回值：** 1123 1124| 类型 | 说明 | 1125| ------ | -------------- | 1126| boolean |返回true表示读取位置在最后一行之后；返回false表示读取位置不在最后一行之后。 | 1127 1128**示例：** 1129 1130```js 1131let kvStore; 1132try { 1133 let resultSet; 1134 kvStore.getResultSet('batch_test_string_key').then((result) => { 1135 console.log('getResultSet succeed.'); 1136 resultSet = result; 1137 }).catch((err) => { 1138 console.log('getResultSet failed: ' + err); 1139 }); 1140 const isafterlast = resultSet.isAfterLast(); 1141 console.log("Check isAfterLast succeed:" + isafterlast); 1142} catch (e) { 1143 console.log("Check isAfterLast failed: " + e); 1144} 1145``` 1146 1147 1148### getEntry<sup>8+</sup> 1149 1150getEntry(): Entry 1151 1152从当前位置获取对应的键值对。 1153 1154**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1155 1156**返回值：** 1157 1158| 类型 | 说明 | 1159| ------ | ------- | 1160| [Entry](#entry) |返回键值对。| 1161 1162**示例：** 1163 1164```js 1165let kvStore; 1166try { 1167 let resultSet; 1168 kvStore.getResultSet('batch_test_string_key').then((result) => { 1169 console.log('getResultSet succeed.'); 1170 resultSet = result; 1171 }).catch((err) => { 1172 console.log('getResultSet failed: ' + err); 1173 }); 1174 const entry = resultSet.getEntry(); 1175 console.log("getEntry succeed:" + JSON.stringify(entry)); 1176} catch (e) { 1177 console.log("getEntry failed: " + e); 1178} 1179``` 1180 1181 1182## Query<sup>8+</sup> 1183 1184使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 1185 1186**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1187 1188### constructor<sup>8+</sup> 1189 1190constructor() 1191 1192用于创建Schema实例的构造函数。 1193 1194**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1195 1196 1197### reset<sup>8+</sup> 1198 1199reset(): Query 1200 1201重置Query对象。 1202 1203**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1204 1205 1206**返回值：** 1207 1208| 类型 | 说明 | 1209| ------ | ------- | 1210| [Query](#query8) |返回重置的Query对象。| 1211 1212**示例：** 1213 1214```js 1215try { 1216 let query = new distributedData.Query(); 1217 query.equalTo("key", "value"); 1218 console.log("query is " + query.getSqlLike()); 1219 query.reset(); 1220 console.log("query is " + query.getSqlLike()); 1221 query = null; 1222} catch (e) { 1223 console.log("simply calls should be ok :" + e); 1224} 1225``` 1226 1227 1228### equalTo<sup>8+</sup> 1229 1230equalTo(field: string, value: number|string|boolean): Query 1231 1232构造一个Query对象来查询具有指定字段的条目，其值等于指定的值。 1233 1234**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1235 1236**参数：** 1237 1238| 参数名 | 类型 | 必填 | 说明 | 1239| ----- | ------ | ---- | ----------------------- | 1240| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1241| value | number\|string\|boolean | 是 | 表示指定的值。| 1242 1243**返回值：** 1244 1245| 类型 | 说明 | 1246| ------ | ------- | 1247| [Query](#query8) |返回Query对象。| 1248 1249**示例：** 1250 1251```js 1252try { 1253 let query = new distributedData.Query(); 1254 query.equalTo("field", "value"); 1255 console.log("query is " + query.getSqlLike()); 1256 query = null; 1257} catch (e) { 1258 console.log("duplicated calls should be ok :" + e); 1259} 1260``` 1261 1262 1263### notEqualTo<sup>8+</sup> 1264 1265notEqualTo(field: string, value: number|string|boolean): Query 1266 1267构造一个Query对象以查询具有指定字段且值不等于指定值的条目。 1268 1269**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1270 1271**参数：** 1272 1273| 参数名 | 类型 | 必填 | 说明 | 1274| ----- | ------ | ---- | ----------------------- | 1275| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1276| value | number\|string\|boolean | 是 | 表示指定的值。| 1277 1278**返回值：** 1279 1280| 类型 | 说明 | 1281| ------ | ------- | 1282| [Query](#query8) |返回Query对象。| 1283 1284**示例：** 1285 1286```js 1287try { 1288 let query = new distributedData.Query(); 1289 query.notEqualTo("field", "value"); 1290 console.log("query is " + query.getSqlLike()); 1291 query = null; 1292} catch (e) { 1293 console.log("duplicated calls should be ok :" + e); 1294} 1295``` 1296 1297 1298### greaterThan<sup>8+</sup> 1299 1300greaterThan(field: string, value: number|string|boolean): Query 1301 1302构造一个Query对象以查询具有大于指定值的指定字段的条目。 1303 1304**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1305 1306**参数：** 1307 1308| 参数名 | 类型 | 必填 | 说明 | 1309| ----- | ------ | ---- | ----------------------- | 1310| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1311| value | number\|string\|boolean | 是 | 表示指定的值。| 1312 1313**返回值：** 1314 1315| 类型 | 说明 | 1316| ------ | ------- | 1317| [Query](#query8) |返回Query对象。| 1318 1319**示例：** 1320 1321```js 1322try { 1323 let query = new distributedData.Query(); 1324 query.greaterThan("field", "value"); 1325 console.log("query is " + query.getSqlLike()); 1326 query = null; 1327} catch (e) { 1328 console.log("duplicated calls should be ok :" + e); 1329} 1330``` 1331 1332 1333### lessThan<sup>8+</sup> 1334 1335lessThan(field: string, value: number|string): Query 1336 1337构造一个Query对象以查询具有小于指定值的指定字段的条目。 1338 1339**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1340 1341**参数：** 1342 1343| 参数名 | 类型 | 必填 | 说明 | 1344| ----- | ------ | ---- | ----------------------- | 1345| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1346| value | number\|string | 是 | 表示指定的值。| 1347 1348**返回值：** 1349 1350| 类型 | 说明 | 1351| ------ | ------- | 1352| [Query](#query8) |返回Query对象。| 1353 1354**示例：** 1355 1356```js 1357try { 1358 let query = new distributedData.Query(); 1359 query.lessThan("field", "value"); 1360 console.log("query is " + query.getSqlLike()); 1361 query = null; 1362} catch (e) { 1363 console.log("duplicated calls should be ok :" + e); 1364} 1365``` 1366 1367 1368### greaterThanOrEqualTo<sup>8+</sup> 1369 1370greaterThanOrEqualTo(field: string, value: number|string): Query 1371 1372构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。 1373 1374**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1375 1376**参数：** 1377 1378| 参数名 | 类型 | 必填 | 说明 | 1379| ----- | ------ | ---- | ----------------------- | 1380| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1381| value | number\|string | 是 | 表示指定的值。| 1382 1383**返回值：** 1384 1385| 类型 | 说明 | 1386| ------ | ------- | 1387| [Query](#query8) |返回Query对象。| 1388 1389**示例：** 1390 1391```js 1392try { 1393 let query = new distributedData.Query(); 1394 query.greaterThanOrEqualTo("field", "value"); 1395 console.log("query is " + query.getSqlLike()); 1396 query = null; 1397} catch (e) { 1398 console.log("duplicated calls should be ok :" + e); 1399} 1400``` 1401 1402 1403### lessThanOrEqualTo<sup>8+</sup> 1404 1405lessThanOrEqualTo(field: string, value: number|string): Query 1406 1407构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。 1408 1409**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1410 1411**参数：** 1412 1413| 参数名 | 类型 | 必填 | 说明 | 1414| ----- | ------ | ---- | ----------------------- | 1415| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1416| value | number\|string | 是 | 表示指定的值。| 1417 1418**返回值：** 1419 1420| 类型 | 说明 | 1421| ------ | ------- | 1422| [Query](#query8) |返回Query对象。| 1423 1424**示例：** 1425 1426```js 1427try { 1428 let query = new distributedData.Query(); 1429 query.lessThanOrEqualTo("field", "value"); 1430 console.log("query is " + query.getSqlLike()); 1431 query = null; 1432} catch (e) { 1433 console.log("duplicated calls should be ok :" + e); 1434} 1435``` 1436 1437 1438### isNull<sup>8+</sup> 1439 1440isNull(field: string): Query 1441 1442构造一个Query对象以查询具有值为null的指定字段的条目。 1443 1444**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1445 1446**参数：** 1447 1448| 参数名 | 类型 | 必填 | 说明 | 1449| ----- | ------ | ---- | ----------------------- | 1450| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1451 1452**返回值：** 1453 1454| 类型 | 说明 | 1455| ------ | ------- | 1456| [Query](#query8) |返回Query对象。| 1457 1458**示例：** 1459 1460```js 1461try { 1462 let query = new distributedData.Query(); 1463 query.isNull("field"); 1464 console.log("query is " + query.getSqlLike()); 1465 query = null; 1466} catch (e) { 1467 console.log("duplicated calls should be ok :" + e); 1468} 1469``` 1470 1471 1472### inNumber<sup>8+</sup> 1473 1474inNumber(field: string, valueList: number[]): Query 1475 1476构造一个Query对象以查询具有指定字段的条目，其值在指定的值列表中。 1477 1478 1479**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1480 1481**参数：** 1482 1483| 参数名 | 类型 | 必填 | 说明 | 1484| ----- | ------ | ---- | ----------------------- | 1485| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1486| valueList | number[] | 是 | 表示指定的值列表。| 1487 1488**返回值：** 1489 1490| 类型 | 说明 | 1491| ------ | ------- | 1492| [Query](#query8) |返回Query对象。| 1493 1494**示例：** 1495 1496```js 1497try { 1498 let query = new distributedData.Query(); 1499 query.inNumber("field", [0, 1]); 1500 console.log("query is " + query.getSqlLike()); 1501 query = null; 1502} catch (e) { 1503 console.log("duplicated calls should be ok :" + e); 1504} 1505``` 1506 1507 1508### inString<sup>8+</sup> 1509 1510inString(field: string, valueList: string[]): Query 1511 1512构造一个Query对象以查询具有指定字段的条目，其值在指定的字符串值列表中。 1513 1514**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1515 1516**参数：** 1517 1518| 参数名 | 类型 | 必填 | 说明 | 1519| ----- | ------ | ---- | ----------------------- | 1520| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1521| valueList | string[] | 是 | 表示指定的字符串值列表。| 1522 1523**返回值：** 1524 1525| 类型 | 说明 | 1526| ------ | ------- | 1527| [Query](#query8) |返回Query对象。| 1528 1529**示例：** 1530 1531```js 1532try { 1533 let query = new distributedData.Query(); 1534 query.inString("field", ['test1', 'test2']); 1535 console.log("query is " + query.getSqlLike()); 1536 query = null; 1537} catch (e) { 1538 console.log("duplicated calls should be ok :" + e); 1539} 1540``` 1541 1542 1543### notInNumber<sup>8+</sup> 1544 1545notInNumber(field: string, valueList: number[]): Query 1546 1547构造一个Query对象以查询具有指定字段的条目，该字段的值不在指定的值列表中。 1548 1549**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1550 1551**参数：** 1552 1553| 参数名 | 类型 | 必填 | 说明 | 1554| ----- | ------ | ---- | ----------------------- | 1555| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1556| valueList | number[] | 是 | 表示指定的值列表。| 1557 1558**返回值：** 1559 1560| 类型 | 说明 | 1561| ------ | ------- | 1562| [Query](#query8) |返回Query对象。| 1563 1564**示例：** 1565 1566```js 1567try { 1568 let query = new distributedData.Query(); 1569 query.notInNumber("field", [0, 1]); 1570 console.log("query is " + query.getSqlLike()); 1571 query = null; 1572} catch (e) { 1573 console.log("duplicated calls should be ok :" + e); 1574} 1575``` 1576 1577 1578### notInString<sup>8+</sup> 1579 1580notInString(field: string, valueList: string[]): Query 1581 1582构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。 1583 1584**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1585 1586**参数：** 1587 1588| 参数名 | 类型 | 必填 | 说明 | 1589| ----- | ------ | ---- | ----------------------- | 1590| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1591| valueList | string[] | 是 | 表示指定的字符串值列表。| 1592 1593**返回值：** 1594 1595| 类型 | 说明 | 1596| ------ | ------- | 1597| [Query](#query8) |返回Query对象。| 1598 1599**示例：** 1600 1601```js 1602try { 1603 let query = new distributedData.Query(); 1604 query.notInString("field", ['test1', 'test2']); 1605 console.log("query is " + query.getSqlLike()); 1606 query = null; 1607} catch (e) { 1608 console.log("duplicated calls should be ok :" + e); 1609} 1610``` 1611 1612 1613### like<sup>8+</sup> 1614 1615like(field: string, value: string): Query 1616 1617构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。 1618 1619**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1620 1621**参数：** 1622 1623| 参数名 | 类型 | 必填 | 说明 | 1624| ----- | ------ | ---- | ----------------------- | 1625| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1626| value | string | 是 | 表示指定的字符串值。| 1627 1628**返回值：** 1629 1630| 类型 | 说明 | 1631| ------ | ------- | 1632| [Query](#query8) |返回Query对象。| 1633 1634**示例：** 1635 1636```js 1637try { 1638 let query = new distributedData.Query(); 1639 query.like("field", "value"); 1640 console.log("query is " + query.getSqlLike()); 1641 query = null; 1642} catch (e) { 1643 console.log("duplicated calls should be ok :" + e); 1644} 1645``` 1646 1647 1648### unlike<sup>8+</sup> 1649 1650unlike(field: string, value: string): Query 1651 1652构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。 1653 1654**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1655 1656**参数：** 1657 1658| 参数名 | 类型 | 必填 | 说明 | 1659| ----- | ------ | ---- | ----------------------- | 1660| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1661| value | string | 是 | 表示指定的字符串值。| 1662 1663**返回值：** 1664 1665| 类型 | 说明 | 1666| ------ | ------- | 1667| [Query](#query8) |返回Query对象。| 1668 1669**示例：** 1670 1671```js 1672try { 1673 let query = new distributedData.Query(); 1674 query.unlike("field", "value"); 1675 console.log("query is " + query.getSqlLike()); 1676 query = null; 1677} catch (e) { 1678 console.log("duplicated calls should be ok :" + e); 1679} 1680``` 1681 1682 1683### and<sup>8+</sup> 1684 1685and(): Query 1686 1687构造一个带有与条件的查询对象。 1688 1689**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1690 1691**返回值：** 1692 1693| 类型 | 说明 | 1694| ------ | ------- | 1695| [Query](#query8) |返回查询对象。| 1696 1697**示例：** 1698 1699```js 1700try { 1701 let query = new distributedData.Query(); 1702 query.notEqualTo("field", "value1"); 1703 query.and(); 1704 query.notEqualTo("field", "value2"); 1705 console.log("query is " + query.getSqlLike()); 1706 query = null; 1707} catch (e) { 1708 console.log("duplicated calls should be ok :" + e); 1709} 1710``` 1711 1712 1713### or<sup>8+</sup> 1714 1715or(): Query 1716 1717构造一个带有或条件的Query对象。 1718 1719**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1720 1721**返回值：** 1722 1723| 类型 | 说明 | 1724| ------ | ------- | 1725| [Query](#query8) |返回查询对象。| 1726 1727**示例：** 1728 1729```js 1730try { 1731 let query = new distributedData.Query(); 1732 query.notEqualTo("field", "value1"); 1733 query.or(); 1734 query.notEqualTo("field", "value2"); 1735 console.log("query is " + query.getSqlLike()); 1736 query = null; 1737} catch (e) { 1738 console.log("duplicated calls should be ok :" + e); 1739} 1740``` 1741 1742 1743### orderByAsc<sup>8+</sup> 1744 1745orderByAsc(field: string): Query 1746 1747构造一个Query对象，将查询结果按升序排序。 1748 1749**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1750 1751**参数：** 1752 1753| 参数名 | 类型 | 必填 | 说明 | 1754| ----- | ------ | ---- | ----------------------- | 1755| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1756 1757**返回值：** 1758 1759| 类型 | 说明 | 1760| ------ | ------- | 1761| [Query](#query8) |返回Query对象。| 1762 1763**示例：** 1764 1765```js 1766try { 1767 let query = new distributedData.Query(); 1768 query.notEqualTo("field", "value"); 1769 query.orderByAsc("field"); 1770 console.log("query is " + query.getSqlLike()); 1771 query = null; 1772} catch (e) { 1773 console.log("duplicated calls should be ok :" + e); 1774} 1775``` 1776 1777 1778### orderByDesc<sup>8+</sup> 1779 1780orderByDesc(field: string): Query 1781 1782构造一个Query对象，将查询结果按降序排序。 1783 1784**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1785 1786**参数：** 1787 1788| 参数名 | 类型 | 必填 | 说明 | 1789| ----- | ------ | ---- | ----------------------- | 1790| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1791 1792**返回值：** 1793 1794| 类型 | 说明 | 1795| ------ | ------- | 1796| [Query](#query8) |返回Query对象。| 1797 1798**示例：** 1799 1800```js 1801try { 1802 let query = new distributedData.Query(); 1803 query.notEqualTo("field", "value"); 1804 query.orderByDesc("field"); 1805 console.log("query is " + query.getSqlLike()); 1806 query = null; 1807} catch (e) { 1808 console.log("duplicated calls should be ok :" + e); 1809} 1810``` 1811 1812 1813### limit<sup>8+</sup> 1814 1815limit(total: number, offset: number): Query 1816 1817构造一个Query对象来指定结果的数量和开始位置。 1818 1819**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1820 1821**参数：** 1822 1823| 参数名 | 类型 | 必填 | 说明 | 1824| ----- | ------ | ---- | ----------------------- | 1825| total | number | 是 |表示指定的结果数。 | 1826| offset | number | 是 |表示起始位置。 | 1827 1828**返回值：** 1829 1830| 类型 | 说明 | 1831| ------ | ------- | 1832| [Query](#query8) |返回Query对象。| 1833 1834**示例：** 1835 1836```js 1837let total = 10; 1838let offset = 1; 1839try { 1840 let query = new distributedData.Query(); 1841 query.notEqualTo("field", "value"); 1842 query.limit(total, offset); 1843 console.log("query is " + query.getSqlLike()); 1844 query = null; 1845} catch (e) { 1846 console.log("duplicated calls should be ok :" + e); 1847} 1848``` 1849 1850 1851### isNotNull<sup>8+</sup> 1852 1853isNotNull(field: string): Query 1854 1855构造一个Query对象以查询具有值不为null的指定字段的条目。 1856 1857**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1858 1859**参数：** 1860 1861| 参数名 | 类型 | 必填 | 说明 | 1862| ----- | ------ | ---- | ----------------------- | 1863| field | string | 是 |表示指定字段，不能包含' ^ '。 | 1864 1865**返回值：** 1866 1867| 类型 | 说明 | 1868| ------ | ------- | 1869| [Query](#query8) |返回Query对象。| 1870 1871**示例：** 1872 1873```js 1874try { 1875 let query = new distributedData.Query(); 1876 query.isNotNull("field"); 1877 console.log("query is " + query.getSqlLike()); 1878 query = null; 1879} catch (e) { 1880 console.log("duplicated calls should be ok :" + e); 1881} 1882``` 1883 1884 1885### beginGroup<sup>8+</sup> 1886 1887beginGroup(): Query 1888 1889创建一个带有左括号的查询条件组。 1890 1891**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1892 1893**返回值：** 1894 1895| 类型 | 说明 | 1896| ------ | ------- | 1897| [Query](#query8) |返回Query对象。| 1898 1899**示例：** 1900 1901```js 1902try { 1903 let query = new distributedData.Query(); 1904 query.beginGroup(); 1905 query.isNotNull("field"); 1906 query.endGroup(); 1907 console.log("query is " + query.getSqlLike()); 1908 query = null; 1909} catch (e) { 1910 console.log("duplicated calls should be ok :" + e); 1911} 1912``` 1913 1914 1915### endGroup<sup>8+</sup> 1916 1917endGroup(): Query 1918 1919创建一个带有右括号的查询条件组。 1920 1921**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1922 1923**返回值：** 1924 1925| 类型 | 说明 | 1926| ------ | ------- | 1927| [Query](#query8) |返回Query对象。| 1928 1929**示例：** 1930 1931```js 1932try { 1933 let query = new distributedData.Query(); 1934 query.beginGroup(); 1935 query.isNotNull("field"); 1936 query.endGroup(); 1937 console.log("query is " + query.getSqlLike()); 1938 query = null; 1939} catch (e) { 1940 console.log("duplicated calls should be ok :" + e); 1941} 1942``` 1943 1944 1945### prefixKey<sup>8+</sup> 1946 1947prefixKey(prefix: string): Query 1948 1949创建具有指定键前缀的查询条件。 1950 1951**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1952 1953**参数：** 1954 1955| 参数名 | 类型 | 必填 | 说明 | 1956| ----- | ------ | ---- | ----------------------- | 1957| prefix | string | 是 |表示指定的键前缀。 | 1958 1959**返回值：** 1960 1961| 类型 | 说明 | 1962| ------ | ------- | 1963| [Query](#query8) |返回Query对象。| 1964 1965**示例：** 1966 1967```js 1968try { 1969 let query = new distributedData.Query(); 1970 query.prefixKey("$.name"); 1971 query.prefixKey("0"); 1972 console.log("query is " + query.getSqlLike()); 1973 query = null; 1974} catch (e) { 1975 console.log("duplicated calls should be ok :" + e); 1976} 1977``` 1978 1979 1980### setSuggestIndex<sup>8+</sup> 1981 1982setSuggestIndex(index: string): Query 1983 1984设置一个指定的索引，将优先用于查询。 1985 1986**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1987 1988**参数：** 1989 1990| 参数名 | 类型 | 必填 | 说明 | 1991| ----- | ------ | ---- | ----------------------- | 1992| index | string | 是 |指示要设置的索引。 | 1993 1994**返回值：** 1995 1996| 类型 | 说明 | 1997| ------ | ------- | 1998| [Query](#query8) |返回Query对象。| 1999 2000**示例：** 2001 2002```js 2003try { 2004 let query = new distributedData.Query(); 2005 query.setSuggestIndex("$.name"); 2006 query.setSuggestIndex("0"); 2007 console.log("query is " + query.getSqlLike()); 2008 query = null; 2009} catch (e) { 2010 console.log("duplicated calls should be ok :" + e); 2011} 2012``` 2013 2014 2015### deviceId<sup>8+</sup> 2016 2017deviceId(deviceId:string):Query 2018 2019添加设备ID作为key的前缀。 2020> **说明：** 2021> 2022> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 2023> deviceId具体获取方式请参考[sync接口示例](#sync)。 2024 2025**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2026 2027**参数：** 2028 2029| 参数名 | 类型 | 必填 | 说明 | 2030| ----- | ------ | ---- | ----------------------- | 2031| deviceId | string | 是 |指示查询的设备ID。 | 2032 2033 2034**返回值：** 2035 2036| 类型 | 说明 | 2037| ------ | ------- | 2038| [Query](#query8) |返回Query对象。| 2039 2040**示例：** 2041 2042```js 2043try { 2044 let query = new distributedData.Query(); 2045 query.deviceId("deviceId"); 2046 console.log("query is " + query.getSqlLike()); 2047} catch (e) { 2048 console.log("should be ok on Method Chaining : " + e); 2049} 2050``` 2051 2052 2053### getSqlLike<sup>8+</sup> 2054 2055getSqlLike():string 2056 2057获取Query对象的查询语句。 2058 2059**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2060 2061**返回值：** 2062 2063| 类型 | 说明 | 2064| ------ | ------- | 2065| string |返回一个字段列中包含对应子串的结果。| 2066 2067**示例：** 2068 2069```js 2070try { 2071 let query = new distributedData.Query(); 2072 let sql1 = query.getSqlLike(); 2073 console.log("GetSqlLike sql=" + sql1); 2074} catch (e) { 2075 console.log("duplicated calls should be ok : " + e); 2076} 2077``` 2078 2079 2080## KVStore 2081 2082KVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。 2083 2084在调用KVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个KVStore实例。 2085 2086### put 2087 2088put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void 2089 2090添加指定类型键值对到数据库，使用callback异步回调。 2091 2092**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2093 2094**参数：** 2095 2096| 参数名 | 类型 | 必填 | 说明 | 2097| ----- | ------ | ---- | ----------------------- | 2098| key | string | 是 |要添加数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2099| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2100| callback | AsyncCallback<void> | 是 |回调函数。 | 2101 2102**示例：** 2103 2104```js 2105let kvStore; 2106const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2107const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2108try { 2109 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { 2110 if (err != undefined) { 2111 console.log("put err: " + JSON.stringify(err)); 2112 return; 2113 } 2114 console.log("put success"); 2115 }); 2116}catch (e) { 2117 console.log("An unexpected error occurred. Error:" + e); 2118} 2119``` 2120 2121### put 2122 2123put(key: string, value: Uint8Array | string | number | boolean): Promise<void> 2124 2125添加指定类型键值对到数据库，使用Promise异步回调。 2126 2127**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2128 2129**参数：** 2130 2131| 参数名 | 类型 | 必填 | 说明 | 2132| ----- | ------ | ---- | ----------------------- | 2133| key | string | 是 |要添加数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2134| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2135 2136**返回值：** 2137 2138| 类型 | 说明 | 2139| ------ | ------- | 2140| Promise<void> |无返回结果的Promise对象。| 2141 2142**示例：** 2143 2144```js 2145let kvStore; 2146const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2147const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2148try { 2149 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { 2150 console.log("put success: " + JSON.stringify(data)); 2151 }).catch((err) => { 2152 console.log("put err: " + JSON.stringify(err)); 2153 }); 2154}catch (e) { 2155 console.log("An unexpected error occurred. Error:" + e); 2156} 2157``` 2158 2159### delete 2160 2161delete(key: string, callback: AsyncCallback<void>): void 2162 2163从数据库中删除指定键值的数据，使用callback异步回调。 2164 2165**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2166 2167**参数：** 2168 2169| 参数名 | 类型 | 必填 | 说明 | 2170| ----- | ------ | ---- | ----------------------- | 2171| key | string | 是 |要删除数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2172| callback | AsyncCallback<void> | 是 |回调函数。 | 2173 2174**示例：** 2175 2176```js 2177let kvStore; 2178const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2179const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2180try { 2181 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { 2182 if (err != undefined) { 2183 console.log("put err: " + JSON.stringify(err)); 2184 return; 2185 } 2186 console.log("put success"); 2187 kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err,data) { 2188 if (err != undefined) { 2189 console.log("delete err: " + JSON.stringify(err)); 2190 return; 2191 } 2192 console.log("delete success"); 2193 }); 2194 }); 2195}catch (e) { 2196 console.log("An unexpected error occurred. Error:" + e); 2197} 2198``` 2199 2200### delete 2201 2202delete(key: string): Promise<void> 2203 2204从数据库中删除指定键值的数据，使用Promise异步回调。 2205 2206**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2207 2208**参数：** 2209 2210| 参数名 | 类型 | 必填 | 说明 | 2211| ----- | ------ | ---- | ----------------------- | 2212| key | string | 是 |要删除数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2213 2214**返回值：** 2215 2216| 类型 | 说明 | 2217| ------ | ------- | 2218| Promise<void> |无返回结果的Promise对象。| 2219 2220**示例：** 2221 2222```js 2223let kvStore; 2224const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2225const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2226try { 2227 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { 2228 console.log("put success: " + JSON.stringify(data)); 2229 kvStore.delete(KEY_TEST_STRING_ELEMENT).then((data) => { 2230 console.log("delete success"); 2231 }).catch((err) => { 2232 console.log("delete err: " + JSON.stringify(err)); 2233 }); 2234 }).catch((err) => { 2235 console.log("put err: " + JSON.stringify(err)); 2236 }); 2237}catch (e) { 2238 console.log("An unexpected error occurred. Error:" + e); 2239} 2240``` 2241 2242### on('dataChange') 2243 2244on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void 2245 2246订阅指定类型的数据变更通知。 2247 2248**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2249 2250**参数：** 2251 2252| 参数名 | 类型 | 必填 | 说明 | 2253| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | 2254| event | string | 是 | 订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 2255| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | 2256| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | 2257 2258**示例：** 2259 2260```js 2261let kvStore; 2262kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { 2263 console.log("dataChange callback call data: " + JSON.stringify(data)); 2264}); 2265``` 2266 2267### on('syncComplete') 2268 2269on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void 2270 2271订阅同步完成事件回调通知。 2272 2273**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2274 2275**参数：** 2276 2277| 参数名 | 类型 | 必填 | 说明 | 2278| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | 2279| event | string | 是 | 订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 2280| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | 2281 2282**示例：** 2283 2284```js 2285let kvStore; 2286kvStore.on('syncComplete', function (data) { 2287 console.log("callback call data: " + data); 2288}); 2289``` 2290 2291### off('dataChange')<sup>8+</sup> 2292 2293off(event:'dataChange', listener?: Callback<ChangeNotification>): void 2294 2295取消订阅数据变更通知。 2296 2297**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2298 2299**参数：** 2300 2301| 参数名 | 类型 | 必填 | 说明 | 2302| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | 2303| event | string | 是 | 取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 2304| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 2305 2306 2307 2308**示例：** 2309 2310```js 2311let kvStore; 2312class KvstoreModel { 2313 call(data) { 2314 console.log("dataChange: " + data); 2315 } 2316 subscribeDataChange() { 2317 if (kvStore != null) { 2318 kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 2319 } 2320 } 2321 unsubscribeDataChange() { 2322 if (kvStore != null) { 2323 kvStore.off('dataChange', this.call); 2324 } 2325 } 2326} 2327``` 2328 2329### off('syncComplete')<sup>8+</sup> 2330 2331off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void 2332 2333取消订阅同步完成事件回调通知。 2334 2335**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2336 2337**参数：** 2338 2339| 参数名 | 类型 | 必填 | 说明 | 2340| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | 2341| event | string | 是 | 取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 2342| syncCallback | Callback<Array<[string, number]>> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 2343 2344**示例：** 2345 2346```js 2347let kvStore; 2348class KvstoreModel { 2349 call(data) { 2350 console.log("syncComplete: " + data); 2351 } 2352 subscribeSyncComplete() { 2353 if (kvStore != null) { 2354 kvStore.on('syncComplete', this.call); 2355 } 2356 } 2357 unsubscribeSyncComplete() { 2358 if (kvStore != null) { 2359 kvStore.off('syncComplete', this.call); 2360 } 2361 } 2362} 2363``` 2364 2365### putBatch<sup>8+</sup> 2366 2367putBatch(entries: Entry[], callback: AsyncCallback<void>): void 2368 2369批量插入键值对到KVStore数据库中，使用callback异步回调。 2370 2371**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2372 2373**参数：** 2374 2375| 参数名 | 类型 | 必填 | 说明 | 2376| ----- | ------ | ---- | ----------------------- | 2377| entries |[Entry](#entry)[] | 是 |表示要批量插入的键值对。 | 2378| callback |AsyncCallback<void> |是 |回调函数。 | 2379 2380**示例：** 2381 2382```js 2383let kvStore; 2384try { 2385 let entries = []; 2386 for (var i = 0; i < 10; i++) { 2387 var key = 'batch_test_string_key'; 2388 var entry = { 2389 key : key + i, 2390 value : { 2391 type : distributedData.ValueType.STRING, 2392 value : 'batch_test_string_value' 2393 } 2394 } 2395 entries.push(entry); 2396 } 2397 console.log('entries: ' + JSON.stringify(entries)); 2398 kvStore.putBatch(entries, async function (err,data) { 2399 console.log('putBatch success'); 2400 kvStore.getEntries('batch_test_string_key', function (err,entries) { 2401 console.log('getEntries success'); 2402 console.log('entries.length: ' + entries.length); 2403 console.log('entries[0]: ' + JSON.stringify(entries[0])); 2404 }); 2405 }); 2406}catch(e) { 2407 console.log('PutBatch e ' + JSON.stringify(e)); 2408} 2409``` 2410 2411 2412### putBatch<sup>8+</sup> 2413 2414putBatch(entries: Entry[]): Promise<void> 2415 2416批量插入键值对到KVStore数据库中，使用Promise异步回调。 2417 2418**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2419 2420**参数：** 2421 2422| 参数名 | 类型 | 必填 | 说明 | 2423| ----- | ------ | ---- | ----------------------- | 2424| entries |[Entry](#entry)[] | 是 |表示要批量插入的键值对。 | 2425 2426**返回值：** 2427 2428| 类型 | 说明 | 2429| ------ | ------- | 2430| Promise<void> |无返回结果的Promise对象。| 2431 2432**示例：** 2433 2434```js 2435let kvStore; 2436try { 2437 let entries = []; 2438 for (var i = 0; i < 10; i++) { 2439 var key = 'batch_test_string_key'; 2440 var entry = { 2441 key : key + i, 2442 value : { 2443 type : distributedData.ValueType.STRING, 2444 value : 'batch_test_string_value' 2445 } 2446 } 2447 entries.push(entry); 2448 } 2449 console.log('entries: ' + JSON.stringify(entries)); 2450 kvStore.putBatch(entries).then(async (err) => { 2451 console.log('putBatch success'); 2452 kvStore.getEntries('batch_test_string_key').then((entries) => { 2453 console.log('getEntries success'); 2454 console.log('PutBatch ' + JSON.stringify(entries)); 2455 }).catch((err) => { 2456 console.log('getEntries fail ' + JSON.stringify(err)); 2457 }); 2458 }).catch((err) => { 2459 console.log('putBatch fail ' + JSON.stringify(err)); 2460 }); 2461}catch(e) { 2462 console.log('PutBatch e ' + JSON.stringify(e)); 2463} 2464``` 2465 2466### deleteBatch<sup>8+</sup> 2467 2468deleteBatch(keys: string[], callback: AsyncCallback<void>): void 2469 2470批量删除KVStore数据库中的键值对，使用callback异步回调。 2471 2472**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2473 2474**参数：** 2475 2476| 参数名 | 类型 | 必填 | 说明 | 2477| ----- | ------ | ---- | ----------------------- | 2478| keys |string[] | 是 |表示要批量删除的键值对。 | 2479| callback |AsyncCallback<void> | 是 |回调函数。 | 2480 2481**示例：** 2482 2483```js 2484let kvStore; 2485try { 2486 let entries = []; 2487 let keys = []; 2488 for (var i = 0; i < 5; i++) { 2489 var key = 'batch_test_string_key'; 2490 var entry = { 2491 key : key + i, 2492 value : { 2493 type : distributedData.ValueType.STRING, 2494 value : 'batch_test_string_value' 2495 } 2496 } 2497 entries.push(entry); 2498 keys.push(key + i); 2499 } 2500 console.log('entries: ' + JSON.stringify(entries)); 2501 kvStore.putBatch(entries, async function (err,data) { 2502 console.log('putBatch success'); 2503 kvStore.deleteBatch(keys, async function (err,data) { 2504 console.log('deleteBatch success'); 2505 }); 2506 }); 2507}catch(e) { 2508 console.log('DeleteBatch e ' + e); 2509} 2510``` 2511 2512 2513### deleteBatch<sup>8+</sup> 2514 2515deleteBatch(keys: string[]): Promise<void> 2516 2517批量删除KVStore数据库中的键值对，使用Promise异步回调。 2518 2519**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2520 2521**参数：** 2522 2523| 参数名 | 类型 | 必填 | 说明 | 2524| ----- | ------ | ---- | ----------------------- | 2525| keys |string[] | 是 |表示要批量删除的键值对。 | 2526 2527**返回值：** 2528 2529| 类型 | 说明 | 2530| ------ | ------- | 2531| Promise<void> |无返回结果的Promise对象。| 2532 2533**示例：** 2534 2535```js 2536let kvStore; 2537try { 2538 let entries = []; 2539 let keys = []; 2540 for (var i = 0; i < 5; i++) { 2541 var key = 'batch_test_string_key'; 2542 var entry = { 2543 key : key + i, 2544 value : { 2545 type : distributedData.ValueType.STRING, 2546 value : 'batch_test_string_value' 2547 } 2548 } 2549 entries.push(entry); 2550 keys.push(key + i); 2551 } 2552 console.log('entries: ' + JSON.stringify(entries)); 2553 kvStore.putBatch(entries).then(async (err) => { 2554 console.log('putBatch success'); 2555 kvStore.deleteBatch(keys).then((err) => { 2556 console.log('deleteBatch success'); 2557 }).catch((err) => { 2558 console.log('deleteBatch fail ' + JSON.stringify(err)); 2559 }); 2560 }).catch((err) => { 2561 console.log('putBatch fail ' + JSON.stringify(err)); 2562 }); 2563}catch(e) { 2564 console.log('DeleteBatch e ' + e); 2565} 2566``` 2567 2568 2569### startTransaction<sup>8+</sup> 2570 2571startTransaction(callback: AsyncCallback<void>): void 2572 2573启动KVStore数据库中的事务，使用callback异步回调。 2574 2575**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2576 2577**参数：** 2578 2579| 参数名 | 类型 | 必填 | 说明 | 2580| ----- | ------ | ---- | ----------------------- | 2581| callback |AsyncCallback<void> | 是 |回调函数。 | 2582 2583**示例：** 2584 2585```js 2586let kvStore; 2587function putBatchString(len, prefix) { 2588 let entries = []; 2589 for (var i = 0; i < len; i++) { 2590 var entry = { 2591 key : prefix + i, 2592 value : { 2593 type : distributedData.ValueType.STRING, 2594 value : 'batch_test_string_value' 2595 } 2596 } 2597 entries.push(entry); 2598 } 2599 return entries; 2600} 2601try { 2602 var count = 0; 2603 kvStore.on('dataChange', 0, function (data) { 2604 console.log('startTransaction 0' + data) 2605 count++; 2606 }); 2607 kvStore.startTransaction(async function (err,data) { 2608 console.log('startTransaction success'); 2609 let entries = putBatchString(10, 'batch_test_string_key'); 2610 console.log('entries: ' + JSON.stringify(entries)); 2611 kvStore.putBatch(entries, async function (err,data) { 2612 console.log('putBatch success'); 2613 }); 2614 }); 2615}catch(e) { 2616 console.log('startTransaction e ' + e); 2617} 2618``` 2619 2620 2621### startTransaction<sup>8+</sup> 2622 2623startTransaction(): Promise<void> 2624 2625启动KVStore数据库中的事务，使用Promise异步回调。 2626 2627**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2628 2629**返回值：** 2630 2631| 类型 | 说明 | 2632| ------ | ------- | 2633| Promise<void> |无返回结果的Promise对象。| 2634 2635**示例：** 2636 2637```js 2638let kvStore; 2639try { 2640 var count = 0; 2641 kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { 2642 console.log('startTransaction ' + JSON.stringify(data)); 2643 count++; 2644 }); 2645 kvStore.startTransaction().then(async (err) => { 2646 console.log('startTransaction success'); 2647 }).catch((err) => { 2648 console.log('startTransaction fail ' + JSON.stringify(err)); 2649 }); 2650}catch(e) { 2651 console.log('startTransaction e ' + e); 2652} 2653``` 2654 2655 2656### commit<sup>8+</sup> 2657 2658commit(callback: AsyncCallback<void>): void 2659 2660提交KVStore数据库中的事务，使用callback异步回调。 2661 2662**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2663 2664**参数：** 2665 2666| 参数名 | 类型 | 必填 | 说明 | 2667| ----- | ------ | ---- | ----------------------- | 2668| callback |AsyncCallback<void> | 是 |回调函数。 | 2669 2670**示例：** 2671 2672```js 2673let kvStore; 2674try { 2675 kvStore.commit(function (err,data) { 2676 if (err == undefined) { 2677 console.log('commit success'); 2678 } else { 2679 console.log('commit fail'); 2680 } 2681 }); 2682}catch(e) { 2683 console.log('Commit e ' + e); 2684} 2685``` 2686 2687 2688### commit<sup>8+</sup> 2689 2690commit(): Promise<void> 2691 2692提交KVStore数据库中的事务，使用Promise异步回调。 2693 2694**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2695 2696**返回值：** 2697 2698| 类型 | 说明 | 2699| ------ | ------- | 2700| Promise<void> |无返回结果的Promise对象。| 2701 2702**示例：** 2703 2704```js 2705let kvStore; 2706try { 2707 kvStore.commit().then(async (err) => { 2708 console.log('commit success'); 2709 }).catch((err) => { 2710 console.log('commit fail ' + JSON.stringify(err)); 2711 }); 2712}catch(e) { 2713 console.log('Commit e ' + e); 2714} 2715``` 2716 2717 2718### rollback<sup>8+</sup> 2719 2720rollback(callback: AsyncCallback<void>): void 2721 2722在KVStore数据库中回滚事务，使用callback异步回调。 2723 2724**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2725 2726**参数：** 2727 2728| 参数名 | 类型 | 必填 | 说明 | 2729| ----- | ------ | ---- | ----------------------- | 2730| callback |AsyncCallback<void> | 是 |回调函数。 | 2731 2732**示例：** 2733 2734```js 2735let kvStore; 2736try { 2737 kvStore.rollback(function (err,data) { 2738 if (err == undefined) { 2739 console.log('commit success'); 2740 } else { 2741 console.log('commit fail'); 2742 } 2743 }); 2744}catch(e) { 2745 console.log('Rollback e ' + e); 2746} 2747``` 2748 2749 2750### rollback<sup>8+</sup> 2751 2752rollback(): Promise<void> 2753 2754在KVStore数据库中回滚事务，使用Promise异步回调。 2755 2756**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2757 2758**返回值：** 2759 2760| 类型 | 说明 | 2761| ------ | ------- | 2762| Promise<void> |无返回结果的Promise对象。| 2763 2764**示例：** 2765 2766```js 2767let kvStore; 2768try { 2769 kvStore.rollback().then(async (err) => { 2770 console.log('rollback success'); 2771 }).catch((err) => { 2772 console.log('rollback fail ' + JSON.stringify(err)); 2773 }); 2774}catch(e) { 2775 console.log('Rollback e ' + e); 2776} 2777``` 2778 2779 2780### enableSync<sup>8+</sup> 2781 2782enableSync(enabled: boolean, callback: AsyncCallback<void>): void 2783 2784设定是否开启同步，使用callback异步回调。 2785 2786**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2787 2788**参数：** 2789 2790| 参数名 | 类型 | 必填 | 说明 | 2791| ----- | ------ | ---- | ----------------------- | 2792| enabled |boolean | 是 |设定是否开启同步，true表示开启同步，false表示不启用同步。 | 2793| callback |AsyncCallback<void> | 是 |回调函数。 | 2794 2795**示例：** 2796 2797```js 2798let kvStore; 2799try { 2800 kvStore.enableSync(true, function (err,data) { 2801 if (err == undefined) { 2802 console.log('enableSync success'); 2803 } else { 2804 console.log('enableSync fail'); 2805 } 2806 }); 2807}catch(e) { 2808 console.log('EnableSync e ' + e); 2809} 2810``` 2811 2812 2813### enableSync<sup>8+</sup> 2814 2815enableSync(enabled: boolean): Promise<void> 2816 2817设定是否开启同步，使用Promise异步回调。 2818 2819**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2820 2821**参数：** 2822 2823| 参数名 | 类型 | 必填 | 说明 | 2824| ----- | ------ | ---- | ----------------------- | 2825| enabled |boolean | 是 |设定是否开启同步，true表示开启同步，false表示不启用同步。 | 2826 2827**返回值：** 2828 2829| 类型 | 说明 | 2830| ------ | ------- | 2831| Promise<void> |无返回结果的Promise对象。| 2832 2833**示例：** 2834 2835```js 2836let kvStore; 2837try { 2838 kvStore.enableSync(true).then((err) => { 2839 console.log('enableSync success'); 2840 }).catch((err) => { 2841 console.log('enableSync fail ' + JSON.stringify(err)); 2842 }); 2843}catch(e) { 2844 console.log('EnableSync e ' + e); 2845} 2846``` 2847 2848 2849### setSyncRange<sup>8+</sup> 2850 2851setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void 2852 2853设置同步范围标签，使用callback异步回调。 2854 2855**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2856 2857**参数：** 2858 2859| 参数名 | 类型 | 必填 | 说明 | 2860| ----- | ------ | ---- | ----------------------- | 2861| localLabels |string[] | 是 |表示本地设备的同步标签。 | 2862| remoteSupportLabels |string[] | 是 |表示要同步数据的设备的同步标签。 | 2863| callback |AsyncCallback<void> | 是 |回调函数。 | 2864 2865**示例：** 2866 2867```js 2868let kvStore; 2869try { 2870 const localLabels = ['A', 'B']; 2871 const remoteSupportLabels = ['C', 'D']; 2872 kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err,data) { 2873 console.log('SetSyncRange put success'); 2874 }); 2875}catch(e) { 2876 console.log('SetSyncRange e ' + e); 2877} 2878``` 2879 2880 2881### setSyncRange<sup>8+</sup> 2882 2883setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void> 2884 2885设置同步范围标签，使用Promise异步回调。 2886 2887**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2888 2889**参数：** 2890 2891| 参数名 | 类型 | 必填 | 说明 | 2892| ----- | ------ | ---- | ----------------------- | 2893| localLabels |string[] | 是 |表示本地设备的同步标签。 | 2894| remoteSupportLabels |string[] | 是 |表示要同步数据的设备的同步标签。 | 2895 2896 2897**返回值：** 2898 2899| 类型 | 说明 | 2900| ------ | ------- | 2901| Promise<void> |无返回结果的Promise对象。| 2902 2903**示例：** 2904 2905```js 2906let kvStore; 2907try { 2908 const localLabels = ['A', 'B']; 2909 const remoteSupportLabels = ['C', 'D']; 2910 kvStore.setSyncRange(localLabels, remoteSupportLabels).then((err) => { 2911 console.log('setSyncRange success'); 2912 }).catch((err) => { 2913 console.log('delete fail ' + err); 2914 }); 2915}catch(e) { 2916 console.log('SetSyncRange e ' + e); 2917} 2918``` 2919 2920 2921## SubscribeType 2922 2923订阅类型枚举。 2924 2925**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2926 2927| 名称 | 值 | 说明 | 2928| ----- | ------ | ----------------------- | 2929| SUBSCRIBE_TYPE_LOCAL |0 |表示订阅本地数据变更。 | 2930| SUBSCRIBE_TYPE_REMOTE |1 |表示订阅远端数据变更。 | 2931| SUBSCRIBE_TYPE_ALL |2 |表示订阅远端和本地数据变更。 | 2932 2933## ChangeNotification 2934 2935数据变更时通知的对象，包括数据插入的数据、更新的数据、删除的数据和设备ID。 2936 2937**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2938 2939| 名称 | 类型 |必填 | 说明 | 2940| ----- | ------- | ------|------------------------ | 2941| insertEntries | [Entry](#entry)[] | 是 |数据添加记录。 | 2942| updateEntries | [Entry](#entry)[] | 是 |数据更新记录。 | 2943| deleteEntries | [Entry](#entry)[] | 是 |数据删除记录。 | 2944| deviceId | string | 是 |设备ID，此处为设备UUID。 | 2945 2946## Entry 2947 2948存储在数据库中的键值对。 2949 2950**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2951 2952| 名称 | 类型 |必填 | 说明 | 2953| ----- | ------- | ------|------------------------ | 2954| key | string | 是 |键值。 | 2955| value | [Value](#value) | 是 |值对象。 | 2956 2957 2958## Value 2959 2960存储在数据库中的值对象。 2961 2962**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2963 2964| 名称 | 类型 |必填 | 说明 | 2965| ----- | ------- | ------|------------------------ | 2966| type | [ValueType](#value) | 是 |值类型。 | 2967| value | Uint8Array \| string \| number \| boolean| 是 |值。 | 2968 2969## ValueType 2970 2971数据类型枚举。 2972 2973**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2974 2975| 名称 | 值 | 说明 | 2976| ----- | ------ | ----------------------- | 2977| STRING |0 |表示值类型为字符串。 | 2978| INTEGER |1 |表示值类型为整数。 | 2979| FLOAT |2 |表示值类型为浮点数。 | 2980| BYTE_ARRAY |3 |表示值类型为字节数组。 | 2981| BOOLEAN |4 |表示值类型为布尔值。 | 2982| DOUBLE |5 |表示值类型为双浮点数。 | 2983 2984## SingleKVStore 2985 2986单版本数据库，继承自[KVStore](#kvstore)数据库，提供查询数据和同步数据的方法。 2987 2988单版本数据库，不对数据所属设备进行区分，不同设备使用相同键写入数据会互相覆盖。比如，可以使用单版本数据库实现个人日历、联系人数据在不同设备间的数据同步。 2989 2990在调用SingleKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore实例。 2991 2992### get 2993 2994get(key: string, callback: AsyncCallback<Uint8Array | string | boolean | number>): void 2995 2996获取指定键的值，使用callback异步回调。 2997 2998**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2999 3000**参数：** 3001 3002| 参数名 | 类型 | 必填 | 说明 | 3003| ----- | ------ | ---- | ----------------------- | 3004| key |string | 是 |要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3005| callback |AsyncCallback<Uint8Array \| string \| boolean \| number> | 是 |回调函数。返回获取查询的值。 | 3006 3007**示例：** 3008 3009```js 3010let kvStore; 3011const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 3012const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 3013try { 3014 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { 3015 if (err != undefined) { 3016 console.log("put err: " + JSON.stringify(err)); 3017 return; 3018 } 3019 console.log("put success"); 3020 kvStore.get(KEY_TEST_STRING_ELEMENT, function (err,data) { 3021 console.log("get success data: " + data); 3022 }); 3023 }); 3024}catch (e) { 3025 console.log("An unexpected error occurred. Error:" + e); 3026} 3027``` 3028 3029 3030### get 3031 3032get(key: string): Promise<Uint8Array | string | boolean | number> 3033 3034获取指定键的值，使用Promise异步回调。 3035 3036**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3037 3038**参数：** 3039 3040| 参数名 | 类型 | 必填 | 说明 | 3041| ----- | ------ | ---- | ----------------------- | 3042| key |string | 是 |要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3043 3044 3045**返回值：** 3046 3047| 类型 | 说明 | 3048| ------ | ------- | 3049|Promise<Uint8Array \| string \| boolean \| number> |Promise对象。返回获取查询的值。| 3050 3051**示例：** 3052 3053```js 3054let kvStore; 3055const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 3056const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 3057try { 3058 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => { 3059 console.log("put success: " + JSON.stringify(data)); 3060 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { 3061 console.log("get success data: " + data); 3062 }).catch((err) => { 3063 console.log("get err: " + JSON.stringify(err)); 3064 }); 3065 }).catch((err) => { 3066 console.log("put err: " + JSON.stringify(err)); 3067 }); 3068}catch (e) { 3069 console.log("An unexpected error occurred. Error:" + e); 3070} 3071``` 3072 3073### getEntries<sup>8+</sup> 3074 3075getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void 3076 3077获取匹配指定键前缀的所有键值对，使用callback异步回调。 3078 3079**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3080 3081**参数：** 3082 3083| 参数名 | 类型 | 必填 | 说明 | 3084| ----- | ------ | ---- | ----------------------- | 3085| keyPrefix |string | 是 |表示要匹配的键前缀。 | 3086| callback |AsyncCallback<[Entry](#entry)[]> | 是 |回调函数。返回匹配指定前缀的键值对列表。 | 3087 3088**示例：** 3089 3090```js 3091let kvStore; 3092try { 3093 let entries = []; 3094 for (var i = 0; i < 10; i++) { 3095 var key = 'batch_test_number_key'; 3096 var entry = { 3097 key : key + i, 3098 value : { 3099 type : distributedData.ValueType.INTEGER, 3100 value : 222 3101 } 3102 } 3103 entries.push(entry); 3104 } 3105 kvStore.putBatch(entries, async function (err,data) { 3106 console.log('putBatch success'); 3107 kvStore.getEntries('batch_test_number_key', function (err,entries) { 3108 console.log('getEntries success'); 3109 console.log('entries.length: ' + entries.length); 3110 console.log('entries[0]: ' + JSON.stringify(entries[0])); 3111 }); 3112 }); 3113}catch(e) { 3114 console.log('PutBatch e ' + e); 3115} 3116``` 3117 3118 3119### getEntries<sup>8+</sup> 3120 3121getEntries(keyPrefix: string): Promise<Entry[]> 3122 3123获取匹配指定键前缀的所有键值对，使用Promise异步回调。 3124 3125**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3126 3127**参数：** 3128 3129| 参数名 | 类型 | 必填 | 说明 | 3130| ----- | ------ | ---- | ----------------------- | 3131| keyPrefix |string | 是 |表示要匹配的键前缀。 | 3132 3133**返回值：** 3134 3135| 类型 | 说明 | 3136| ------ | ------- | 3137|Promise<[Entry](#entry)[]> |Promise对象。返回匹配指定前缀的键值对列表。| 3138 3139**示例：** 3140 3141```js 3142let kvStore; 3143try { 3144 let entries = []; 3145 for (var i = 0; i < 10; i++) { 3146 var key = 'batch_test_string_key'; 3147 var entry = { 3148 key : key + i, 3149 value : { 3150 type : distributedData.ValueType.STRING, 3151 value : 'batch_test_string_value' 3152 } 3153 } 3154 entries.push(entry); 3155 } 3156 console.log('entries: ' + entries); 3157 kvStore.putBatch(entries).then(async (err) => { 3158 console.log('putBatch success'); 3159 kvStore.getEntries('batch_test_string_key').then((entries) => { 3160 console.log('getEntries success'); 3161 console.log('entries.length: ' + entries.length); 3162 console.log('entries[0]: ' + JSON.stringify(entries[0])); 3163 console.log('entries[0].value: ' + JSON.stringify(entries[0].value)); 3164 console.log('entries[0].value.value: ' + entries[0].value.value); 3165 }).catch((err) => { 3166 console.log('getEntries fail ' + JSON.stringify(err)); 3167 }); 3168 }).catch((err) => { 3169 console.log('putBatch fail ' + JSON.stringify(err)); 3170 }); 3171}catch(e) { 3172 console.log('PutBatch e ' + e); 3173} 3174``` 3175 3176 3177### getEntries<sup>8+</sup> 3178 3179getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 3180 3181获取与指定Query对象匹配的键值对列表，使用callback异步回调。 3182 3183**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3184 3185**参数：** 3186 3187| 参数名 | 类型 | 必填 | 说明 | 3188| ----- | ------ | ---- | ----------------------- | 3189| query |[Query](#query8) | 是 |表示要匹配的键前缀。 | 3190| callback |AsyncCallback<[Entry](#entry)[]> | 是 |回调函数。返回与指定Query对象匹配的键值对列表。 | 3191 3192**示例：** 3193 3194```js 3195let kvStore; 3196try { 3197 var arr = new Uint8Array([21,31]); 3198 let entries = []; 3199 for (var i = 0; i < 10; i++) { 3200 var key = 'batch_test_bool_key'; 3201 var entry = { 3202 key : key + i, 3203 value : { 3204 type : distributedData.ValueType.BYTE_ARRAY, 3205 value : arr 3206 } 3207 } 3208 entries.push(entry); 3209 } 3210 console.log('entries: ' + JSON.stringify(entries)); 3211 kvStore.putBatch(entries, async function (err,data) { 3212 console.log('putBatch success'); 3213 const query = new distributedData.Query(); 3214 query.prefixKey("batch_test"); 3215 kvStore.getEntries(query, function (err,entries) { 3216 console.log('getEntries success'); 3217 console.log('entries.length: ' + entries.length); 3218 console.log('entries[0]: ' + JSON.stringify(entries[0])); 3219 }); 3220 }); 3221 console.log('GetEntries success'); 3222}catch(e) { 3223 console.log('GetEntries e ' + e); 3224} 3225``` 3226 3227 3228### getEntries<sup>8+</sup> 3229 3230getEntries(query: Query): Promise<Entry[]> 3231 3232获取与指定Query对象匹配的键值对列表，使用Promise异步回调。 3233 3234**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3235 3236**参数：** 3237 3238| 参数名 | 类型 | 必填 | 说明 | 3239| ----- | ------ | ---- | ----------------------- | 3240| query |[Query](#query8) | 是 |表示查询对象。 | 3241 3242**返回值：** 3243 3244| 类型 | 说明 | 3245| ------ | ------- | 3246|Promise<[Entry](#entry)[]> |Promise对象。返回与指定Query对象匹配的键值对列表。| 3247 3248**示例：** 3249 3250```js 3251let kvStore; 3252try { 3253 var arr = new Uint8Array([21,31]); 3254 let entries = []; 3255 for (var i = 0; i < 10; i++) { 3256 var key = 'batch_test_bool_key'; 3257 var entry = { 3258 key : key + i, 3259 value : { 3260 type : distributedData.ValueType.BYTE_ARRAY, 3261 value : arr 3262 } 3263 } 3264 entries.push(entry); 3265 } 3266 console.log('entries: ' + JSON.stringify(entries)); 3267 kvStore.putBatch(entries).then(async (err) => { 3268 console.log('putBatch success'); 3269 const query = new distributedData.Query(); 3270 query.prefixKey("batch_test"); 3271 kvStore.getEntries(query).then((entries) => { 3272 console.log('getEntries success'); 3273 }).catch((err) => { 3274 console.log('getEntries fail ' + JSON.stringify(err)); 3275 }); 3276 }).catch((err) => { 3277 console.log('GetEntries putBatch fail ' + JSON.stringify(err)) 3278 }); 3279 console.log('GetEntries success'); 3280}catch(e) { 3281 console.log('GetEntries e ' + e); 3282} 3283``` 3284 3285 3286### getResultSet<sup>8+</sup> 3287 3288getResultSet(keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void 3289 3290从KvStore数据库中获取具有指定前缀的结果集，使用callback异步回调。 3291 3292**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3293 3294**参数：** 3295 3296| 参数名 | 类型 | 必填 | 说明 | 3297| ----- | ------ | ---- | ----------------------- | 3298| keyPrefix |string | 是 |表示要匹配的键前缀。 | 3299| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数。返回具有指定前缀的结果集。 | 3300 3301**示例：** 3302 3303```js 3304let kvStore; 3305try { 3306 let resultSet; 3307 let entries = []; 3308 for (var i = 0; i < 10; i++) { 3309 var key = 'batch_test_string_key'; 3310 var entry = { 3311 key : key + i, 3312 value : { 3313 type : distributedData.ValueType.STRING, 3314 value : 'batch_test_string_value' 3315 } 3316 } 3317 entries.push(entry); 3318 } 3319 kvStore.putBatch(entries, async function (err, data) { 3320 console.log('GetResultSet putBatch success'); 3321 kvStore.getResultSet('batch_test_string_key', async function (err, result) { 3322 console.log('GetResultSet getResultSet succeed.'); 3323 resultSet = result; 3324 kvStore.closeResultSet(resultSet, function (err, data) { 3325 console.log('GetResultSet closeResultSet success'); 3326 }) 3327 }); 3328 }); 3329}catch(e) { 3330 console.log('GetResultSet e ' + e); 3331} 3332``` 3333 3334 3335### getResultSet<sup>8+</sup> 3336 3337getResultSet(keyPrefix: string): Promise<KvStoreResultSet> 3338 3339从KVStore数据库中获取具有指定前缀的结果集，使用Promise异步回调。 3340 3341**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3342 3343**参数：** 3344 3345| 参数名 | 类型 | 必填 | 说明 | 3346| ----- | ------ | ---- | ----------------------- | 3347| keyPrefix |string | 是 |表示要匹配的键前缀。 | 3348 3349**返回值：** 3350 3351| 类型 | 说明 | 3352| ------ | ------- | 3353|Promise<[KvStoreResultSet](#kvstoreresultset8)> |Promise对象。返回具有指定前缀的结果集。| 3354 3355**示例：** 3356 3357```js 3358let kvStore; 3359try { 3360 let resultSet; 3361 let entries = []; 3362 for (var i = 0; i < 10; i++) { 3363 var key = 'batch_test_string_key'; 3364 var entry = { 3365 key : key + i, 3366 value : { 3367 type : distributedData.ValueType.STRING, 3368 value : 'batch_test_string_value' 3369 } 3370 } 3371 entries.push(entry); 3372 } 3373 kvStore.putBatch(entries).then(async (err) => { 3374 console.log('putBatch success'); 3375 }).catch((err) => { 3376 console.log('PutBatch putBatch fail ' + JSON.stringify(err)); 3377 }); 3378 kvStore.getResultSet('batch_test_string_key').then((result) => { 3379 console.log('GetResult getResultSet succeed.'); 3380 resultSet = result; 3381 }).catch((err) => { 3382 console.log('getResultSet failed: ' + JSON.stringify(err)); 3383 }); 3384 kvStore.closeResultSet(resultSet).then((err) => { 3385 console.log('GetResult closeResultSet success'); 3386 }).catch((err) => { 3387 console.log('closeResultSet fail ' + JSON.stringify(err)); 3388 }); 3389}catch(e) { 3390 console.log('GetResult e ' + e); 3391} 3392``` 3393 3394 3395### getResultSet<sup>8+</sup> 3396 3397getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void 3398 3399获取与指定Query对象匹配的KvStoreResultSet对象，使用callback异步回调。 3400 3401**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3402 3403**参数：** 3404 3405| 参数名 | 类型 | 必填 | 说明 | 3406| ----- | ------ | ---- | ----------------------- | 3407| query |Query | 是 |表示查询对象。 | 3408| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数，获取与指定Query对象匹配的KvStoreResultSet对象。 | 3409 3410**示例：** 3411 3412```js 3413let kvStore; 3414try { 3415 let resultSet; 3416 let entries = []; 3417 for (var i = 0; i < 10; i++) { 3418 var key = 'batch_test_string_key'; 3419 var entry = { 3420 key : key + i, 3421 value : { 3422 type : distributedData.ValueType.STRING, 3423 value : 'batch_test_string_value' 3424 } 3425 } 3426 entries.push(entry); 3427 } 3428 kvStore.putBatch(entries, async function (err, data) { 3429 console.log('putBatch success'); 3430 const query = new distributedData.Query(); 3431 query.prefixKey("batch_test"); 3432 kvStore.getResultSet(query, async function (err, result) { 3433 console.log('getResultSet succeed.'); 3434 resultSet = result; 3435 }); 3436 }); 3437} catch(e) { 3438 console.log('GetResultSet e ' + e); 3439} 3440``` 3441 3442 3443### getResultSet<sup>8+</sup> 3444 3445getResultSet(query: Query): Promise<KvStoreResultSet> 3446 3447获取与指定Query对象匹配的KvStoreResultSet对象，使用Promise异步回调。 3448 3449**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3450 3451**参数：** 3452 3453| 参数名 | 类型 | 必填 | 说明 | 3454| ----- | ------ | ---- | ----------------------- | 3455| query |[Query](#query8) | 是 |表示查询对象。 | 3456 3457**返回值：** 3458 3459| 类型 | 说明 | 3460| ------ | ------- | 3461|Promise<[KvStoreResultSet](#kvstoreresultset8)> |Promise对象。获取与指定Query对象匹配的KvStoreResultSet对象。| 3462 3463**示例：** 3464 3465```js 3466let kvStore; 3467try { 3468 let resultSet; 3469 let entries = []; 3470 for (var i = 0; i < 10; i++) { 3471 var key = 'batch_test_string_key'; 3472 var entry = { 3473 key : key + i, 3474 value : { 3475 type : distributedData.ValueType.STRING, 3476 value : 'batch_test_string_value' 3477 } 3478 } 3479 entries.push(entry); 3480 } 3481 kvStore.putBatch(entries).then(async (err) => { 3482 console.log('putBatch success'); 3483 }).catch((err) => { 3484 console.log('putBatch fail ' + JSON.stringify(err)); 3485 }); 3486 const query = new distributedData.Query(); 3487 query.prefixKey("batch_test"); 3488 kvStore.getResultSet(query).then((result) => { 3489 console.log(' getResultSet succeed.'); 3490 resultSet = result; 3491 }).catch((err) => { 3492 console.log('getResultSet failed: ' + JSON.stringify(err)); 3493 }); 3494}catch(e) { 3495 console.log('GetResultSet e ' + e); 3496} 3497``` 3498 3499### closeResultSet<sup>8+</sup> 3500 3501closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void 3502 3503关闭由[SingleKVStore.getResultSet](#getresultset8)返回的KvStoreResultSet对象，使用callback异步回调。 3504 3505**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3506 3507**参数：** 3508 3509| 参数名 | 类型 | 必填 | 说明 | 3510| ----- | ------ | ---- | ----------------------- | 3511| resultSet |[KvStoreResultSet](#kvstoreresultset8) | 是 |表示要关闭的KvStoreResultSet对象。 | 3512| callback |AsyncCallback<void> | 是 |回调函数。 | 3513 3514**示例：** 3515 3516```js 3517let kvStore; 3518try { 3519 let resultSet = null; 3520 kvStore.closeResultSet(resultSet, function (err, data) { 3521 if (err == undefined) { 3522 console.log('closeResultSet success'); 3523 } else { 3524 console.log('closeResultSet fail'); 3525 } 3526 }); 3527}catch(e) { 3528 console.log('CloseResultSet e ' + e); 3529} 3530``` 3531 3532 3533### closeResultSet<sup>8+</sup> 3534 3535closeResultSet(resultSet: KvStoreResultSet): Promise<void> 3536 3537关闭由[SingleKVStore.getResultSet](#getresultset8)返回的KvStoreResultSet对象，使用Promise异步回调。 3538 3539**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3540 3541**参数：** 3542 3543| 参数名 | 类型 | 必填 | 说明 | 3544| ----- | ------ | ---- | ----------------------- | 3545| resultSet |[KvStoreResultSet](#kvstoreresultset8) | 是 |表示要关闭的KvStoreResultSet对象。 | 3546 3547**返回值：** 3548 3549| 类型 | 说明 | 3550| ------ | ------- | 3551|Promise<void> |无返回结果的Promise对象。| 3552 3553**示例：** 3554 3555```js 3556let kvStore; 3557try { 3558 let resultSet = null; 3559 kvStore.closeResultSet(resultSet).then(() => { 3560 console.log('closeResultSet success'); 3561 }).catch((err) => { 3562 console.log('closeResultSet fail ' + JSON.stringify(err)); 3563 }); 3564}catch(e) { 3565 console.log('CloseResultSet e ' + e); 3566} 3567``` 3568 3569 3570### getResultSize<sup>8+</sup> 3571 3572getResultSize(query: Query, callback: AsyncCallback<number>): void 3573 3574获取与指定Query对象匹配的结果数，使用callback异步回调。 3575 3576**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3577 3578**参数：** 3579 3580| 参数名 | 类型 | 必填 | 说明 | 3581| ----- | ------ | ---- | ----------------------- | 3582| query |[Query](#query8) | 是 |表示查询对象。 | 3583| callback |AsyncCallback<number> | 是 |回调函数。返回与指定Query对象匹配的结果数。 | 3584 3585**示例：** 3586 3587```js 3588let kvStore; 3589try { 3590 let entries = []; 3591 for (var i = 0; i < 10; i++) { 3592 var key = 'batch_test_string_key'; 3593 var entry = { 3594 key : key + i, 3595 value : { 3596 type : distributedData.ValueType.STRING, 3597 value : 'batch_test_string_value' 3598 } 3599 } 3600 entries.push(entry); 3601 } 3602 kvStore.putBatch(entries, async function (err, data) { 3603 console.log('putBatch success'); 3604 const query = new distributedData.Query(); 3605 query.prefixKey("batch_test"); 3606 kvStore.getResultSize(query, async function (err, resultSize) { 3607 console.log('getResultSet succeed.'); 3608 }); 3609 }); 3610} catch(e) { 3611 console.log('GetResultSize e ' + e); 3612} 3613``` 3614 3615 3616### getResultSize<sup>8+</sup> 3617 3618getResultSize(query: Query): Promise<number> 3619 3620获取与指定Query对象匹配的结果数，使用Promise异步回调。 3621 3622**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3623 3624**参数：** 3625 3626| 参数名 | 类型 | 必填 | 说明 | 3627| ----- | ------ | ---- | ----------------------- | 3628| query |[Query](#query8) | 是 |表示查询对象。 | 3629 3630**返回值：** 3631 3632| 类型 | 说明 | 3633| ------ | ------- | 3634|Promise<number> |Promise对象。获取与指定Query对象匹配的结果数。| 3635 3636**示例：** 3637 3638```js 3639let kvStore; 3640try { 3641 let entries = []; 3642 for (var i = 0; i < 10; i++) { 3643 var key = 'batch_test_string_key'; 3644 var entry = { 3645 key : key + i, 3646 value : { 3647 type : distributedData.ValueType.STRING, 3648 value : 'batch_test_string_value' 3649 } 3650 } 3651 entries.push(entry); 3652 } 3653 kvStore.putBatch(entries).then(async (err) => { 3654 console.log('putBatch success'); 3655 }).catch((err) => { 3656 console.log('putBatch fail ' + JSON.stringify(err)); 3657 }); 3658 const query = new distributedData.Query(); 3659 query.prefixKey("batch_test"); 3660 kvStore.getResultSize(query).then((resultSize) => { 3661 console.log('getResultSet succeed.'); 3662 }).catch((err) => { 3663 console.log('getResultSet failed: ' + JSON.stringify(err)); 3664 }); 3665}catch(e) { 3666 console.log('GetResultSize e ' + e); 3667} 3668``` 3669 3670 3671### removeDeviceData<sup>8+</sup> 3672 3673removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void 3674 3675删除指定设备的数据，使用callback异步回调。 3676> **说明：** 3677> 3678> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 3679> deviceId具体获取方式请参考[sync接口示例](#sync)。 3680 3681**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3682 3683**参数：** 3684 3685| 参数名 | 类型 | 必填 | 说明 | 3686| ----- | ------ | ---- | ----------------------- | 3687| deviceId |string | 是 |表示要删除设备的名称。 | 3688| callback |AsyncCallback<void> | 是 |回调函数。 | 3689 3690**示例：** 3691 3692```js 3693let kvStore; 3694const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 3695const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 3696try { 3697 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) { 3698 console.log('put success'); 3699 const deviceid = 'no_exist_device_id'; 3700 kvStore.removeDeviceData(deviceid, async function (err,data) { 3701 if (err == undefined) { 3702 console.log('removeDeviceData success'); 3703 } else { 3704 console.log('removeDeviceData fail'); 3705 kvStore.get(KEY_TEST_STRING_ELEMENT, async function (err,data) { 3706 console.log('RemoveDeviceData get success'); 3707 }); 3708 } 3709 }); 3710 }); 3711}catch(e) { 3712 console.log('RemoveDeviceData e ' + e); 3713} 3714``` 3715 3716 3717### removeDeviceData<sup>8+</sup> 3718 3719removeDeviceData(deviceId: string): Promise<void> 3720 3721删除指定设备的数据，使用Promise异步回调。 3722> **说明：** 3723> 3724> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 3725> deviceId具体获取方式请参考[sync接口示例](#sync)。 3726 3727**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3728 3729**参数：** 3730 3731| 参数名 | 类型 | 必填 | 说明 | 3732| ----- | ------ | ---- | ----------------------- | 3733| deviceId |string | 是 |表示要删除设备的名称。 | 3734 3735**返回值：** 3736 3737| 类型 | 说明 | 3738| ------ | ------- | 3739|Promise<void> |无返回结果的Promise对象。| 3740 3741**示例：** 3742 3743```js 3744let kvStore; 3745const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 3746const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; 3747try { 3748 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => { 3749 console.log('removeDeviceData put success'); 3750 }).catch((err) => { 3751 console.log('put fail ' + JSON.stringify(err)); 3752 }); 3753 const deviceid = 'no_exist_device_id'; 3754 kvStore.removeDeviceData(deviceid).then((err) => { 3755 console.log('removeDeviceData success'); 3756 }).catch((err) => { 3757 console.log('removeDeviceData fail ' + JSON.stringify(err)); 3758 }); 3759 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => { 3760 console.log('get success data:' + data); 3761 }).catch((err) => { 3762 console.log('RemoveDeviceData get fail ' + JSON.stringify(err)); 3763 }); 3764}catch(e) { 3765 console.log('RemoveDeviceData e ' + e); 3766} 3767``` 3768 3769### sync 3770 3771 3772sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void 3773 3774在手动同步方式下，触发数据库同步。 3775> **说明：** 3776> 3777> 其中deviceIds为<!--RP2-->[DeviceInfo](../apis-distributedservice-kit/js-apis-device-manager-sys.md#deviceinfo)中的networkId, 通过调用[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP2End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 3778 3779**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 3780 3781**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3782 3783**参数：** 3784 3785| 参数名 | 类型 | 必填 | 说明 | 3786| --------- | --------------------- | ---- | ---------------------------------------------- | 3787| deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的networkId列表。 | 3788| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | 3789| delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒），默认为0。 | 3790 3791**示例：** 3792 3793```js 3794import deviceManager from '@ohos.distributedHardware.deviceManager'; 3795 3796let devManager; 3797let kvStore; 3798const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 3799const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 3800// create deviceManager 3801deviceManager.createDeviceManager('bundleName', (err, value) => { 3802 if (!err) { 3803 devManager = value; 3804 let deviceIds = []; 3805 if (devManager != null) { 3806 var devices = devManager.getTrustedDeviceListSync(); 3807 for (var i = 0; i < devices.length; i++) { 3808 deviceIds[i] = devices[i].networkId; 3809 } 3810 } 3811 try { 3812 kvStore.on('syncComplete', function (data) { 3813 console.log('Sync dataChange'); 3814 }); 3815 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) { 3816 if (err != undefined) { 3817 console.log("put err: " + JSON.stringify(err)); 3818 return; 3819 } 3820 console.log('Succeeded in putting data'); 3821 const mode = distributedData.SyncMode.PULL_ONLY; 3822 kvStore.sync(deviceIds, mode, 1000); 3823 }); 3824 } catch (e) { 3825 console.log('Sync e' + e); 3826 } 3827 } 3828}); 3829``` 3830 3831### on('dataChange')<sup>8+</sup> 3832 3833on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void 3834 3835订阅指定类型的数据变更通知。 3836 3837**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3838 3839**参数：** 3840 3841| 参数名 | 类型 | 必填 | 说明 | 3842| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | 3843| event | string | 是 | 订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 3844| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | 3845| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | 3846 3847**示例：** 3848 3849```js 3850let kvStore; 3851kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { 3852 console.log("dataChange callback call data: " + JSON.stringify(data)); 3853}); 3854``` 3855 3856### on('syncComplete')<sup>8+</sup> 3857 3858on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void 3859 3860订阅同步完成事件回调通知。 3861 3862**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3863 3864**参数：** 3865 3866| 参数名 | 类型 | 必填 | 说明 | 3867| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | 3868| event | string | 是 | 订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 3869| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | 3870 3871**示例：** 3872 3873```js 3874let kvStore; 3875const KEY_TEST_FLOAT_ELEMENT = 'key_test_float'; 3876const VALUE_TEST_FLOAT_ELEMENT = 321.12; 3877try { 3878 kvStore.on('syncComplete', function (data) { 3879 console.log('syncComplete ' + data) 3880 }); 3881 kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => { 3882 console.log('syncComplete put success'); 3883 }).catch((error) => { 3884 console.log('syncComplete put fail ' + error); 3885 }); 3886}catch(e) { 3887 console.log('syncComplete put e ' + e); 3888} 3889``` 3890 3891### off('dataChange')<sup>8+</sup> 3892 3893off(event:'dataChange', listener?: Callback<ChangeNotification>): void 3894 3895取消订阅数据变更通知。 3896 3897**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3898 3899**参数：** 3900 3901| 参数名 | 类型 | 必填 | 说明 | 3902| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | 3903| event | string | 是 | 取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 3904| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 3905 3906**示例：** 3907 3908```js 3909let kvStore; 3910class KvstoreModel { 3911 call(data) { 3912 console.log("dataChange: " + data); 3913 } 3914 subscribeDataChange() { 3915 if (kvStore != null) { 3916 kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 3917 } 3918 } 3919 unsubscribeDataChange() { 3920 if (kvStore != null) { 3921 kvStore.off('dataChange', this.call); 3922 } 3923 } 3924} 3925``` 3926 3927### off('syncComplete')<sup>8+</sup> 3928 3929off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void 3930 3931取消订阅同步完成事件回调通知。 3932 3933**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3934 3935**参数：** 3936 3937| 参数名 | 类型 | 必填 | 说明 | 3938| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | 3939| event | string | 是 | 取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 3940| syncCallback | Callback<Array<[string, number]>> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 3941 3942**示例：** 3943 3944```js 3945let kvStore; 3946class KvstoreModel { 3947 call(data) { 3948 console.log("syncComplete: " + data); 3949 } 3950 subscribeSyncComplete() { 3951 if (kvStore != null) { 3952 kvStore.on('syncComplete', this.call); 3953 } 3954 } 3955 unsubscribeSyncComplete() { 3956 if (kvStore != null) { 3957 kvStore.off('syncComplete', this.call); 3958 } 3959 } 3960} 3961``` 3962 3963### setSyncParam<sup>8+</sup> 3964 3965setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void 3966 3967设置数据库同步允许的默认延迟，使用callback异步回调。 3968 3969**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3970 3971**参数：** 3972 3973| 参数名 | 类型 | 必填 | 说明 | 3974| ----- | ------ | ---- | ----------------------- | 3975| defaultAllowedDelayMs |number | 是 |表示数据库同步允许的默认延迟，以毫秒为单位。 | 3976| callback |AsyncCallback<void> | 是 |回调函数。 | 3977 3978**示例：** 3979 3980```js 3981let kvStore; 3982try { 3983 const defaultAllowedDelayMs = 500; 3984 kvStore.setSyncParam(defaultAllowedDelayMs, function (err,data) { 3985 console.log('SetSyncParam put success'); 3986 }); 3987}catch(e) { 3988 console.log('testSingleKvStoreSetSyncParam e ' + e); 3989} 3990``` 3991 3992 3993### setSyncParam<sup>8+</sup> 3994 3995setSyncParam(defaultAllowedDelayMs: number): Promise<void> 3996 3997设置数据库同步允许的默认延迟，使用Promise异步回调。 3998 3999**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4000 4001**参数：** 4002 4003| 参数名 | 类型 | 必填 | 说明 | 4004| ----- | ------ | ---- | ----------------------- | 4005| defaultAllowedDelayMs |number | 是 |表示数据库同步允许的默认延迟，以毫秒为单位。 | 4006 4007 4008**返回值：** 4009 4010| 类型 | 说明 | 4011| ------ | ------- | 4012|Promise<void> |无返回结果的Promise对象。| 4013 4014**示例：** 4015 4016```js 4017let kvStore; 4018try { 4019 const defaultAllowedDelayMs = 500; 4020 kvStore.setSyncParam(defaultAllowedDelayMs).then((err) => { 4021 console.log('SetSyncParam put success'); 4022 }).catch((err) => { 4023 console.log('SetSyncParam put fail ' + JSON.stringify(err)); 4024 }); 4025}catch(e) { 4026 console.log('SetSyncParam e ' + e); 4027} 4028``` 4029 4030 4031### getSecurityLevel<sup>8+</sup> 4032 4033getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void 4034 4035获取数据库的安全级别，使用callback异步回调。 4036 4037**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4038 4039**参数：** 4040 4041| 参数名 | 类型 | 必填 | 说明 | 4042| ----- | ------ | ---- | ----------------------- | 4043| callback |AsyncCallback<[SecurityLevel](#securitylevel)> | 是 |回调函数。返回数据库的安全级别。 | 4044 4045**示例：** 4046 4047```js 4048let kvStore; 4049try { 4050 kvStore.getSecurityLevel(function (err,data) { 4051 console.log('getSecurityLevel success'); 4052 }); 4053}catch(e) { 4054 console.log('GetSecurityLevel e ' + e); 4055} 4056``` 4057 4058 4059### getSecurityLevel<sup>8+</sup> 4060 4061getSecurityLevel(): Promise<SecurityLevel> 4062 4063获取数据库的安全级别，使用Promise异步回调。 4064 4065**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4066 4067**返回值：** 4068 4069| 类型 | 说明 | 4070| ------ | ------- | 4071|Promise<[SecurityLevel](#securitylevel)> |Promise对象。返回数据库的安全级别。| 4072 4073**示例：** 4074 4075```js 4076let kvStore; 4077try { 4078 kvStore.getSecurityLevel().then((data) => { 4079 console.log(' getSecurityLevel success'); 4080 }).catch((err) => { 4081 console.log('getSecurityLevel fail ' + JSON.stringify(err)); 4082 }); 4083}catch(e) { 4084 console.log('GetSecurityLevel e ' + e); 4085} 4086``` 4087 4088 4089## DeviceKVStore<sup>8+</sup> 4090 4091设备协同数据库，继承自KVStore，提供查询数据和同步数据的方法。 4092 4093设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。 4094 4095比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。 4096 4097在调用DeviceKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个DeviceKVStore实例。 4098 4099### get<sup>8+</sup> 4100 4101get(deviceId: string, key: string, callback: AsyncCallback<boolean|string|number|Uint8Array>): void 4102 4103获取与指定设备ID和key匹配的string值，使用callback异步回调。 4104> **说明：** 4105> 4106> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4107> deviceId具体获取方式请参考[sync接口示例](#sync)。 4108 4109**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4110 4111**参数：** 4112 4113| 参数名 | 类型 | 必填 | 说明 | 4114| ----- | ------ | ---- | ----------------------- | 4115| deviceId |string | 是 |标识要查询其数据的设备。 | 4116| key |string | 是 |表示要查询key值的键。 | 4117| callback |AsyncCallback<boolean\|string\|number\|Uint8Array> | 是 |回调函数，返回匹配给定条件的字符串值。 | 4118 4119**示例：** 4120 4121```js 4122let kvStore; 4123const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 4124const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 4125try{ 4126 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) { 4127 console.log('put success'); 4128 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err,data) { 4129 console.log('get success'); 4130 }); 4131 }) 4132}catch(e) { 4133 console.log('get e' + e); 4134} 4135``` 4136 4137 4138### get<sup>8+</sup> 4139 4140get(deviceId: string, key: string): Promise<boolean|string|number|Uint8Array> 4141 4142获取与指定设备ID和key匹配的string值，使用Promise异步回调。 4143> **说明：** 4144> 4145> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4146> deviceId具体获取方式请参考[sync接口示例](#sync)。 4147 4148**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4149 4150**参数：** 4151 4152| 参数名 | 类型 | 必填 | 说明 | 4153| ----- | ------ | ---- | ----------------------- | 4154| deviceId |string | 是 |标识要查询其数据的设备。 | 4155| key |string | 是 |表示要查询key值的键。 | 4156 4157**返回值：** 4158 4159| 类型 | 说明 | 4160| ------ | ------- | 4161|Promise<boolean\|string\|number\|Uint8Array> |Promise对象。返回匹配给定条件的字符串值。| 4162 4163**示例：** 4164 4165```js 4166let kvStore; 4167const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 4168const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 4169try { 4170 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async (data) => { 4171 console.log(' put success'); 4172 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => { 4173 console.log('get success'); 4174 }).catch((err) => { 4175 console.log('get fail ' + JSON.stringify(err)); 4176 }); 4177 }).catch((error) => { 4178 console.log('put error' + error); 4179 }); 4180} catch (e) { 4181 console.log('Get e ' + e); 4182} 4183``` 4184 4185 4186### getEntries<sup>8+</sup> 4187 4188getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void 4189 4190获取与指定设备ID和key前缀匹配的所有键值对，使用callback异步回调。 4191> **说明：** 4192> 4193> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4194> deviceId具体获取方式请参考[sync接口示例](#sync)。 4195 4196**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4197 4198**参数：** 4199 4200| 参数名 | 类型 | 必填 | 说明 | 4201| ----- | ------ | ---- | ----------------------- | 4202| deviceId |string | 是 |标识要查询其数据的设备。 | 4203| keyPrefix |string | 是 |表示要匹配的键前缀。 | 4204| callback |AsyncCallback<[Entry](#entry)[]> | 是 |回调函数，返回满足给定条件的所有键值对的列表。 | 4205 4206**示例：** 4207 4208```js 4209let kvStore; 4210try { 4211 let entries = []; 4212 for (var i = 0; i < 10; i++) { 4213 var key = 'batch_test_string_key'; 4214 var entry = { 4215 key : key + i, 4216 value : { 4217 type : distributedData.ValueType.STRING, 4218 value : 'batch_test_string_value' 4219 } 4220 } 4221 entries.push(entry); 4222 } 4223 console.log('entries: ' + entries); 4224 kvStore.putBatch(entries, async function (err,data) { 4225 console.log('putBatch success'); 4226 kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err,entries) { 4227 console.log('getEntries success'); 4228 console.log('entries.length: ' + entries.length); 4229 console.log('entries[0]: ' + JSON.stringify(entries[0])); 4230 }); 4231 }); 4232}catch(e) { 4233 console.log('PutBatch e ' + e); 4234} 4235``` 4236 4237 4238### getEntries<sup>8+</sup> 4239 4240getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]> 4241 4242获取与指定设备ID和key前缀匹配的所有键值对，使用Promise异步回调。 4243> **说明：** 4244> 4245> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4246> deviceId具体获取方式请参考[sync接口示例](#sync)。 4247 4248**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4249 4250**参数：** 4251 4252| 参数名 | 类型 | 必填 | 说明 | 4253| ----- | ------ | ---- | ----------------------- | 4254| deviceId |string | 是 |标识要查询其数据的设备。 | 4255| keyPrefix |string | 是 |表示要匹配的键前缀。 | 4256 4257**返回值：** 4258 4259| 类型 | 说明 | 4260| ------ | ------- | 4261|Promise<[Entry](#entry)[]> |Promise对象。返回匹配给定条件的所有键值对的列表。| 4262 4263**示例：** 4264 4265```js 4266let kvStore; 4267try { 4268 let entries = []; 4269 for (var i = 0; i < 10; i++) { 4270 var key = 'batch_test_string_key'; 4271 var entry = { 4272 key : key + i, 4273 value : { 4274 type : distributedData.ValueType.STRING, 4275 value : 'batch_test_string_value' 4276 } 4277 } 4278 entries.push(entry); 4279 } 4280 console.log('entries: ' + entries); 4281 kvStore.putBatch(entries).then(async (err) => { 4282 console.log('putBatch success'); 4283 kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => { 4284 console.log('getEntries success'); 4285 console.log('entries.length: ' + entries.length); 4286 console.log('entries[0]: ' + JSON.stringify(entries[0])); 4287 console.log('entries[0].value: ' + JSON.stringify(entries[0].value)); 4288 console.log('entries[0].value.value: ' + entries[0].value.value); 4289 }).catch((err) => { 4290 console.log('getEntries fail ' + JSON.stringify(err)); 4291 }); 4292 }).catch((err) => { 4293 console.log('putBatch fail ' + JSON.stringify(err)); 4294 }); 4295}catch(e) { 4296 console.log('PutBatch e ' + e); 4297} 4298``` 4299 4300 4301### getEntries<sup>8+</sup> 4302 4303getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 4304 4305获取与指定Query对象匹配的键值对列表，使用callback异步回调。 4306 4307**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4308 4309**参数：** 4310 4311| 参数名 | 类型 | 必填 | 说明 | 4312| ----- | ------ | ---- | ----------------------- | 4313| query |[Query](#query8) | 是 |表示查询对象。 | 4314| callback |AsyncCallback<[Entry](#entry)[]> | 是 |回调函数，返回与指定Query对象匹配的键值对列表。 | 4315 4316**示例：** 4317 4318```js 4319let kvStore; 4320try { 4321 var arr = new Uint8Array([21,31]); 4322 let entries = []; 4323 for (var i = 0; i < 10; i++) { 4324 var key = 'batch_test_bool_key'; 4325 var entry = { 4326 key : key + i, 4327 value : { 4328 type : distributedData.ValueType.BYTE_ARRAY, 4329 value : arr 4330 } 4331 } 4332 entries.push(entry); 4333 } 4334 console.log('entries: ' + JSON.stringify(entries)); 4335 kvStore.putBatch(entries, async function (err,data) { 4336 console.log('putBatch success'); 4337 const query = new distributedData.Query(); 4338 query.prefixKey("batch_test"); 4339 query.deviceId('localDeviceId'); 4340 kvStore.getEntries(query, function (err,entries) { 4341 console.log('getEntries success'); 4342 console.log('entries.length: ' + entries.length); 4343 console.log('entries[0]: ' + JSON.stringify(entries[0])); 4344 }); 4345 }); 4346 console.log('GetEntries success'); 4347}catch(e) { 4348 console.log('GetEntries e ' + e); 4349} 4350``` 4351 4352 4353### getEntries<sup>8+</sup> 4354 4355getEntries(query: Query): Promise<Entry[]> 4356 4357获取与指定Query对象匹配的键值对列表，使用Promise异步回调。 4358 4359**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4360 4361**参数：** 4362 4363| 参数名 | 类型 | 必填 | 说明 | 4364| ----- | ------ | ---- | ----------------------- | 4365| query |[Query](#query8) | 是 |表示查询对象。 | 4366 4367**返回值：** 4368 4369| 类型 | 说明 | 4370| ------ | ------- | 4371|Promise<[Entry](#entry)[]> |Promise对象。返回与指定Query对象匹配的键值对列表。| 4372 4373**示例：** 4374 4375```js 4376let kvStore; 4377try { 4378 var arr = new Uint8Array([21,31]); 4379 let entries = []; 4380 for (var i = 0; i < 10; i++) { 4381 var key = 'batch_test_bool_key'; 4382 var entry = { 4383 key : key + i, 4384 value : { 4385 type : distributedData.ValueType.BYTE_ARRAY, 4386 value : arr 4387 } 4388 } 4389 entries.push(entry); 4390 } 4391 console.log('entries: ' + JSON.stringify(entries)); 4392 kvStore.putBatch(entries).then(async (err) => { 4393 console.log('putBatch success'); 4394 const query = new distributedData.Query(); 4395 query.prefixKey("batch_test"); 4396 kvStore.getEntries(query).then((entries) => { 4397 console.log('getEntries success'); 4398 }).catch((err) => { 4399 console.log('getEntries fail ' + JSON.stringify(err)); 4400 }); 4401 }).catch((err) => { 4402 console.log('GetEntries putBatch fail ' + JSON.stringify(err)) 4403 }); 4404 console.log('GetEntries success'); 4405}catch(e) { 4406 console.log('GetEntries e ' + e); 4407} 4408``` 4409 4410 4411### getEntries<sup>8+</sup> 4412 4413getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void 4414 4415获取与指定设备ID和Query对象匹配的键值对列表，使用callback异步回调。 4416> **说明：** 4417> 4418> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4419> deviceId具体获取方式请参考[sync接口示例](#sync)。 4420 4421**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4422 4423**参数：** 4424 4425| 参数名 | 类型 | 必填 | 说明 | 4426| ----- | ------ | ---- | ----------------------- | 4427| deviceId |string | 是 |键值对所属的设备ID。 | 4428| query |[Query](#query8) | 是 |表示查询对象。 | 4429| callback |AsyncCallback<[Entry](#entry)[]> | 是 |回调函数。返回与指定设备ID和Query对象匹配的键值对列表。 | 4430 4431**示例：** 4432 4433```js 4434let kvStore; 4435try { 4436 var arr = new Uint8Array([21,31]); 4437 let entries = []; 4438 for (var i = 0; i < 10; i++) { 4439 var key = 'batch_test_bool_key'; 4440 var entry = { 4441 key : key + i, 4442 value : { 4443 type : distributedData.ValueType.BYTE_ARRAY, 4444 value : arr 4445 } 4446 } 4447 entries.push(entry); 4448 } 4449 console.log('entries: ' + JSON.stringify(entries)); 4450 kvStore.putBatch(entries, async function (err,data) { 4451 console.log('putBatch success'); 4452 var query = new distributedData.Query(); 4453 query.deviceId('localDeviceId'); 4454 query.prefixKey("batch_test"); 4455 kvStore.getEntries('localDeviceId', query, function (err,entries) { 4456 console.log('getEntries success'); 4457 console.log('entries.length: ' + entries.length); 4458 console.log('entries[0]: ' + JSON.stringify(entries[0])); 4459 }) 4460 }); 4461 console.log('GetEntries success'); 4462}catch(e) { 4463 console.log('GetEntries e ' + e); 4464} 4465``` 4466 4467 4468### getEntries<sup>8+</sup> 4469 4470getEntries(deviceId: string, query: Query): Promise<Entry[]> 4471 4472获取与指定设备ID和Query对象匹配的键值对列表，使用Promise异步回调。 4473> **说明：** 4474> 4475> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4476> deviceId具体获取方式请参考[sync接口示例](#sync)。 4477 4478**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4479 4480**参数：** 4481 4482| 参数名 | 类型 | 必填 | 说明 | 4483| ----- | ------ | ---- | ----------------------- | 4484| deviceId |string | 是 |键值对所属的设备ID。 | 4485| query |[Query](#query8) | 是 |表示查询对象。 | 4486 4487**返回值：** 4488 4489| 类型 | 说明 | 4490| ------ | ------- | 4491|Promise<[Entry](#entry)[]> |Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。| 4492 4493**示例：** 4494 4495```js 4496let kvStore; 4497try { 4498 var arr = new Uint8Array([21,31]); 4499 let entries = []; 4500 for (var i = 0; i < 10; i++) { 4501 var key = 'batch_test_bool_key'; 4502 var entry = { 4503 key : key + i, 4504 value : { 4505 type : distributedData.ValueType.BYTE_ARRAY, 4506 value : arr 4507 } 4508 } 4509 entries.push(entry); 4510 } 4511 console.log('entries: ' + JSON.stringify(entries)); 4512 kvStore.putBatch(entries).then(async (err) => { 4513 console.log('putBatch success'); 4514 var query = new distributedData.Query(); 4515 query.deviceId('localDeviceId'); 4516 query.prefixKey("batch_test"); 4517 kvStore.getEntries('localDeviceId', query).then((entries) => { 4518 console.log('getEntries success'); 4519 }).catch((err) => { 4520 console.log('getEntries fail ' + JSON.stringify(err)); 4521 }); 4522 }).catch((err) => { 4523 console.log('putBatch fail ' + JSON.stringify(err)); 4524 }); 4525 console.log('GetEntries success'); 4526}catch(e) { 4527 console.log('GetEntries e ' + e); 4528} 4529``` 4530 4531 4532### getResultSet<sup>8+</sup> 4533 4534getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void 4535 4536获取与指定设备ID和key前缀匹配的KvStoreResultSet对象，使用callback异步回调。 4537> **说明：** 4538> 4539> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4540> deviceId具体获取方式请参考[sync接口示例](#sync)。 4541 4542**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4543 4544**参数：** 4545 4546| 参数名 | 类型 | 必填 | 说明 | 4547| ----- | ------ | ---- | ----------------------- | 4548| deviceId |string | 是 |标识要查询其数据的设备。 | 4549| keyPrefix |string | 是 |表示要匹配的键前缀。 | 4550| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数。返回与指定设备ID和key前缀匹配的KvStoreResultSet对象。 | 4551 4552**示例：** 4553 4554```js 4555let kvStore; 4556try { 4557 let resultSet; 4558 kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) { 4559 console.log('getResultSet succeed.'); 4560 resultSet = result; 4561 kvStore.closeResultSet(resultSet, function (err, data) { 4562 console.log('closeResultSet success'); 4563 }) 4564 }); 4565}catch(e) { 4566 console.log('GetResultSet e ' + e); 4567} 4568``` 4569 4570 4571### getResultSet<sup>8+</sup> 4572 4573getResultSet(deviceId: string, keyPrefix: string): Promise<KvStoreResultSet> 4574 4575获取与指定设备ID和key前缀匹配的KvStoreResultSet对象，使用Promise异步回调。 4576> **说明：** 4577> 4578> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4579> deviceId具体获取方式请参考[sync接口示例](#sync)。 4580 4581**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4582 4583**参数：** 4584 4585| 参数名 | 类型 | 必填 | 说明 | 4586| ----- | ------ | ---- | ----------------------- | 4587| deviceId |string | 是 |标识要查询其数据的设备。 | 4588| keyPrefix |string | 是 |表示要匹配的键前缀。 | 4589 4590**返回值：** 4591 4592| 类型 | 说明 | 4593| ------ | ------- | 4594|Promise<[KvStoreResultSet](#kvstoreresultset8)> |Promise对象。返回与指定设备ID和key前缀匹配的KvStoreResultSet对象。| 4595 4596**示例：** 4597 4598```js 4599let kvStore; 4600try { 4601 let resultSet; 4602 kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => { 4603 console.log('getResultSet succeed.'); 4604 resultSet = result; 4605 }).catch((err) => { 4606 console.log('getResultSet failed: ' + JSON.stringify(err)); 4607 }); 4608 kvStore.closeResultSet(resultSet).then((err) => { 4609 console.log('closeResultSet success'); 4610 }).catch((err) => { 4611 console.log('closeResultSet fail ' + JSON.stringify(err)); 4612 }); 4613}catch(e) { 4614 console.log('GetResultSet e ' + e); 4615} 4616``` 4617 4618 4619### getResultSet<sup>8+</sup> 4620 4621getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void 4622 4623获取与指定Query对象匹配的KvStoreResultSet对象，使用callback异步回调。 4624 4625**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4626 4627**参数：** 4628 4629| 参数名 | 类型 | 必填 | 说明 | 4630| ----- | ------ | ---- | ----------------------- | 4631| query |[Query](#query8) | 是 |表示查询对象。 | 4632| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数，返回与指定Query对象匹配的KvStoreResultSet对象。 | 4633 4634**示例：** 4635 4636```js 4637let kvStore; 4638try { 4639 let resultSet; 4640 let entries = []; 4641 for (var i = 0; i < 10; i++) { 4642 var key = 'batch_test_string_key'; 4643 var entry = { 4644 key : key + i, 4645 value : { 4646 type : distributedData.ValueType.STRING, 4647 value : 'batch_test_string_value' 4648 } 4649 } 4650 entries.push(entry); 4651 } 4652 kvStore.putBatch(entries, async function (err, data) { 4653 console.log('putBatch success'); 4654 const query = new distributedData.Query(); 4655 query.prefixKey("batch_test"); 4656 query.deviceId('localDeviceId'); 4657 kvStore.getResultSet(query, async function (err, result) { 4658 console.log('getResultSet succeed.'); 4659 resultSet = result; 4660 kvStore.closeResultSet(resultSet, function (err, data) { 4661 console.log('closeResultSet success'); 4662 }) 4663 }); 4664 }); 4665} catch(e) { 4666 console.log('GetResultSet e ' + e); 4667} 4668``` 4669 4670 4671### getResultSet<sup>8+</sup> 4672 4673getResultSet(query: Query): Promise<KvStoreResultSet> 4674 4675获取与指定Query对象匹配的KvStoreResultSet对象，使用Promise异步回调。 4676 4677**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4678 4679**参数：** 4680 4681| 参数名 | 类型 | 必填 | 说明 | 4682| ----- | ------ | ---- | ----------------------- | 4683| query |[Query](#query8) | 是 |表示查询对象。 | 4684 4685**返回值：** 4686 4687| 类型 | 说明 | 4688| ------ | ------- | 4689|Promise<[KvStoreResultSet](#kvstoreresultset8)> |Promise对象。返回与指定Query对象匹配的KvStoreResultSet对象。| 4690 4691**示例：** 4692 4693```js 4694let kvStore; 4695try { 4696 let resultSet; 4697 let entries = []; 4698 for (var i = 0; i < 10; i++) { 4699 var key = 'batch_test_string_key'; 4700 var entry = { 4701 key : key + i, 4702 value : { 4703 type : distributedData.ValueType.STRING, 4704 value : 'batch_test_string_value' 4705 } 4706 } 4707 entries.push(entry); 4708 } 4709 kvStore.putBatch(entries).then(async (err) => { 4710 console.log('putBatch success'); 4711 }).catch((err) => { 4712 console.log('putBatch fail ' + err); 4713 }); 4714 const query = new distributedData.Query(); 4715 query.deviceId('localDeviceId'); 4716 query.prefixKey("batch_test"); 4717 console.log("GetResultSet " + query.getSqlLike()); 4718 kvStore.getResultSet(query).then((result) => { 4719 console.log('getResultSet succeed.'); 4720 resultSet = result; 4721 }).catch((err) => { 4722 console.log('getResultSet failed: ' + JSON.stringify(err)); 4723 }); 4724 kvStore.closeResultSet(resultSet).then((err) => { 4725 console.log('closeResultSet success'); 4726 }).catch((err) => { 4727 console.log('closeResultSet fail ' + JSON.stringify(err)); 4728 }); 4729}catch(e) { 4730 console.log('GetResultSet e ' + e); 4731} 4732``` 4733 4734 4735### getResultSet<sup>8+</sup> 4736 4737getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KvStoreResultSet>): void 4738 4739获取与指定设备ID和Query对象匹配的KvStoreResultSet对象，使用callback异步回调。 4740> **说明：** 4741> 4742> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4743> deviceId具体获取方式请参考[sync接口示例](#sync)。 4744 4745**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4746 4747**参数：** 4748 4749| 参数名 | 类型 | 必填 | 说明 | 4750| ----- | ------ | ---- | ----------------------- | 4751| deviceId |string | 是 |KvStoreResultSet对象所属的设备ID。 | 4752| query |[Query](#query8) | 是 |表示查询对象。 | 4753| callback |AsyncCallback<[KvStoreResultSet](#kvstoreresultset8)> | 是 |回调函数。返回与指定设备ID和Query对象匹配的KvStoreResultSet对象。 | 4754 4755**示例：** 4756 4757```js 4758let kvStore; 4759try { 4760 let resultSet; 4761 let entries = []; 4762 for (var i = 0; i < 10; i++) { 4763 var key = 'batch_test_string_key'; 4764 var entry = { 4765 key : key + i, 4766 value : { 4767 type : distributedData.ValueType.STRING, 4768 value : 'batch_test_string_value' 4769 } 4770 } 4771 entries.push(entry); 4772 } 4773 kvStore.putBatch(entries, async function (err, data) { 4774 console.log('putBatch success'); 4775 const query = new distributedData.Query(); 4776 query.prefixKey("batch_test"); 4777 kvStore.getResultSet('localDeviceId', query, async function (err, result) { 4778 console.log('getResultSet succeed.'); 4779 resultSet = result; 4780 kvStore.closeResultSet(resultSet, function (err, data) { 4781 console.log('closeResultSet success'); 4782 }) 4783 }); 4784 }); 4785} catch(e) { 4786 console.log('GetResultSet e ' + e); 4787} 4788``` 4789 4790 4791### getResultSet<sup>8+</sup> 4792 4793getResultSet(deviceId: string, query: Query): Promise<KvStoreResultSet> 4794 4795获取与指定设备ID和Query对象匹配的KvStoreResultSet对象，使用Promise异步回调。 4796> **说明：** 4797> 4798> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 4799> deviceId具体获取方式请参考[sync接口示例](#sync)。 4800 4801**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4802 4803**参数：** 4804 4805| 参数名 | 类型 | 必填 | 说明 | 4806| ----- | ------ | ---- | ----------------------- | 4807| deviceId |string | 是 |KvStoreResultSet对象所属的设备ID。 | 4808| query |[Query](#query8) | 是 |表示查询对象。 | 4809 4810**返回值：** 4811 4812| 类型 | 说明 | 4813| ------ | ------- | 4814|Promise<[KvStoreResultSet](#kvstoreresultset8)> |Promise对象。返回与指定设备ID和Query对象匹配的KvStoreResultSet对象。| 4815 4816**示例：** 4817 4818```js 4819let kvStore; 4820try { 4821 let resultSet; 4822 let entries = []; 4823 for (var i = 0; i < 10; i++) { 4824 var key = 'batch_test_string_key'; 4825 var entry = { 4826 key : key + i, 4827 value : { 4828 type : distributedData.ValueType.STRING, 4829 value : 'batch_test_string_value' 4830 } 4831 } 4832 entries.push(entry); 4833 } 4834 kvStore.putBatch(entries).then(async (err) => { 4835 console.log('GetResultSet putBatch success'); 4836 }).catch((err) => { 4837 console.log('PutBatch putBatch fail ' + JSON.stringify(err)); 4838 }); 4839 const query = new distributedData.Query(); 4840 query.prefixKey("batch_test"); 4841 kvStore.getResultSet('localDeviceId', query).then((result) => { 4842 console.log('GetResultSet getResultSet succeed.'); 4843 resultSet = result; 4844 }).catch((err) => { 4845 console.log('GetResultSet getResultSet failed: ' + JSON.stringify(err)); 4846 }); 4847 query.deviceId('localDeviceId'); 4848 console.log("GetResultSet " + query.getSqlLike()); 4849 kvStore.closeResultSet(resultSet).then((err) => { 4850 console.log('GetResultSet closeResultSet success'); 4851 }).catch((err) => { 4852 console.log('GetResultSet closeResultSet fail ' + JSON.stringify(err)); 4853 }); 4854 4855}catch(e) { 4856 console.log('GetResultSet e ' + e); 4857} 4858``` 4859 4860 4861### closeResultSet<sup>8+</sup> 4862 4863closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void 4864 4865关闭由[DeviceKVStore.getResultSet](#getresultset8-4)返回的KvStoreResultSet对象，使用callback异步回调。 4866 4867**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4868 4869**参数：** 4870 4871| 参数名 | 类型 | 必填 | 说明 | 4872| ----- | ------ | ---- | ----------------------- | 4873| resultSet |[KvStoreResultSet](#kvstoreresultset8) | 是 |指示要关闭的KvStoreResultSet对象。 | 4874| callback |AsyncCallback<void> | 是 |回调函数。 | 4875 4876**示例：** 4877 4878```js 4879let kvStore; 4880try { 4881 console.log('CloseResultSet success'); 4882 let resultSet = null; 4883 kvStore.closeResultSet(resultSet, function (err, data) { 4884 if (err == undefined) { 4885 console.log('closeResultSet success'); 4886 } else { 4887 console.log('closeResultSet fail'); 4888 } 4889 }); 4890}catch(e) { 4891 console.log('CloseResultSet e ' + e); 4892} 4893``` 4894 4895 4896### closeResultSet<sup>8+</sup> 4897 4898closeResultSet(resultSet: KvStoreResultSet): Promise<void> 4899 4900关闭由[DeviceKVStore.getResultSet](#getresultset8-4)返回的KvStoreResultSet对象，使用Promise异步回调。 4901 4902**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4903 4904**参数：** 4905 4906| 参数名 | 类型 | 必填 | 说明 | 4907| ----- | ------ | ---- | ----------------------- | 4908| resultSet |[KvStoreResultSet](#kvstoreresultset8) | 是 |指示要关闭的KvStoreResultSet对象。 | 4909 4910**返回值：** 4911 4912| 类型 | 说明 | 4913| ------ | ------- | 4914|Promise<void> |无返回结果的Promise对象。| 4915 4916**示例：** 4917 4918```js 4919let kvStore; 4920try { 4921 console.log('CloseResultSet success'); 4922 let resultSet = null; 4923 kvStore.closeResultSet(resultSet).then(() => { 4924 console.log('closeResultSet success'); 4925 }).catch((err) => { 4926 console.log('closeResultSet fail ' + JSON.stringify(err)); 4927 }); 4928}catch(e) { 4929 console.log('CloseResultSet e ' + e); 4930} 4931``` 4932 4933 4934### getResultSize<sup>8+</sup> 4935 4936getResultSize(query: Query, callback: AsyncCallback<number>): void 4937 4938获取与指定Query对象匹配的结果数，使用callback异步回调。 4939 4940**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4941 4942**参数：** 4943 4944| 参数名 | 类型 | 必填 | 说明 | 4945| ----- | ------ | ---- | ----------------------- | 4946| query |[Query](#query8) | 是 |表示查询对象。 | 4947| callback |AsyncCallback<number> | 是 |回调函数，返回与指定Query对象匹配的结果数。 | 4948 4949**示例：** 4950 4951```js 4952let kvStore; 4953try { 4954 let entries = []; 4955 for (var i = 0; i < 10; i++) { 4956 var key = 'batch_test_string_key'; 4957 var entry = { 4958 key : key + i, 4959 value : { 4960 type : distributedData.ValueType.STRING, 4961 value : 'batch_test_string_value' 4962 } 4963 } 4964 entries.push(entry); 4965 } 4966 kvStore.putBatch(entries, async function (err, data) { 4967 console.log('putBatch success'); 4968 const query = new distributedData.Query(); 4969 query.prefixKey("batch_test"); 4970 query.deviceId('localDeviceId'); 4971 kvStore.getResultSize(query, async function (err, resultSize) { 4972 console.log('getResultSet succeed.'); 4973 }); 4974 }); 4975} catch(e) { 4976 console.log('GetResultSize e ' + e); 4977} 4978``` 4979 4980 4981### getResultSize<sup>8+</sup> 4982 4983getResultSize(query: Query): Promise<number> 4984 4985获取与指定Query对象匹配的结果数，使用Promise异步回调。 4986 4987**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 4988 4989**参数：** 4990 4991| 参数名 | 类型 | 必填 | 说明 | 4992| ----- | ------ | ---- | ----------------------- | 4993| query |[Query](#query8) | 是 |表示查询对象。 | 4994 4995**返回值：** 4996 4997| 类型 | 说明 | 4998| ------ | ------- | 4999|Promise<number> |Promise对象。返回与指定Query对象匹配的结果数。| 5000 5001**示例：** 5002 5003```js 5004let kvStore; 5005try { 5006 let entries = []; 5007 for (var i = 0; i < 10; i++) { 5008 var key = 'batch_test_string_key'; 5009 var entry = { 5010 key : key + i, 5011 value : { 5012 type : distributedData.ValueType.STRING, 5013 value : 'batch_test_string_value' 5014 } 5015 } 5016 entries.push(entry); 5017 } 5018 kvStore.putBatch(entries).then(async (err) => { 5019 console.log('putBatch success'); 5020 }).catch((err) => { 5021 console.log('putBatch fail ' + JSON.stringify(err)); 5022 }); 5023 const query = new distributedData.Query(); 5024 query.prefixKey("batch_test"); 5025 query.deviceId('localDeviceId'); 5026 kvStore.getResultSize(query).then((resultSize) => { 5027 console.log('getResultSet succeed.'); 5028 }).catch((err) => { 5029 console.log('getResultSet failed: ' + JSON.stringify(err)); 5030 }); 5031}catch(e) { 5032 console.log('GetResultSize e ' + e); 5033} 5034``` 5035 5036 5037### getResultSize<sup>8+</sup> 5038 5039getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; 5040 5041获取与指定设备ID和Query对象匹配的结果数，使用callback异步回调。 5042> **说明：** 5043> 5044> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 5045> deviceId具体获取方式请参考[sync接口示例](#sync)。 5046 5047**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5048 5049**参数：** 5050 5051| 参数名 | 类型 | 必填 | 说明 | 5052| ----- | ------ | ---- | ----------------------- | 5053| deviceId |string | 是 |KvStoreResultSet对象所属的设备ID。 | 5054| query |[Query](#query8) | 是 |表示查询对象。 | 5055| callback |AsyncCallback<number> | 是 |回调函数。返回与指定设备ID和Query对象匹配的结果数。 | 5056 5057**示例：** 5058 5059```js 5060let kvStore; 5061try { 5062 let entries = []; 5063 for (var i = 0; i < 10; i++) { 5064 var key = 'batch_test_string_key'; 5065 var entry = { 5066 key : key + i, 5067 value : { 5068 type : distributedData.ValueType.STRING, 5069 value : 'batch_test_string_value' 5070 } 5071 } 5072 entries.push(entry); 5073 } 5074 kvStore.putBatch(entries, async function (err, data) { 5075 console.log('putBatch success'); 5076 const query = new distributedData.Query(); 5077 query.prefixKey("batch_test"); 5078 kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) { 5079 console.log('getResultSet succeed.'); 5080 }); 5081 }); 5082} catch(e) { 5083 console.log('GetResultSize e ' + e); 5084} 5085``` 5086 5087 5088### getResultSize<sup>8+</sup> 5089 5090getResultSize(deviceId: string, query: Query): Promise<number> 5091 5092获取与指定设备ID和Query对象匹配的结果数，使用Promise异步回调。 5093> **说明：** 5094> 5095> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 5096> deviceId具体获取方式请参考[sync接口示例](#sync)。 5097 5098**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5099 5100**参数：** 5101 5102| 参数名 | 类型 | 必填 | 说明 | 5103| ----- | ------ | ---- | ----------------------- | 5104| deviceId |string | 是 |KvStoreResultSet对象所属的设备ID。 | 5105| query |[Query](#query8) | 是 |表示查询对象。 | 5106 5107**返回值：** 5108 5109| 类型 | 说明 | 5110| ------ | ------- | 5111|Promise<number> |Promise对象。返回与指定设备ID和Query对象匹配的结果数。| 5112 5113**示例：** 5114 5115```js 5116let kvStore; 5117try { 5118 let entries = []; 5119 for (var i = 0; i < 10; i++) { 5120 var key = 'batch_test_string_key'; 5121 var entry = { 5122 key : key + i, 5123 value : { 5124 type : distributedData.ValueType.STRING, 5125 value : 'batch_test_string_value' 5126 } 5127 } 5128 entries.push(entry); 5129 } 5130 kvStore.putBatch(entries).then(async (err) => { 5131 console.log('putBatch success'); 5132 }).catch((err) => { 5133 console.log('putBatch fail ' + JSON.stringify(err)); 5134 }); 5135 var query = new distributedData.Query(); 5136 query.prefixKey("batch_test"); 5137 kvStore.getResultSize('localDeviceId', query).then((resultSize) => { 5138 console.log('getResultSet succeed.'); 5139 }).catch((err) => { 5140 console.log('getResultSet failed: ' + JSON.stringify(err)); 5141 }); 5142}catch(e) { 5143 console.log('GetResultSize e ' + e); 5144} 5145``` 5146 5147 5148### removeDeviceData<sup>8+</sup> 5149 5150removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void 5151 5152从当前数据库中删除指定设备的数据，使用callback异步回调。 5153> **说明：** 5154> 5155> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 5156> deviceId具体获取方式请参考[sync接口示例](#sync)。 5157 5158**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5159 5160**参数：** 5161 5162| 参数名 | 类型 | 必填 | 说明 | 5163| ----- | ------ | ---- | ----------------------- | 5164| deviceId |string | 是 |标识要删除其数据的设备。 | 5165| callback |AsyncCallback<void> | 是 |回调函数。 | 5166 5167**示例：** 5168 5169```js 5170let kvStore; 5171const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 5172const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; 5173try { 5174 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) { 5175 console.log('RemoveDeviceData put success'); 5176 const deviceid = 'no_exist_device_id'; 5177 kvStore.removeDeviceData(deviceid, async function (err,data) { 5178 if (err == undefined) { 5179 console.log('removeDeviceData success'); 5180 } else { 5181 console.log('removeDeviceData fail'); 5182 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, async function (err,data) { 5183 console.log('RemoveDeviceData get success'); 5184 }); 5185 } 5186 }); 5187 }); 5188}catch(e) { 5189 console.log('RemoveDeviceData e ' + e); 5190} 5191``` 5192 5193 5194### removeDeviceData<sup>8+</sup> 5195 5196removeDeviceData(deviceId: string): Promise<void> 5197 5198从当前数据库中删除指定设备的数据，使用Promise异步回调。 5199> **说明：** 5200> 5201> 其中deviceId通过调用<!--RP1-->[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP1End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 5202> deviceId具体获取方式请参考[sync接口示例](#sync)。 5203 5204**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5205 5206**参数：** 5207 5208| 参数名 | 类型 | 必填 | 说明 | 5209| ----- | ------ | ---- | ----------------------- | 5210| deviceId |string | 是 |标识要删除其数据的设备。 | 5211 5212**返回值：** 5213 5214| 类型 | 说明 | 5215| ------ | ------- | 5216|Promise<void> |无返回结果的Promise对象。| 5217 5218**示例：** 5219 5220```js 5221let kvStore; 5222const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 5223const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; 5224try { 5225 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => { 5226 console.log('RemoveDeviceData put success'); 5227 }).catch((err) => { 5228 console.log('RemoveDeviceData put fail ' + JSON.stringify(err)); 5229 }); 5230 const deviceid = 'no_exist_device_id'; 5231 kvStore.removeDeviceData(deviceid).then((err) => { 5232 console.log('removeDeviceData success'); 5233 }).catch((err) => { 5234 console.log('removeDeviceData fail ' + JSON.stringify(err)); 5235 }); 5236 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => { 5237 console.log('RemoveDeviceData get success data:' + data); 5238 }).catch((err) => { 5239 console.log('RemoveDeviceData get fail ' + JSON.stringify(err)); 5240 }); 5241}catch(e) { 5242 console.log('RemoveDeviceData e ' + e); 5243} 5244``` 5245 5246 5247### sync<sup>8+</sup> 5248 5249sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void 5250 5251在手动同步方式下，触发数据库同步。 5252 5253> **说明：** 5254> 5255> 其中deviceIds为<!--RP2-->[DeviceInfo](../apis-distributedservice-kit/js-apis-device-manager-sys.md#deviceinfo)中的networkId, 通过调用[deviceManager.getTrustedDeviceListSync](../apis-distributedservice-kit/js-apis-device-manager-sys.md#gettrusteddevicelistsync)方法得到。<!--RP2End-->deviceManager模块的接口均为系统接口，仅系统应用可用。 5256 5257**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 5258 5259**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5260 5261**参数：** 5262 5263| 参数名 | 类型 | 必填 | 说明 | 5264| ----- | ------ | ---- | ----------------------- | 5265| deviceIds |string[] | 是 |需要同步DeviceKVStore数据库的设备networkId列表。 | 5266| mode |[SyncMode](#syncmode) | 是 |同步模式。 | 5267| delayMs |number | 否 |可选参数，允许延时时间，单位：ms（毫秒），默认为0。 | 5268 5269**示例：** 5270 5271```js 5272import deviceManager from '@ohos.distributedHardware.deviceManager'; 5273 5274let devManager; 5275let kvStore; 5276const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 5277const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 5278// create deviceManager 5279deviceManager.createDeviceManager('bundleName', (err, value) => { 5280 if (!err) { 5281 devManager = value; 5282 let deviceIds = []; 5283 if (devManager != null) { 5284 var devices = devManager.getTrustedDeviceListSync(); 5285 for (var i = 0; i < devices.length; i++) { 5286 deviceIds[i] = devices[i].networkId; 5287 } 5288 } 5289 try { 5290 kvStore.on('syncComplete', function (data) { 5291 console.log('Sync dataChange'); 5292 }); 5293 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) { 5294 if (err != undefined) { 5295 console.log("put err: " + JSON.stringify(err)); 5296 return; 5297 } 5298 console.log('Succeeded in putting data'); 5299 const mode = distributedData.SyncMode.PULL_ONLY; 5300 kvStore.sync(deviceIds, mode, 1000); 5301 }); 5302 } catch (e) { 5303 console.log('Sync e' + e); 5304 } 5305 } 5306}); 5307``` 5308 5309### on('dataChange')<sup>8+</sup> 5310 5311on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void 5312 5313订阅指定类型的数据变更通知。 5314 5315**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5316 5317**参数：** 5318 5319| 参数名 | 类型 | 必填 | 说明 | 5320| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | 5321| event | string | 是 | 订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 5322| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | 5323| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | 5324 5325**示例：** 5326 5327```js 5328let kvStore; 5329kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) { 5330 console.log("dataChange callback call data: " + JSON.stringify(data)); 5331}); 5332``` 5333 5334### on('syncComplete')<sup>8+</sup> 5335 5336on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void 5337 5338订阅同步完成事件回调通知。 5339 5340**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5341 5342**参数：** 5343 5344| 参数名 | 类型 | 必填 | 说明 | 5345| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | 5346| event | string | 是 | 订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 5347| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | 5348 5349**示例：** 5350 5351```js 5352let kvStore; 5353const KEY_TEST_FLOAT_ELEMENT = 'key_test_float'; 5354const VALUE_TEST_FLOAT_ELEMENT = 321.12; 5355try { 5356 kvStore.on('syncComplete', function (data) { 5357 console.log('syncComplete ' + data) 5358 }); 5359 kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => { 5360 console.log('syncComplete put success'); 5361 }).catch((error) => { 5362 console.log('syncComplete put fail ' + error); 5363 }); 5364}catch(e) { 5365 console.log('syncComplete put e ' + e); 5366} 5367``` 5368 5369### off('dataChange')<sup>8+</sup> 5370 5371off(event:'dataChange', listener?: Callback<ChangeNotification>): void 5372 5373取消订阅数据变更通知。 5374 5375**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5376 5377**参数：** 5378 5379| 参数名 | 类型 | 必填 | 说明 | 5380| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | 5381| event | string | 是 | 取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 5382| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 5383 5384**示例：** 5385 5386```js 5387let kvStore; 5388class KvstoreModel { 5389 call(data) { 5390 console.log("dataChange: " + data); 5391 } 5392 subscribeDataChange() { 5393 if (kvStore != null) { 5394 kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 5395 } 5396 } 5397 unsubscribeDataChange() { 5398 if (kvStore != null) { 5399 kvStore.off('dataChange', this.call); 5400 } 5401 } 5402} 5403``` 5404 5405### off('syncComplete')<sup>8+</sup> 5406 5407off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void 5408 5409取消订阅同步完成事件回调通知。 5410 5411**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5412 5413**参数：** 5414 5415| 参数名 | 类型 | 必填 | 说明 | 5416| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | 5417| event | string | 是 | 取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 5418| syncCallback | Callback<Array<[string, number]>> | 否 | 取消订阅的函数。如不设置callback，则取消所有订阅的函数。 | 5419 5420**示例：** 5421 5422```js 5423let kvStore; 5424class KvstoreModel { 5425 call(data) { 5426 console.log("syncComplete: " + data); 5427 } 5428 subscribeSyncComplete() { 5429 if (kvStore != null) { 5430 kvStore.on('syncComplete', this.call); 5431 } 5432 } 5433 unsubscribeSyncComplete() { 5434 if (kvStore != null) { 5435 kvStore.off('syncComplete', this.call); 5436 } 5437 } 5438} 5439``` 5440 5441## SyncMode 5442 5443同步模式枚举。 5444 5445**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5446 5447| 名称 | 值 | 说明 | 5448| ----- | ------ | ----------------------- | 5449| PULL_ONLY |0 |表示只能从远端拉取数据到本端。 | 5450| PUSH_ONLY |1 |表示只能从本端推送数据到远端。 | 5451| PUSH_PULL |2 |表示从本端推送数据到远端，然后从远端拉取数据到本端。 | 5452