1# @ohos.data.dataShare (Data Sharing) 2 3The **DataShare** module allows an application to manage its own data and share data with other applications on the same device. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> 10> - The APIs provided by this module are system APIs. 11> 12> 13> - The APIs of this module can be used only in the stage model. 14 15 16## Modules to Import 17 18```ts 19import dataShare from '@ohos.data.dataShare' 20``` 21 22## URI Naming Rule 23 24The URIs are in the following format: 25 26**Scheme://authority/path** 27- *Scheme*: scheme name, which has a fixed value of **datashare** for the **DataShare** module. 28- *authority*: [userinfo@]host[:port] 29 - *userinfo*: login information, which can be left unspecified. 30 - *host*: server address. It is the target device ID for cross-device access and empty for local device access. 31 - *port*: port number of the server, which can be left unspecified. 32- *path*: **DataShare** identifier and the resource path. The **DataShare** identifier is mandatory, and the resource path is optional. 33 34Example: 35 36- URI without the resource path:<br>**datashare:///com.samples.datasharetest.DataShare** 37 38- URI with the resource path:<br>**datashare:///com.samples.datasharetest.DataShare/DB00/TBL00** 39 40**com.samples.datasharetest.DataShare** is the data share identifier, and **DB00/TBL00** is the resource path. 41 42## dataShare.createDataShareHelper 43 44createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void 45 46Creates a **DataShareHelper** instance. This API uses an asynchronous callback to return the result. 47 48**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 49 50**Parameters** 51 52| Name | Type | Mandatory| Description | 53| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 54| context | [Context](js-apis-app-ability-uiAbility.md) | Yes | Context of an application. | 55| uri | string | Yes | Uniform Resource Identifier (URI) of the server application to connect. | 56| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the **DataShareHelper** instance created. Otherwise, **err** is an error object.| 57 58**Error codes** 59 60For details about the error codes, see [DataShare Error Codes](../errorcodes/errorcode-datashare.md). 61 62| ID| Error Message | 63| -------- | ---------------------------------------------------- | 64| 15700010 | The dataShareHelper is not initialized successfully. | 65 66**Example** 67 68```ts 69import UIAbility from '@ohos.app.ability.UIAbility' 70 71let uri = ("datashare:///com.samples.datasharetest.DataShare"); 72let dataShareHelper; 73try { 74 dataShare.createDataShareHelper(this.context, uri, (err, data) => { 75 if (err != undefined) { 76 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 77 return; 78 } 79 console.info("createDataShareHelper succeed, data : " + data); 80 dataShareHelper = data; 81 }); 82} catch (err) { 83 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 84}; 85``` 86 87## dataShare.createDataShareHelper 88 89createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper> 90 91Creates a **DataShareHelper** instance. This API uses a promise to return the result. 92 93**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 94 95**Parameters** 96 97| Name | Type | Mandatory| Description | 98| ------- | ------------------------------------------------- | ---- | ------------------------------ | 99| context | [Context](js-apis-app-ability-uiAbility.md) | Yes | Context of an application. | 100| uri | string | Yes | URI of the server application to connect.| 101 102**Return value** 103 104| Type | Description | 105| -------------------------------------------------- | -------------------------------------- | 106| Promise<[DataShareHelper](#datasharehelper)> | Promise used to return the **DataShareHelper** instance created.| 107 108**Error codes** 109 110For details about the error codes, see [DataShare Error Codes](../errorcodes/errorcode-datashare.md). 111 112| ID| Error Message | 113| -------- | ---------------------------------------------------- | 114| 15700010 | The dataShareHelper is not initialized successfully. | 115 116**Example** 117 118```ts 119import UIAbility from '@ohos.app.ability.UIAbility' 120 121let uri = ("datashare:///com.samples.datasharetest.DataShare"); 122let dataShareHelper; 123try { 124 dataShare.createDataShareHelper(this.context, uri).then((data) => { 125 console.info("createDataShareHelper succeed, data : " + data); 126 dataShareHelper = data; 127 }). catch((err) => { 128 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 129 }); 130} catch (err) { 131 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 132}; 133``` 134 135## DataShareHelper 136 137Provides a **DataShareHelper** instance to access or manage data on the server. Before calling an API provided by **DataShareHelper**, you must create a **DataShareHelper** instance using [createDataShareHelper](#datasharecreatedatasharehelper). 138 139### on('dataChange') 140 141on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void 142 143Subscribes to changes of the specified data. After an observer is registered, the subscriber will receive a notification when the change notification is triggered (the **notifyChange()** method is called). This API uses an asynchronous callback to return the result. 144 145**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 146 147**Parameters** 148 149| Name | Type | Mandatory| Description | 150| -------- | -------------------- | ---- | ------------------------ | 151| type | string | Yes | Event type to subscribe to. The value is **dataChange**, which indicates data change events.| 152| uri | string | Yes | URI of the data.| 153| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If data is changed, the value of **err** is undefined. Otherwise, this callback is not invoked or the value of **err** is an error object.| 154 155**Example** 156 157```ts 158import UIAbility from '@ohos.app.ability.UIAbility' 159function onCallback() { 160 console.info("**** Observer on callback ****"); 161} 162let uri = ("datashare:///com.samples.datasharetest.DataShare"); 163dataShareHelper.on("dataChange", uri, onCallback); 164``` 165 166### off('dataChange') 167 168off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void 169 170Unsubscribes from the changes of the specified data. This API uses an asynchronous callback to return the result. 171 172**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 173 174**Parameters** 175 176| Name | Type | Mandatory| Description | 177| -------- | -------------------- | ---- | ------------------------ | 178| type | string | Yes | Event type to unsubscribe from. The value is **dataChange**, which indicates data change events.| 179| uri | string | Yes | URI of the data.| 180| callback | AsyncCallback<void> | No | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| 181 182**Example** 183 184```ts 185import UIAbility from '@ohos.app.ability.UIAbility' 186function offCallback() { 187 console.info("**** Observer off callback ****"); 188} 189let uri = ("datashare:///com.samples.datasharetest.DataShare"); 190dataShareHelper.off("dataChange", uri, offCallback); 191``` 192 193### insert 194 195insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void 196 197Inserts a single data record into the database. This API uses an asynchronous callback to return the result. 198 199**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 200 201**Parameters** 202 203| Name | Type | Mandatory| Description | 204| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 205| uri | string | Yes | URI of the data to insert. | 206| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes | Data to insert. If this parameter is empty, a blank row will be inserted. | 207| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the index of the inserted data record. Otherwise, **err** is an error object.<br>The data index is not returned if the APIs of the database in use, for example, the key-value database (KVDB), do not support the return of indexes.| 208 209**Example** 210 211```ts 212import UIAbility from '@ohos.app.ability.UIAbility' 213let uri = ("datashare:///com.samples.datasharetest.DataShare"); 214const valueBucket = { 215 "name": "rose", 216 "age": 22, 217 "salary": 200.5, 218} 219try { 220 dataShareHelper.insert(uri, valueBucket, (err, data) => { 221 if (err != undefined) { 222 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 223 return; 224 } 225 console.info("insert succeed, data : " + data); 226 }); 227} catch (err) { 228 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 229}; 230``` 231 232### insert 233 234insert(uri: string, value: ValuesBucket): Promise<number> 235 236Inserts a single data record into the database. This API uses a promise to return the result. 237 238**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 239 240**Parameters** 241 242| Name | Type | Mandatory| Description | 243| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- | 244| uri | string | Yes | URI of the data to insert. | 245| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes | Data to insert. If this parameter is empty, a blank row will be inserted.| 246 247**Return value** 248 249| Type | Description | 250| ---------------- | ------------------------------------------------------------ | 251| Promise<number> | Promise used to return the index of the inserted data record.<br>The data index is not returned if the APIs of the database in use (for example, KVDB) do not support the return of indexes.| 252 253**Example** 254 255```ts 256import UIAbility from '@ohos.app.ability.UIAbility' 257let uri = ("datashare:///com.samples.datasharetest.DataShare"); 258const valueBucket = { 259 "name": "rose1", 260 "age": 221, 261 "salary": 20.5, 262} 263try { 264 dataShareHelper.insert(uri, valueBucket).then((data) => { 265 console.log("insert succeed, data : " + data); 266 }). catch((err) => { 267 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 268 }); 269} catch (err) { 270 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 271}; 272``` 273 274### delete 275 276delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 277 278Deletes one or more data records from the database. This API uses an asynchronous callback to return the result. 279 280**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 281 282**Parameters** 283 284| Name | Type | Mandatory| Description | 285| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 286| uri | string | Yes | URI of the data to delete. | 287| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **delete()** vary depending on the database in use. For example, the KVDB supports only **inKeys**.| 288| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of deleted data records. Otherwise, **err** is an error object.<br>The number of deleted data records is not returned if the APIs of the database in use (for example, KVDB) do not support this return.| 289 290**Example** 291 292```ts 293import UIAbility from '@ohos.app.ability.UIAbility' 294import dataSharePredicates from '@ohos.data.dataSharePredicates' 295 296let uri = ("datashare:///com.samples.datasharetest.DataShare"); 297let da = new dataSharePredicates.DataSharePredicates(); 298da.equalTo("name", "ZhangSan"); 299try { 300 dataShareHelper.delete(uri, da, (err, data) => { 301 if (err != undefined) { 302 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 303 return; 304 } 305 console.info("delete succeed, data : " + data); 306 }); 307} catch (err) { 308 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 309}; 310``` 311 312### delete 313 314delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number> 315 316Deletes one or more data records from the database. This API uses a promise to return the result. 317 318**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 319 320**Parameters** 321 322| Name | Type | Mandatory| Description | 323| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 324| uri | string | Yes | URI of the data to delete. | 325| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **delete()** vary depending on the database in use. For example, the KVDB supports only **inKeys**.| 326 327**Return value** 328 329| Type | Description | 330| ---------------- | ------------------------------------------------------------ | 331| Promise<number> | Promise used to return the number of deleted data records.<br>The number of deleted data records is not returned if the APIs of the database in use (for example, KVDB) do not support this return.| 332 333**Example** 334 335```ts 336import UIAbility from '@ohos.app.ability.UIAbility' 337import dataSharePredicates from '@ohos.data.dataSharePredicates' 338 339let uri = ("datashare:///com.samples.datasharetest.DataShare"); 340let da = new dataSharePredicates.DataSharePredicates(); 341da.equalTo("name", "ZhangSan"); 342try { 343 dataShareHelper.delete(uri, da).then((data) => { 344 console.log("delete succeed, data : " + data); 345 }). catch((err) => { 346 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 347 }); 348} catch (err) { 349 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 350}; 351``` 352 353### query 354 355query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void 356 357Queries data in the database. This API uses an asynchronous callback to return the result. 358 359**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 360 361**Parameters** 362 363| Name | Type | Mandatory| Description | 364| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 365| uri | string | Yes | URI of the data to query. | 366| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **query()** vary depending on the database used. For example, the KVDB supports only **inKeys** and **prefixKey**.| 367| columns | Array<string> | Yes | Columns to query. If this parameter is empty, all columns will be queried. | 368| callback | AsyncCallback<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the result set obtained. Otherwise, **err** is an error object.| 369 370**Example** 371 372```ts 373import UIAbility from '@ohos.app.ability.UIAbility' 374import dataSharePredicates from '@ohos.data.dataSharePredicates' 375 376let uri = ("datashare:///com.samples.datasharetest.DataShare"); 377let columns = ["*"]; 378let da = new dataSharePredicates.DataSharePredicates(); 379da.equalTo("name", "ZhangSan"); 380try { 381 dataShareHelper.query(uri, da, columns, (err, data) => { 382 if (err != undefined) { 383 console.error(`query error: code: ${err.code}, message: ${err.message} `); 384 return; 385 } 386 console.log("query succeed, rowCount : " + data.rowCount); 387 }); 388} catch (err) { 389 console.error(`query error: code: ${err.code}, message: ${err.message} `); 390}; 391``` 392 393### query 394 395query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet> 396 397Queries data in the database. This API uses a promise to return the result. 398 399**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 400 401**Parameters** 402 403| Name | Type | Mandatory| Description | 404| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 405| uri | string | Yes | URI of the data to query. | 406| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **query()** vary depending on the database used. For example, the KVDB supports only **inKeys** and **prefixKey**.| 407| columns | Array<string> | Yes | Columns to query. If this parameter is empty, all columns will be queried. | 408 409**Return value** 410 411| Type | Description | 412| ------------------------------------------------------------ | --------------------------------- | 413| Promise<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Promise used to return the result set obtained.| 414 415**Example** 416 417```ts 418import UIAbility from '@ohos.app.ability.UIAbility' 419import dataSharePredicates from '@ohos.data.dataSharePredicates' 420 421let uri = ("datashare:///com.samples.datasharetest.DataShare"); 422let columns = ["*"]; 423let da = new dataSharePredicates.DataSharePredicates(); 424da.equalTo("name", "ZhangSan"); 425try { 426 dataShareHelper.query(uri, da, columns).then((data) => { 427 console.log("query succeed, rowCount : " + data.rowCount); 428 }). catch((err) => { 429 console.error(`query error: code: ${err.code}, message: ${err.message} `); 430 }); 431} catch (err) { 432 console.error(`query error: code: ${err.code}, message: ${err.message} `); 433}; 434``` 435 436### update 437 438update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void 439 440Updates data in the database. This API uses an asynchronous callback to return the result. 441 442**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 443 444**Parameters** 445 446| Name | Type | Mandatory| Description | 447| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 448| uri | string | Yes | URI of the data to update. | 449| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **update()** vary depending on the database in use. For example, only the relational database (RDB) supports predicates.| 450| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes | New data. | 451| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of updated data records. Otherwise, **err** is an error object.<br>The number of updated data records is not returned if the APIs of the database in use (for example, KVDB) do not support this return.| 452 453**Example** 454 455```ts 456import UIAbility from '@ohos.app.ability.UIAbility' 457import dataSharePredicates from '@ohos.data.dataSharePredicates' 458 459let uri = ("datashare:///com.samples.datasharetest.DataShare"); 460let da = new dataSharePredicates.DataSharePredicates(); 461da.equalTo("name", "ZhangSan"); 462const va = { 463 "name": "roe1", 464 "age": 21, 465 "salary": 20.5, 466 467} 468try { 469 dataShareHelper.update(uri, da, va, (err, data) => { 470 if (err != undefined) { 471 console.error(`update error: code: ${err.code}, message: ${err.message} `); 472 return; 473 } 474 console.log("update succeed, data : " + data); 475 }); 476} catch (err) { 477 console.error(`update error: code: ${err.code}, message: ${err.message} `); 478}; 479``` 480 481### update 482 483update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number> 484 485Updates data in the database. This API uses a promise to return the result. 486 487**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 488 489**Parameters** 490 491| Name | Type | Mandatory| Description | 492| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 493| uri | string | Yes | URI of the data to update. | 494| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.<br>The predicate methods supported by **update()** vary depending on the database in use. For example, only the relational database (RDB) supports predicates.| 495| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | Yes | New data. | 496 497**Return value** 498 499| Type | Description | 500| ---------------- | ------------------------------------------------------------ | 501| Promise<number> | Promise used to return the number of data records updated.<br>The number of updated data records is not returned if the APIs of the database in use (for example, KVDB) do not support this return.| 502 503**Example** 504 505```ts 506import UIAbility from '@ohos.app.ability.UIAbility' 507import dataSharePredicates from '@ohos.data.dataSharePredicates' 508 509let uri = ("datashare:///com.samples.datasharetest.DataShare"); 510let da = new dataSharePredicates.DataSharePredicates(); 511da.equalTo("name", "ZhangSan"); 512const va = { 513 "name": "roe1", 514 "age": 21, 515 "salary": 20.5, 516 517} 518try { 519 dataShareHelper.update(uri, da, va).then((data) => { 520 console.log("update succeed, data : " + data); 521 }). catch((err) => { 522 console.error(`update error: code: ${err.code}, message: ${err.message} `); 523 }); 524} catch (err) { 525 console.error(`update error: code: ${err.code}, message: ${err.message} `); 526}; 527``` 528 529### batchInsert 530 531batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void 532 533Batch inserts data into the database. This API uses an asynchronous callback to return the result. 534 535**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 536 537**Parameters** 538 539| Name | Type | Mandatory| Description | 540| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 541| uri | string | Yes | URI of the data to insert. | 542| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to insert. | 543| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of data records inserted. Otherwise, **err** is an error object.<br>The number of inserted data records is not returned if the APIs of the database in use (for example, KVDB) do not support this return.| 544 545**Example** 546 547```ts 548import UIAbility from '@ohos.app.ability.UIAbility' 549let uri = ("datashare:///com.samples.datasharetest.DataShare"); 550let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, 551 {"name": "roe12", "age": 21, "salary": 20.5,}, 552 {"name": "roe13", "age": 21, "salary": 20.5,}) 553try { 554 dataShareHelper.batchInsert(uri, vbs, (err, data) => { 555 if (err != undefined) { 556 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 557 return; 558 } 559 console.log("batchInsert succeed, data : " + data); 560 }); 561} catch (err) { 562 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 563}; 564``` 565 566### batchInsert 567 568batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number> 569 570Batch inserts data into the database. This API uses a promise to return the result. 571 572**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 573 574**Parameters** 575 576| Name | Type | Mandatory| Description | 577| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 578| uri | string | Yes | URI of the data to insert.| 579| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | Yes | Data to insert. | 580 581**Return value** 582 583| Type | Description | 584| ---------------- | ------------------------------------------------------------ | 585| Promise<number> | Promise used to return the number of data records inserted.<br>The number of inserted data records is not returned if the APIs of the database (for example, KVDB) in use do not the return of the number of data records.| 586 587**Example** 588 589```ts 590import UIAbility from '@ohos.app.ability.UIAbility' 591let uri = ("datashare:///com.samples.datasharetest.DataShare"); 592let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, 593 {"name": "roe12", "age": 21, "salary": 20.5,}, 594 {"name": "roe13", "age": 21, "salary": 20.5,}) 595try { 596 dataShareHelper.batchInsert(uri, vbs).then((data) => { 597 console.log("batchInsert succeed, data : " + data); 598 }). catch((err) => { 599 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 600 }); 601} catch (err) { 602 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 603}; 604``` 605 606### normalizeUri 607 608normalizeUri(uri: string, callback: AsyncCallback<string>): void 609 610Normalizes a **DataShare** URI. The **DataShare** URI can be used only by the local device, but the normalized URI can be used across devices. This API uses an asynchronous callback to return the result. 611 612**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 613 614**Parameters** 615 616| Name | Type | Mandatory| Description | 617| -------- | ---------------------- | ---- | -------------------------------------------------------- | 618| uri | string | Yes | [URI](js-apis-uri.md#uri) to normalize. | 619| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the normalized URI (if **null** is returned, URI normalization is not supported). Otherwise, **err** is an error object.| 620 621**Example** 622 623```ts 624import UIAbility from '@ohos.app.ability.UIAbility' 625let uri = ("datashare:///com.samples.datasharetest.DataShare"); 626dataShareHelper.normalizeUri(uri, (err, data) => { 627 if (err != undefined) { 628 console.log("normalizeUri failed, error message : " + err); 629 }else{ 630 console.log("normalizeUri = " + data); 631 } 632}); 633``` 634 635### normalizeUri 636 637normalizeUri(uri: string): Promise<string> 638 639Normalizes a **DataShare** URI. The **DataShare** URI can be used only by the local device, but the normalized URI can be used across devices. This API uses a promise to return the result. 640 641**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 642 643**Parameters** 644 645| Name| Type | Mandatory| Description | 646| ---- | ------ | ---- | ----------------------------------------- | 647| uri | string | Yes | [URI](js-apis-uri.md#uri) to normalize.| 648 649**Return value** 650 651| Type | Description | 652| ---------------- | ---------------------------------------------- | 653| Promise<string> | Promise used to return the result. If URI normalization is supported, the normalized URI is returned. Otherwise, **null** is returned.| 654 655**Example** 656 657```ts 658import UIAbility from '@ohos.app.ability.UIAbility' 659let uri = ("datashare:///com.samples.datasharetest.DataShare"); 660dataShareHelper.normalizeUri(uri).then((data) => { 661 console.log("normalizeUri = " + data); 662}).catch((err) => { 663 console.log("normalizeUri failed, error message : " + err); 664}); 665``` 666 667### denormalizeUri 668 669denormalizeUri(uri: string, callback: AsyncCallback<string>): void 670 671Denormalizes a URI. This API uses an asynchronous callback to return the result. 672 673**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 674 675**Parameters** 676 677| Name | Type | Mandatory| Description | 678| -------- | ---------------------- | ---- | --------------------------------------------------- | 679| uri | string | Yes | [URI](js-apis-uri.md#uri) to denormalize.| 680| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the URI obtained. If the original URI is returned, denormalization is not required. If **null** is returned, denormalization is not supported. If the operation fails, **err** is an error object.| 681 682**Example** 683 684```ts 685import UIAbility from '@ohos.app.ability.UIAbility' 686let uri = ("datashare:///com.samples.datasharetest.DataShare"); 687dataShareHelper.denormalizeUri(uri, (err, data) => { 688 if (err != undefined) { 689 console.log("denormalizeUri failed, error message : " + err); 690 }else{ 691 console.log("denormalizeUri = " + data); 692 } 693}); 694``` 695 696### denormalizeUri 697 698denormalizeUri(uri: string): Promise<string> 699 700Denormalizes a URI. This API uses a promise to return the result. 701 702**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 703 704**Parameters** 705 706| Name| Type | Mandatory| Description | 707| ---- | ------ | ---- | ------------------------------------------- | 708| uri | string | Yes | [URI](js-apis-uri.md#uri) to denormalize.| 709 710**Return value** 711 712| Type | Description | 713| ---------------- | ----------------------------------------- | 714| Promise<string> | Promise used to return the result. If the denormalization is successful, the URI obtained is returned. If no operation is required, the original URI is returned. If denormalization is not supported, **null** is returned.| 715 716**Example** 717 718```ts 719import UIAbility from '@ohos.app.ability.UIAbility' 720let uri = ("datashare:///com.samples.datasharetest.DataShare"); 721dataShareHelper.denormalizeUri(uri).then((data) => { 722 console.log("denormalizeUri = " + data); 723}).catch((err) => { 724 console.log("denormalizeUri failed, error message : " + err); 725}); 726``` 727 728### notifyChange 729 730notifyChange(uri: string, callback: AsyncCallback<void>): void 731 732Notifies the registered observer of data changes. This API uses an asynchronous callback to return the result. 733 734**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 735 736**Parameters** 737 738| Name | Type | Mandatory| Description | 739| -------- | -------------------- | ---- | ------------------------ | 740| uri | string | Yes | URI of the data.| 741| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the observer is notified of the data changes, **err** is **undefined**. Otherwise, **err** is an error object.| 742 743**Example** 744 745```ts 746import UIAbility from '@ohos.app.ability.UIAbility' 747let uri = ("datashare:///com.samples.datasharetest.DataShare"); 748dataShareHelper.notifyChange(uri, () => { 749 console.log("***** notifyChange *****"); 750}); 751``` 752 753### notifyChange 754 755notifyChange(uri: string): Promise<void> 756 757Notifies the registered observer of data changes. This API uses a promise to return the result. 758 759**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer 760 761**Parameters** 762 763| Name| Type | Mandatory| Description | 764| ---- | ------ | ---- | -------------------- | 765| uri | string | Yes | URI of the data.| 766 767**Return value** 768 769| Type | Description | 770| -------------- | --------------------- | 771| Promise<void> | Promise that returns no value.| 772 773**Example** 774 775```ts 776import UIAbility from '@ohos.app.ability.UIAbility' 777let uri = ("datashare:///com.samples.datasharetest.DataShare"); 778dataShareHelper.notifyChange(uri); 779``` 780