1# @ohos.data.dataShare (数据共享) 2 3**DataShare**用于应用管理其自身数据，同时支持同个设备上不同应用间的数据共享。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口为系统接口。 10> 11> 本模块接口仅可在Stage模型下使用。 12 13 14## 导入模块 15 16```ts 17import dataShare from '@ohos.data.dataShare' 18``` 19 20## uri命名规则 21 22标准uri定义结构如下: 23 24**Scheme://authority/path** 25- Scheme: 协议名，对于data share统一为datashare 26- authority: [userinfo@]host[:port] 27 - userinfo: 登录信息，不需要填写。 28 - host: 服务器地址，如果跨设备访问则为目标设备的ID，如果为本设备则为空。 29 - port: 服务器端口，不需要填写。 30- path: data share的标识信息和资源的路径信息，需要包含data share的标识信息，资源的路径信息可以不填写。 31 32uri示例: 33 34- 不包含资源路径: `datashare:///com.samples.datasharetest.DataShare` 35 36- 包含资源路径: `datashare:///com.samples.datasharetest.DataShare/DB00/TBL00` 37 38其中，data share的标识信息为`com.samples.datasharetest.DataShare`，资源路径为`DB00/TBL00`。 39 40## dataShare.createDataShareHelper 41 42createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void 43 44创建DataShareHelper实例。使用callback异步回调。 45 46**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 47 48**参数：** 49 50| 参数名 | 类型 | 必填 | 说明 | 51| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 52| context | [Context](js-apis-app-ability-uiAbility.md) | 是 | 应用的上下文环境。 | 53| uri | string | 是 | 指示要连接的服务端应用的路径。 | 54| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是 | 回调函数。当创建DataShareHelper实例成功，err为undefined，data为获取到的DataShareHelper实例；否则为错误对象。 | 55 56**错误码：** 57 58以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 59 60| 错误码ID | 错误信息 | 61| -------- | ---------------------------------------------------- | 62| 15700010 | The dataShareHelper is not initialized successfully. | 63 64**示例：** 65 66```ts 67import UIAbility from '@ohos.app.ability.UIAbility' 68 69let uri = ("datashare:///com.samples.datasharetest.DataShare"); 70let dataShareHelper; 71try { 72 dataShare.createDataShareHelper(this.context, uri, (err, data) => { 73 if (err != undefined) { 74 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 75 return; 76 } 77 console.info("createDataShareHelper succeed, data : " + data); 78 dataShareHelper = data; 79 }); 80} catch (err) { 81 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 82}; 83``` 84 85## dataShare.createDataShareHelper 86 87createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper> 88 89创建DataShareHelper实例。使用Promise异步回调。 90 91**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 92 93**参数：** 94 95| 参数名 | 类型 | 必填 | 说明 | 96| ------- | ------------------------------------------------- | ---- | ------------------------------ | 97| context | [Context](js-apis-app-ability-uiAbility.md) | 是 | 应用的上下文环境。 | 98| uri | string | 是 | 指示要连接的服务端应用的路径。 | 99 100**返回值：** 101 102| 类型 | 说明 | 103| -------------------------------------------------- | -------------------------------------- | 104| Promise<[DataShareHelper](#datasharehelper)> | Promise对象。返回DataShareHelper实例。 | 105 106**错误码：** 107 108以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 109 110| 错误码ID | 错误信息 | 111| -------- | ---------------------------------------------------- | 112| 15700010 | The dataShareHelper is not initialized successfully. | 113 114**示例：** 115 116```ts 117import UIAbility from '@ohos.app.ability.UIAbility' 118 119let uri = ("datashare:///com.samples.datasharetest.DataShare"); 120let dataShareHelper; 121try { 122 dataShare.createDataShareHelper(this.context, uri).then((data) => { 123 console.info("createDataShareHelper succeed, data : " + data); 124 dataShareHelper = data; 125 }). catch((err) => { 126 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 127 }); 128} catch (err) { 129 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 130}; 131``` 132 133## DataShareHelper 134 135DataShare管理工具实例，可使用此实例访问或管理服务端的数据。在调用DataShareHelper提供的方法前，需要先通过[createDataShareHelper](#datasharecreatedatasharehelper)构建一个实例。 136 137### on('dataChange') 138 139on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void 140 141订阅指定URI对应数据的数据变更事件。若用户（订阅者）已注册了观察者，当有其他用户触发了变更通知时（调用了下文中的notifyChange方法），订阅者将会接收到callback通知。使用callback异步回调。 142 143**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| -------- | -------------------- | ---- | ------------------------ | 149| type | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当数据更改时，触发该事件。 | 150| uri | string | 是 | 表示指定的数据路径。 | 151| callback | AsyncCallback<void> | 是 | 回调函数。当有其他用户触发了变更通知时调用，err为undefined；否则不被触发或为错误对象。 | 152 153**示例：** 154 155```ts 156import UIAbility from '@ohos.app.ability.UIAbility' 157function onCallback() { 158 console.info("**** Observer on callback ****"); 159} 160let uri = ("datashare:///com.samples.datasharetest.DataShare"); 161dataShareHelper.on("dataChange", uri, onCallback); 162``` 163 164### off('dataChange') 165 166off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void 167 168取消订阅指定URI对应的数据资源的变更通知。使用callback异步回调。 169 170**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 171 172**参数：** 173 174| 参数名 | 类型 | 必填 | 说明 | 175| -------- | -------------------- | ---- | ------------------------ | 176| type | string | 是 | 取消订阅的事件/回调类型，支持的事件为'dataChange'。 | 177| uri | string | 是 | 表示指定的数据路径。 | 178| callback | AsyncCallback<void> | 否 | 回调函数。当取消订阅指定URI对应的数据资源的变更通知成功，err为undefined；否则为错误对象。 | 179 180**示例：** 181 182```ts 183import UIAbility from '@ohos.app.ability.UIAbility' 184function offCallback() { 185 console.info("**** Observer off callback ****"); 186} 187let uri = ("datashare:///com.samples.datasharetest.DataShare"); 188dataShareHelper.off("dataChange", uri, offCallback); 189``` 190 191### insert 192 193insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void 194 195将单条数据插入数据库。使用callback异步回调。 196 197**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 198 199**参数：** 200 201| 参数名 | 类型 | 必填 | 说明 | 202| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 203| uri | string | 是 | 指示要插入的数据的路径。 | 204| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。如果此参数为空，将插入一个空行。 | 205| callback | AsyncCallback<number> | 是 | 回调函数。当将单条数据插入数据库成功，err为undefined，data为获取到的插入数据记录的索引；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此callback也无法返回索引值。 | 206 207**示例：** 208 209```ts 210import UIAbility from '@ohos.app.ability.UIAbility' 211let uri = ("datashare:///com.samples.datasharetest.DataShare"); 212const valueBucket = { 213 "name": "rose", 214 "age": 22, 215 "salary": 200.5, 216} 217try { 218 dataShareHelper.insert(uri, valueBucket, (err, data) => { 219 if (err != undefined) { 220 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 221 return; 222 } 223 console.info("insert succeed, data : " + data); 224 }); 225} catch (err) { 226 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 227}; 228``` 229 230### insert 231 232insert(uri: string, value: ValuesBucket): Promise<number> 233 234将单条数据插入数据库。使用Promise异步回调。 235 236**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 237 238**参数：** 239 240| 参数名 | 类型 | 必填 | 说明 | 241| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- | 242| uri | string | 是 | 指示要插入的数据的路径。 | 243| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。如果此参数为空，将插入一个空行。 | 244 245**返回值：** 246 247| 类型 | 说明 | 248| ---------------- | ------------------------------------------------------------ | 249| Promise<number> | Promise对象。返回插入数据记录的索引。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此Promise也无法返回索引值。 | 250 251**示例：** 252 253```ts 254import UIAbility from '@ohos.app.ability.UIAbility' 255let uri = ("datashare:///com.samples.datasharetest.DataShare"); 256const valueBucket = { 257 "name": "rose1", 258 "age": 221, 259 "salary": 20.5, 260} 261try { 262 dataShareHelper.insert(uri, valueBucket).then((data) => { 263 console.log("insert succeed, data : " + data); 264 }). catch((err) => { 265 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 266 }); 267} catch (err) { 268 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 269}; 270``` 271 272### delete 273 274delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 275 276从数据库中删除一条或多条数据记录。使用callback异步回调。 277 278**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 279 280**参数：** 281 282| 参数名 | 类型 | 必填 | 说明 | 283| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 284| uri | string | 是 | 指示要删除的数据的路径。 | 285| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。 | 286| callback | AsyncCallback<number> | 是 | 回调函数。当从数据库中删除一条或多条数据记录成功，err为undefined，data为获取到的已删除的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回删除的数据记录数。 | 287 288**示例：** 289 290```ts 291import UIAbility from '@ohos.app.ability.UIAbility' 292import dataSharePredicates from '@ohos.data.dataSharePredicates' 293 294let uri = ("datashare:///com.samples.datasharetest.DataShare"); 295let da = new dataSharePredicates.DataSharePredicates(); 296da.equalTo("name", "ZhangSan"); 297try { 298 dataShareHelper.delete(uri, da, (err, data) => { 299 if (err != undefined) { 300 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 301 return; 302 } 303 console.info("delete succeed, data : " + data); 304 }); 305} catch (err) { 306 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 307}; 308``` 309 310### delete 311 312delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number> 313 314从数据库中删除一条或多条数据记录。使用Promise异步回调。 315 316**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 317 318**参数：** 319 320| 参数名 | 类型 | 必填 | 说明 | 321| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 322| uri | string | 是 | 指示要删除的数据的路径。 | 323| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。 | 324 325**返回值：** 326 327| 类型 | 说明 | 328| ---------------- | ------------------------------------------------------------ | 329| Promise<number> | Promise对象。返回已删除的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回删除的数据记录数。 | 330 331**示例：** 332 333```ts 334import UIAbility from '@ohos.app.ability.UIAbility' 335import dataSharePredicates from '@ohos.data.dataSharePredicates' 336 337let uri = ("datashare:///com.samples.datasharetest.DataShare"); 338let da = new dataSharePredicates.DataSharePredicates(); 339da.equalTo("name", "ZhangSan"); 340try { 341 dataShareHelper.delete(uri, da).then((data) => { 342 console.log("delete succeed, data : " + data); 343 }). catch((err) => { 344 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 345 }); 346} catch (err) { 347 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 348}; 349``` 350 351### query 352 353query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void 354 355查询数据库中的数据。使用callback异步回调。 356 357**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 358 359**参数：** 360 361| 参数名 | 类型 | 必填 | 说明 | 362| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 363| uri | string | 是 | 指示要查询的数据的路径。 | 364| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。 | 365| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 | 366| callback | AsyncCallback<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | 是 | 回调函数。当查询数据库中的数据成功，err为undefined，data为获取到的查询到的结果集；否则为错误对象。 | 367 368**示例：** 369 370```ts 371import UIAbility from '@ohos.app.ability.UIAbility' 372import dataSharePredicates from '@ohos.data.dataSharePredicates' 373 374let uri = ("datashare:///com.samples.datasharetest.DataShare"); 375let columns = ["*"]; 376let da = new dataSharePredicates.DataSharePredicates(); 377da.equalTo("name", "ZhangSan"); 378try { 379 dataShareHelper.query(uri, da, columns, (err, data) => { 380 if (err != undefined) { 381 console.error(`query error: code: ${err.code}, message: ${err.message} `); 382 return; 383 } 384 console.log("query succeed, rowCount : " + data.rowCount); 385 }); 386} catch (err) { 387 console.error(`query error: code: ${err.code}, message: ${err.message} `); 388}; 389``` 390 391### query 392 393query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet> 394 395查询数据库中的数据。使用Promise异步回调。 396 397**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 403| uri | string | 是 | 指示要查询的数据的路径。 | 404| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。 | 405| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 | 406 407**返回值：** 408 409| 类型 | 说明 | 410| ------------------------------------------------------------ | --------------------------------- | 411| Promise<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Promise对象。返回查询到的结果集。 | 412 413**示例：** 414 415```ts 416import UIAbility from '@ohos.app.ability.UIAbility' 417import dataSharePredicates from '@ohos.data.dataSharePredicates' 418 419let uri = ("datashare:///com.samples.datasharetest.DataShare"); 420let columns = ["*"]; 421let da = new dataSharePredicates.DataSharePredicates(); 422da.equalTo("name", "ZhangSan"); 423try { 424 dataShareHelper.query(uri, da, columns).then((data) => { 425 console.log("query succeed, rowCount : " + data.rowCount); 426 }). catch((err) => { 427 console.error(`query error: code: ${err.code}, message: ${err.message} `); 428 }); 429} catch (err) { 430 console.error(`query error: code: ${err.code}, message: ${err.message} `); 431}; 432``` 433 434### update 435 436update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void 437 438更新数据库中的数据记录。使用callback异步回调。 439 440**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 441 442**参数：** 443 444| 参数名 | 类型 | 必填 | 说明 | 445| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 446| uri | string | 是 | 指示要更新的数据的路径。 | 447| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。 | 448| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 | 449| callback | AsyncCallback<number> | 是 | 回调函数。当更新数据库中的数据记录成功，err为undefined，data为获取到的更新的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回更新的数据记录数。 | 450 451**示例：** 452 453```ts 454import UIAbility from '@ohos.app.ability.UIAbility' 455import dataSharePredicates from '@ohos.data.dataSharePredicates' 456 457let uri = ("datashare:///com.samples.datasharetest.DataShare"); 458let da = new dataSharePredicates.DataSharePredicates(); 459da.equalTo("name", "ZhangSan"); 460const va = { 461 "name": "roe1", 462 "age": 21, 463 "salary": 20.5, 464 465} 466try { 467 dataShareHelper.update(uri, da, va, (err, data) => { 468 if (err != undefined) { 469 console.error(`update error: code: ${err.code}, message: ${err.message} `); 470 return; 471 } 472 console.log("update succeed, data : " + data); 473 }); 474} catch (err) { 475 console.error(`update error: code: ${err.code}, message: ${err.message} `); 476}; 477``` 478 479### update 480 481update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number> 482 483更新数据库中的数据记录。使用Promise异步回调。 484 485**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 486 487**参数：** 488 489| 参数名 | 类型 | 必填 | 说明 | 490| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 491| uri | string | 是 | 指示要更新的数据的路径。 | 492| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。 | 493| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 | 494 495**返回值：** 496 497| 类型 | 说明 | 498| ---------------- | ------------------------------------------------------------ | 499| Promise<number> | Promise对象。返回更新的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回更新的数据记录数。 | 500 501**示例：** 502 503```ts 504import UIAbility from '@ohos.app.ability.UIAbility' 505import dataSharePredicates from '@ohos.data.dataSharePredicates' 506 507let uri = ("datashare:///com.samples.datasharetest.DataShare"); 508let da = new dataSharePredicates.DataSharePredicates(); 509da.equalTo("name", "ZhangSan"); 510const va = { 511 "name": "roe1", 512 "age": 21, 513 "salary": 20.5, 514 515} 516try { 517 dataShareHelper.update(uri, da, va).then((data) => { 518 console.log("update succeed, data : " + data); 519 }). catch((err) => { 520 console.error(`update error: code: ${err.code}, message: ${err.message} `); 521 }); 522} catch (err) { 523 console.error(`update error: code: ${err.code}, message: ${err.message} `); 524}; 525``` 526 527### batchInsert 528 529batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void 530 531将批量数据插入数据库。使用callback异步回调。 532 533**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 539| uri | string | 是 | 指示要插入的数据的路径。 | 540| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 指示要插入的数据。 | 541| callback | AsyncCallback<number> | 是 | 回调函数。当将批量数据插入数据库成功，err为undefined，data为获取到的插入的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 542 543**示例：** 544 545```ts 546import UIAbility from '@ohos.app.ability.UIAbility' 547let uri = ("datashare:///com.samples.datasharetest.DataShare"); 548let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, 549 {"name": "roe12", "age": 21, "salary": 20.5,}, 550 {"name": "roe13", "age": 21, "salary": 20.5,}) 551try { 552 dataShareHelper.batchInsert(uri, vbs, (err, data) => { 553 if (err != undefined) { 554 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 555 return; 556 } 557 console.log("batchInsert succeed, data : " + data); 558 }); 559} catch (err) { 560 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 561}; 562``` 563 564### batchInsert 565 566batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number> 567 568将批量数据插入数据库。使用Promise异步回调。 569 570**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 571 572**参数：** 573 574| 参数名 | 类型 | 必填 | 说明 | 575| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 576| uri | string | 是 | 指示要插入的数据的路径。 | 577| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 指示要插入的数据。 | 578 579**返回值：** 580 581| 类型 | 说明 | 582| ---------------- | ------------------------------------------------------------ | 583| Promise<number> | Promise对象。返回插入的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 584 585**示例：** 586 587```ts 588import UIAbility from '@ohos.app.ability.UIAbility' 589let uri = ("datashare:///com.samples.datasharetest.DataShare"); 590let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, 591 {"name": "roe12", "age": 21, "salary": 20.5,}, 592 {"name": "roe13", "age": 21, "salary": 20.5,}) 593try { 594 dataShareHelper.batchInsert(uri, vbs).then((data) => { 595 console.log("batchInsert succeed, data : " + data); 596 }). catch((err) => { 597 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 598 }); 599} catch (err) { 600 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 601}; 602``` 603 604### normalizeUri 605 606normalizeUri(uri: string, callback: AsyncCallback<string>): void 607 608将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用callback异步回调。 609 610**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 611 612**参数：** 613 614| 参数名 | 类型 | 必填 | 说明 | 615| -------- | ---------------------- | ---- | -------------------------------------------------------- | 616| uri | string | 是 | 指示要规范化的[URI](js-apis-uri.md#uri)。 | 617| callback | AsyncCallback<string> | 是 | 回调函数。当将给定的DataShare URI转换为规范化URI成功，err为undefined，data为获取到的规范化URI（如果支持URI规范化，则返回规范化URI，否则返回空）；否则为错误对象。 | 618 619**示例：** 620 621```ts 622import UIAbility from '@ohos.app.ability.UIAbility' 623let uri = ("datashare:///com.samples.datasharetest.DataShare"); 624dataShareHelper.normalizeUri(uri, (err, data) => { 625 if (err != undefined) { 626 console.log("normalizeUri failed, error message : " + err); 627 }else{ 628 console.log("normalizeUri = " + data); 629 } 630}); 631``` 632 633### normalizeUri 634 635normalizeUri(uri: string): Promise<string> 636 637将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用Promise异步回调。 638 639**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 640 641**参数：** 642 643| 参数名 | 类型 | 必填 | 说明 | 644| ---- | ------ | ---- | ----------------------------------------- | 645| uri | string | 是 | 指示要规范化的[URI](js-apis-uri.md#uri)。 | 646 647**返回值：** 648 649| 类型 | 说明 | 650| ---------------- | ---------------------------------------------- | 651| Promise<string> | Promise对象。如果支持URI规范化，则返回规范化URI，否则返回空。 | 652 653**示例：** 654 655```ts 656import UIAbility from '@ohos.app.ability.UIAbility' 657let uri = ("datashare:///com.samples.datasharetest.DataShare"); 658dataShareHelper.normalizeUri(uri).then((data) => { 659 console.log("normalizeUri = " + data); 660}).catch((err) => { 661 console.log("normalizeUri failed, error message : " + err); 662}); 663``` 664 665### denormalizeUri 666 667denormalizeUri(uri: string, callback: AsyncCallback<string>): void 668 669将指定的URI转换为非规范化URI。使用callback异步回调。 670 671**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 672 673**参数：** 674 675| 参数名 | 类型 | 必填 | 说明 | 676| -------- | ---------------------- | ---- | --------------------------------------------------- | 677| uri | string | 是 | 指示要反规范化的[URI](js-apis-uri.md#uri)。 | 678| callback | AsyncCallback<string> | 是 | 回调函数。当将指定的URI转换为非规范化URI，err为undefined，data为获取到的反规范化URI（如果反规范化成功，则返回反规范化的URI；如果无需进行反规范化，则返回原始URI；若不支持则返回空）；否则为错误对象。 | 679 680**示例：** 681 682```ts 683import UIAbility from '@ohos.app.ability.UIAbility' 684let uri = ("datashare:///com.samples.datasharetest.DataShare"); 685dataShareHelper.denormalizeUri(uri, (err, data) => { 686 if (err != undefined) { 687 console.log("denormalizeUri failed, error message : " + err); 688 }else{ 689 console.log("denormalizeUri = " + data); 690 } 691}); 692``` 693 694### denormalizeUri 695 696denormalizeUri(uri: string): Promise<string> 697 698将指定的URI转换为非规范化URI。使用Promise异步回调。 699 700**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 701 702**参数：** 703 704| 参数名 | 类型 | 必填 | 说明 | 705| ---- | ------ | ---- | ------------------------------------------- | 706| uri | string | 是 | 指示要反规范化的[URI](js-apis-uri.md#uri)。 | 707 708**返回值：** 709 710| 类型 | 说明 | 711| ---------------- | ----------------------------------------- | 712| Promise<string> | Promise对象。如果反规范化成功，则返回反规范化的URI；如果无需执行任何操作，则返回原始URI；若不支持则返回空。 | 713 714**示例：** 715 716```ts 717import UIAbility from '@ohos.app.ability.UIAbility' 718let uri = ("datashare:///com.samples.datasharetest.DataShare"); 719dataShareHelper.denormalizeUri(uri).then((data) => { 720 console.log("denormalizeUri = " + data); 721}).catch((err) => { 722 console.log("denormalizeUri failed, error message : " + err); 723}); 724``` 725 726### notifyChange 727 728notifyChange(uri: string, callback: AsyncCallback<void>): void 729 730通知已注册的观察者指定URI对应的数据资源已发生变更。使用callback异步回调。 731 732**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 733 734**参数：** 735 736| 参数名 | 类型 | 必填 | 说明 | 737| -------- | -------------------- | ---- | ------------------------ | 738| uri | string | 是 | 表示指定的数据路径。 | 739| callback | AsyncCallback<void> | 是 | 回调函数。当通知已注册的观察者指定URI对应的数据资源已发生变更成功，err为undefined；否则为错误对象。 | 740 741**示例：** 742 743```ts 744import UIAbility from '@ohos.app.ability.UIAbility' 745let uri = ("datashare:///com.samples.datasharetest.DataShare"); 746dataShareHelper.notifyChange(uri, () => { 747 console.log("***** notifyChange *****"); 748}); 749``` 750 751### notifyChange 752 753notifyChange(uri: string): Promise<void> 754 755通知已注册的观察者指定URI对应的数据资源已发生变更。使用Promise异步回调。 756 757**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 758 759**参数：** 760 761| 参数名 | 类型 | 必填 | 说明 | 762| ---- | ------ | ---- | -------------------- | 763| uri | string | 是 | 表示指定的数据路径。 | 764 765**返回值：** 766 767| 类型 | 说明 | 768| -------------- | --------------------- | 769| Promise<void> | Promise对象。无返回结果的Promise对象。 | 770 771**示例：** 772 773```ts 774import UIAbility from '@ohos.app.ability.UIAbility' 775let uri = ("datashare:///com.samples.datasharetest.DataShare"); 776dataShareHelper.notifyChange(uri); 777```