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