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