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## dataShare.createDataShareHelper 21 22createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void 23 24创建DataShareHelper实例。使用callback异步回调。 25 26使用规则： 27 - 调用方应用位于后台时，使用该接口访问DataShareExtension需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 28 - 跨应用场景下，目标DataShareExtension的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 29 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 30 31**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 37| context | [Context](js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 38| uri | string | 是 | 指示要连接的服务端应用的路径。 | 39| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是 | 回调函数。当创建DataShareHelper实例成功，err为undefined，data为获取到的DataShareHelper实例；否则为错误对象。 | 40 41**错误码：** 42 43以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 44 45| 错误码ID | 错误信息 | 46| -------- | ---------------------------------------------------- | 47| 15700010 | The DataShareHelper is not initialized successfully. | 48 49**示例：** 50 51```ts 52import { BusinessError } from '@ohos.base' 53 54let uri = ("datashare:///com.samples.datasharetest.DataShare"); 55let dataShareHelper: dataShare.DataShareHelper | undefined = undefined; 56try { 57 dataShare.createDataShareHelper(this.context, uri, (err, data) => { 58 if (err !== undefined) { 59 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 60 return; 61 } 62 console.info("createDataShareHelper succeed, data : " + data); 63 dataShareHelper = data; 64 }); 65} catch (err) { 66 let code = (err as BusinessError).code; 67 let message = (err as BusinessError).message; 68 console.error(`createDataShareHelper error: code: ${code}, message: ${message} `); 69}; 70``` 71 72## dataShare.createDataShareHelper<sup>10+</sup> 73createDataShareHelper(context: Context, uri: string, options: DataShareHelperOptions, callback: AsyncCallback<DataShareHelper>): void 74 75创建DataShareHelper实例。使用callback异步回调。 76 77使用规则： 78 - 调用方应用位于后台时，使用该接口访问DataShareExtension需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 79 - 跨应用场景下，目标DataShareExtension的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 80 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 81 82**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 83 84 85| 参数名 | 类型 | 必填 | 说明 | 86| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 87| context | [Context](js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 88| uri | string | 是 | 指示要连接的服务端应用的路径。 | 89| options | [DataShareHelperOptions](#datasharehelperoptions10)| 是 | 可选配置。指定[DataShareHelper](#datasharehelper)是否在代理模式下。| 90| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是 | 回调函数。当创建DataShareHelper实例成功，err为undefined，data为获取到的DataShareHelper实例；否则为错误对象。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | ---------------------------------------------------- | 98| 15700010 | The DataShareHelper is not initialized successfully. | 99 100**示例：** 101 102```ts 103import { BusinessError } from '@ohos.base' 104 105let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 106let dataShareHelper: dataShare.DataShareHelper | undefined = undefined; 107try { 108 dataShare.createDataShareHelper(this.context, uri, {isProxy : true}, (err, data) => { 109 if (err !== undefined) { 110 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 111 return; 112 } 113 console.info("createDataShareHelper succeed, data : " + data); 114 dataShareHelper = data; 115 }); 116} catch (err) { 117 let code = (err as BusinessError).code; 118 let message = (err as BusinessError).message; 119 console.error(`createDataShareHelper error: code: ${code}, message: ${message} `); 120}; 121``` 122## dataShare.createDataShareHelper 123 124createDataShareHelper(context: Context, uri: string, options?: DataShareHelperOptions): Promise<DataShareHelper> 125 126创建DataShareHelper实例。使用Promise异步回调。 127 128使用规则： 129 - 调用方应用位于后台时，使用该接口访问DataShareExtension需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 130 - 跨应用场景下，目标DataShareExtension的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 131 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 132 133**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 134 135**参数：** 136 137| 参数名 | 类型 | 必填 | 说明 | 138| ------- | ------------------------------------------------- | ---- | ------------------------------ | 139| context | [Context](js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 140| uri | string | 是 | 指示要连接的服务端应用的路径。 | 141| options | [DataShareHelperOptions](#datasharehelperoptions10) | 否 | 可选配置。从API version 10开始支持此参数，如果不设置，则表示[DataShareHelper](#datasharehelper)不在代理模式下。| 142 143**返回值：** 144 145| 类型 | 说明 | 146| -------------------------------------------------- | -------------------------------------- | 147| Promise<[DataShareHelper](#datasharehelper)> | Promise对象。返回DataShareHelper实例。 | 148 149**错误码：** 150 151以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 152 153| 错误码ID | 错误信息 | 154| -------- | ---------------------------------------------------- | 155| 15700010 | The DataShareHelper is not initialized successfully. | 156 157**示例：** 158 159```ts 160import { BusinessError } from '@ohos.base' 161 162let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 163let dataShareHelper: dataShare.DataShareHelper | undefined = undefined; 164try { 165 dataShare.createDataShareHelper(this.context, uri, {isProxy : true}).then((data: dataShare.DataShareHelper) => { 166 console.info("createDataShareHelper succeed, data : " + data); 167 dataShareHelper = data; 168 }). catch((err: BusinessError) => { 169 console.error(`createDataShareHelper error: code: ${err.code}, message: ${err.message} `); 170 }); 171} catch (err) { 172 let code = (err as BusinessError).code; 173 let message = (err as BusinessError).message; 174 console.error(`createDataShareHelper error: code: ${code}, message: ${message} `); 175}; 176``` 177 178## DataShareHelperOptions<sup>10+</sup> 179 180指定[DataShareHelper](#datasharehelper)是否在代理模式下。 181 182**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 183 184| 名称 | 类型 | 必填 | 说明 | 185| -------- | -------- | -------- | -------- | 186| isProxy | boolean | 否 | 默认为false，如果为true，则要创建的[DataShareHelper](#datasharehelper)处于代理模式，所有操作都不会打开数据提供者APP，除非数据库不存在，当数据库不存在时，[createDataShareHelper](#datasharecreatedatasharehelper10)会拉起数据提供者创建数据库。 | 187 188## TemplateId<sup>10+</sup> 189 190标记模板的数据结构，TemplateId是在[addTemplate](#addtemplate10)中自动生成的，在[addTemplate](#addtemplate10)后，可以使用模板id来标记模板。 191 192**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 193 194| 名称 | 类型 | 必填 | 说明 | 195| -------- | -------- | -------- | -------- | 196| subscriberId | string | 是 | 指定处理回调的订阅者的id，与[addTemplate](#addtemplate10)中的subscriberId相同，每个订阅者的ID是唯一的。 | 197| bundleNameOfOwner | string | 是 | 指定创建模板的模板所有者的bundleName，与[addTemplate](#addtemplate10)中的bundleName相同。 | 198 199## PublishedItem<sup>10+</sup> 200 201指定发布的数据类型。 202 203**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 204 205| 名称 | 类型 | 必填 | 说明 | 206| -------- | -------- | -------- | -------- | 207| key | string | 是 | 指定发布数据的键。 | 208| data | string \| ArrayBuffer | 是 | 指定发布的数据。如果发布数据大小超过20KB，建议使用ArrayBuffer。 | 209| subscriberId | string | 是 | 指定订阅者id。 | 210 211## RdbDataChangeNode<sup>10+</sup> 212 213订阅/取消订阅RDB数据变更的结果。 214 215**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 216 217| 名称 | 类型 | 必填 | 说明 | 218| -------- | -------- | -------- | -------- | 219| uri | string | 是 | 指定回调的uri。 | 220| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 221| data | Array<string> | 是 | 指定回调的数据。 | 222 223## PublishedDataChangeNode<sup>10+</sup> 224 225订阅/取消订阅已发布数据变更的结果。 226 227**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 228 229| 名称 | 类型 | 必填 | 说明 | 230| -------- | -------- | -------- | -------- | 231| bundleName | string | 是 | 指定回调的bundleName。 | 232| data | Array<[PublishedItem](#publisheditem10)> | 是 | 指定回调的数据。 | 233 234## Template<sup>10+</sup> 235 236指定订阅中的模板结构。 237 238**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 239 240| 名称 | 类型 | 必填 | 说明 | 241| -------- | -------- | -------- | -------- | 242| predicates | { [key: string]: string } | 是 | 指定模板的谓词。当调用[on](#onrdbdatachange10)的回调时，谓词用于生成数据。仅适用于rdb存储数据。 | 243| scheduler | string | 是 | 指定模板的调度程序sql。其中嵌入自定义函数处理，目前预置自定义函数remindTimer处理。remindTimer在指定场景触发一次订阅刷新。<br/>触发场景：<br/>1. 修改数据时且有订阅的情况下触发对应的调度程序sql语句。<br/>2. 添加对应库第一个订阅的情况下触发对应的调度程序sql语句。 | 244 245## OperationResult<sup>10+</sup> 246 247订阅/取消订阅数据变更和发布数据的操作结果。 248 249**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 250 251| 名称 | 类型 | 必填 | 说明 | 252| -------- | -------- | ----- | -------- | 253| key | string | 是 | 指定运算结果的键。 | 254| result | number | 是 | 指定运算结果。正常情况下返回0，异常情况下返回错误码。 | 255## DataShareHelper 256 257DataShare管理工具实例，可使用此实例访问或管理服务端的数据。在调用DataShareHelper提供的方法前，需要先通过[createDataShareHelper](#datasharecreatedatasharehelper)构建一个实例。 258 259### on('dataChange') 260 261on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void 262 263订阅指定URI对应数据的数据变更事件。若用户（订阅者）已注册了观察者，当有其他用户触发了变更通知时（调用了下文中的notifyChange方法），订阅者将会接收到callback通知。使用callback异步回调。 264 265**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| -------- | -------------------- | ---- | ------------------------ | 271| type | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当数据更改时，触发该事件。 | 272| uri | string | 是 | 表示指定的数据路径。 | 273| callback | AsyncCallback<void> | 是 | 回调函数。当有其他用户触发了变更通知时调用，err为undefined；否则不被触发或为错误对象。 | 274 275**示例：** 276 277```ts 278let onCallback: () => void = (): void => { 279 console.info("**** Observer on callback ****"); 280} 281let uri = ("datashare:///com.samples.datasharetest.DataShare"); 282if (dataShareHelper !== undefined) { 283 (dataShareHelper as dataShare.DataShareHelper).on("dataChange", uri, onCallback); 284} 285``` 286 287### off('dataChange') 288 289off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void 290 291取消订阅指定URI下指定callback对应的数据资源的变更通知。 292 293**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 294 295**参数：** 296 297| 参数名 | 类型 | 必填 | 说明 | 298| -------- | -------------------- | ---- | ------------------------ | 299| type | string | 是 | 取消订阅的事件/回调类型，支持的事件为'dataChange'。 | 300| uri | string | 是 | 表示指定的数据路径。 | 301| callback | AsyncCallback<void> | 否 | 表示指定取消订阅的callback通知，如果为空，则取消订阅该uri下所有的通知事件。 | 302 303**示例：** 304 305```ts 306let callback: () => void = (): void => { 307 console.info("**** Observer on callback ****"); 308} 309let uri = ("datashare:///com.samples.datasharetest.DataShare"); 310if (dataShareHelper != undefined) { 311 (dataShareHelper as dataShare.DataShareHelper).on("dataChange", uri, callback); 312 (dataShareHelper as dataShare.DataShareHelper).off("dataChange", uri, callback); 313} 314``` 315 316### addTemplate<sup>10+</sup> 317 318addTemplate(uri: string, subscriberId: string, template: Template): void 319 320添加一个指定订阅者的数据模板。 321 322**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 323 324**参数：** 325 326| 参数名 | 类型 | 必填 | 说明 | 327| -------- | ------------------------ | ---- | -------------------------| 328| uri | string | 是 | 指示要插入的数据的路径。 | 329| subscriberId | string | 是 | 要添加模板的订阅者ID，每个订阅者的ID是唯一的。 | 330| template | [Template](#template10) | 是 | 要添加的数据模板。 | 331 332**错误码：** 333 334以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 335 336| 错误码ID | 错误信息 | 337| -------- | -------------------- | 338| 15700011 | The uri is not exist.| 339 340**示例：** 341 342```ts 343let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 344let subscriberId = '11'; 345let key1: string = "p1"; 346let value1: string = "select cityColumn as city_1, visitedCilumn as visited_1 from citys where like = true"; 347let key2: string = "p2"; 348let value2: string = "select cityColumn as city_2, visitedCilumn as visited_2 from citys where like = false"; 349let template: dataShare.Template = { 350 predicates : { 351 key1 : value1, 352 key2 : value2, 353 }, 354 scheduler : "select remindTimer(time) from TBL00" 355} 356if (dataShareHelper != undefined) { 357 (dataShareHelper as dataShare.DataShareHelper).addTemplate(uri, subscriberId, template); 358} 359``` 360 361### delTemplate<sup>10+</sup> 362 363delTemplate(uri: string, subscriberId: string): void 364 365删除一个指定订阅者的数据模板。 366 367**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 368 369**参数：** 370 371| 参数名 | 类型 | 必填 | 说明 | 372| -------- | -------------| ---- | ------------------------- | 373| uri | string | 是 | 指示要删除的数据的路径。 | 374| subscriberId | string | 是 | 订阅者ID，每个订阅者的ID是唯一的。 | 375 376**错误码：** 377 378以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 379 380| 错误码ID | 错误信息 | 381| -------- | -------------------- | 382| 15700011 | The uri is not exist.| 383 384**示例：** 385 386```ts 387let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 388let subscriberId = '11'; 389let key1: string = "p1"; 390let value1: string = "select cityColumn as city_1, visitedCilumn as visited_1 from citys where like = true"; 391let key2: string = "p2"; 392let value2: string = "select cityColumn as city_2, visitedCilumn as visited_2 from citys where like = false"; 393let template: dataShare.Template = { 394 predicates : { 395 key1 : value1, 396 key2 : value2, 397 }, 398 scheduler : "select remindTimer(time) from TBL00" 399} 400if (dataShareHelper != undefined) { 401 (dataShareHelper as dataShare.DataShareHelper).addTemplate(uri, subscriberId, template); 402 (dataShareHelper as dataShare.DataShareHelper).delTemplate(uri, subscriberId); 403} 404``` 405 406### on('rdbDataChange')<sup>10+</sup> 407 408on(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback: AsyncCallback<RdbDataChangeNode>): Array<OperationResult> 409 410订阅指定URI和模板对应的数据变更事件。 411 412**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| -------- | ----------------------------------| ---- | ------------------------------------------------------------ | 418| type | string | 是 | 订阅的事件类型，支持的事件为'rdbDataChange'，表示rdb数据的变更事件。type是固定值以外时，接口无响应。 | 419| uris | Array<string> | 是 | 要操作的数据的路径。 | 420| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 421| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | 是 | 回调函数。当触发变更通知时调用，err为undefined，node为订阅数据变更结果；否则不被触发或为错误对象。 | 422 423**返回值：** 424 425| 类型 | 说明 | 426| ---------------- | ------------------------------------------------------------ | 427| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 428 429**示例：** 430 431```ts 432import { BusinessError } from '@ohos.base' 433 434let onCallback: (err: BusinessError, node: dataShare.RdbDataChangeNode) => void = (err: BusinessError, node:dataShare.RdbDataChangeNode): void => { 435 console.info("onCallback " + JSON.stringify(node.uri)); 436 console.info("onCallback " + JSON.stringify(node.templateId)); 437 console.info("onCallback " + node.data.length); 438 for (let i = 0; i < node.data.length; i++) { 439 console.info("onCallback " + typeof node.data[i] + " " + node.data[i]); 440 } 441} 442 443let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 444let templateId:dataShare.TemplateId = {subscriberId:"11", bundleNameOfOwner:"com.acts.ohos.data.datasharetest"}; 445if (dataShareHelper != undefined) { 446 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).on("rdbDataChange", [uri], templateId, onCallback); 447} 448``` 449 450### off('rdbDataChange')<sup>10+</sup> 451 452off(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback?: AsyncCallback<RdbDataChangeNode>): Array<OperationResult> 453 454取消订阅指定URI和模板对应的数据变更事件。 455 456**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 457 458**参数：** 459 460| 参数名 | 类型 | 必填 | 说明 | 461| -------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | 462| type | string | 是 | 取消订阅的事件类型，支持的事件为'rdbDataChange'，表示rdb数据的变更事件。 | 463| uris | Array<string> | 是 | 要操作的数据的路径。 | 464| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 465| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | 否 | 回调函数。表示指定取消订阅的callback通知，如果为空，则取消订阅该uri下所有的通知事件。 | 466 467**返回值：** 468 469| 类型 | 说明 | 470| ---------------- | ------------------------------------------------------------ | 471| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 472 473**示例：** 474 475```ts 476let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 477let templateId:dataShare.TemplateId = {subscriberId:"11", bundleNameOfOwner:"com.acts.ohos.data.datasharetest"}; 478if (dataShareHelper != undefined) { 479 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).off("rdbDataChange", [uri], templateId); 480} 481``` 482 483### on('publishedDataChange')<sup>10+</sup> 484 485on(type: 'publishedDataChange', uris: Array<string>, subscriberId: string, callback: AsyncCallback<PublishedDataChangeNode>): Array<OperationResult> 486 487订阅已发布数据的数据变更通知。 488 489**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 490 491**参数：** 492 493| 参数名 | 类型 | 必填 | 说明 | 494| -------- | ----------------------------------| ---- | ------------------------------------------------------------ | 495| type | string | 是 | 订阅的事件类型，支持的事件为'publishedDataChange'，表示已发布数据的变更事件。 | 496| uris | Array<string> | 是 | 要操作的数据的路径。 | 497| subscriberId | string | 是 | 指定处理回调的用户ID。 | 498| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | 是 | 回调函数。当触发变更通知时调用，err为undefined，node为订阅数据变更结果；否则不被触发或为错误对象。 | 499 500**返回值：** 501 502| 类型 | 说明 | 503| ---------------- | ------------------------------------------------------------ | 504| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 505 506**示例：** 507 508```ts 509import { BusinessError } from '@ohos.base' 510 511let onPublishCallback: (err: BusinessError, node: dataShare.PublishedDataChangeNode) => void = (err: BusinessError, node:dataShare.PublishedDataChangeNode): void => { 512 console.info("onPublishCallback node bundleName " + JSON.stringify(node.bundleName)); 513 console.info("onPublishCallback node data size" + node.data.length); 514 for (let i = 0; i < node.data.length; i++) { 515 console.info("onPublishCallback node " + typeof node.data[i].data); 516 if (typeof node.data[i].data != 'string') { 517 let array: ArrayBuffer = node.data[i].data as ArrayBuffer; 518 let data: Uint8Array = new Uint8Array(array); 519 console.info("onPublishCallback " + i + " " + JSON.stringify(data)); 520 } 521 console.info("onPublishCallback data " + i + " " + JSON.stringify(node.data[i])); 522 } 523} 524let uris:Array<string> = ['city', 'datashareproxy://com.acts.ohos.data.datasharetest/appInfo', 'key2']; 525let subscriberId = '11'; 526if (dataShareHelper != undefined) { 527 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).on('publishedDataChange', uris, subscriberId, onPublishCallback); 528} 529``` 530 531### off('publishedDataChange')<sup>10+</sup> 532 533off(type: 'publishedDataChange', uris: Array<string>, subscriberId: string, callback?: AsyncCallback<PublishedDataChangeNode>): Array<OperationResult> 534 535取消订阅已发布数据的数据变更通知。 536 537**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 538 539**参数：** 540 541| 参数名 | 类型 | 必填 | 说明 | 542| -------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | 543| type | string | 是 | 取消订阅的事件类型，支持的事件为'publishedDataChange'，表示已发布数据的变更事件。| 544| uris | Array<string> | 是 | 要操作的数据的路径。 | 545| subscriberId | string | 是 | 指定处理回调的用户ID。 | 546| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | 否 | 回调函数。表示指定取消订阅的callback通知，如果为空，则取消订阅该uri下所有的通知事件。 | 547 548**返回值：** 549 550| 类型 | 说明 | 551| ---------------- | ------------------------------------------------------------ | 552| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 553 554**示例：** 555 556```ts 557import { BusinessError } from '@ohos.base' 558 559let offCallback: (err: BusinessError, node: dataShare.PublishedDataChangeNode) => void = (err: BusinessError, node:dataShare.PublishedDataChangeNode): void => { 560 console.info("**** Observer off callback ****"); 561} 562let uris:Array<string> = ["city", "datashareproxy://com.acts.ohos.data.datasharetest/appInfo", "key2"]; 563let subscriberId = '11'; 564if (dataShareHelper != undefined) { 565 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).off("publishedDataChange", uris, subscriberId, offCallback); 566} 567``` 568 569### publish<sup>10+</sup> 570 571publish(data: Array<PublishedItem>, bundleName: string, version: number, callback: AsyncCallback<Array<OperationResult>>): void 572 573发布数据，将数据更新至数据库。 574 575**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 576 577**参数：** 578 579| 参数名 | 类型 | 必填 | 说明 | 580| --------- | -------------------------------------------------| ---- | ------------------- | 581| data | Array<[PublishedItem](#publisheditem10)> | 是 | 指示要发布的数据。 | 582| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 583| version | number | 是 | 指示要发布的数据版本，越大表示数据版本越新。如果发布的版本号小于数据库中的记录，则更新失败。 | 584| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | 是 | 回调函数。当发布数据时调用，err为undefined，result为发布数据结果；否则不被触发或为错误对象。 | 585 586**错误码：** 587 588以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 589 590| 错误码ID | 错误信息 | 591| -------- | -------------------------- | 592| 15700012 | The data area is not exist.| 593 594**示例：** 595 596```ts 597import { BusinessError } from '@ohos.base' 598 599let arrayBuffer = new ArrayBuffer(1); 600let version = 1; 601let dataArray : Array<dataShare.PublishedItem> = [{key:"key2", subscriberId:"11", data:arrayBuffer}]; 602let publishCallback: (err: BusinessError, result: Array<dataShare.OperationResult>) => void = (err: BusinessError, result: Array<dataShare.OperationResult>): void => { 603 console.info("publishCallback " + JSON.stringify(result)); 604} 605try { 606 console.info("dataArray length is:", dataArray.length); 607 if (dataShareHelper != undefined) { 608 (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest", version, publishCallback); 609 } 610} catch (e) { 611 console.error("publish error " + JSON.stringify(e)); 612} 613``` 614 615### publish<sup>10+</sup> 616 617publish(data: Array<PublishedItem>, bundleName: string, callback: AsyncCallback<Array<OperationResult>>): void 618 619发布数据，将数据更新至数据库。 620 621**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 622 623**参数：** 624 625| 参数名 | 类型 | 必填 | 说明 | 626| -------- | ------------------------------------------------- | ---- | ---------------------------------- | 627| data | Array<[PublishedItem](#publisheditem10)> | 是 | 指示要发布的数据。 | 628| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 629| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | 是 | 回调函数。当发布数据时调用，err为undefined，result为发布数据结果；否则不被触发或为错误对象。 | 630 631**示例：** 632 633**错误码：** 634 635以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 636 637| 错误码ID | 错误信息 | 638| -------- | -------------------------- | 639| 15700012 | The data area is not exist.| 640 641```ts 642import { BusinessError } from '@ohos.base' 643 644let publishCallback: (err: BusinessError, result: Array<dataShare.OperationResult>) => void = (err: BusinessError, result: Array<dataShare.OperationResult>): void => { 645 console.info("publishCallback " + JSON.stringify(result)); 646} 647let dataArray : Array<dataShare.PublishedItem> = [ 648 {key:"city", subscriberId:"11", data:"xian"}, 649 {key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo", subscriberId:"11", data:"appinfo is just a test app"}, 650 {key:"empty", subscriberId:"11", data:"nobody sub"}]; 651if (dataShareHelper != undefined) { 652 (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest", publishCallback); 653} 654``` 655 656### publish<sup>10+</sup> 657 658publish(data: Array<PublishedItem>, bundleName: string, version?: number): Promise<Array<OperationResult>> 659 660发布数据，将数据更新至数据库。 661 662**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 663 664**参数：** 665 666| 参数名 | 类型 | 必填 | 说明 | 667| -------- | ----------------------------- | ---- | ------------------------------ | 668| data | Array<[PublishedItem](#publisheditem10)> | 是 | 指示要发布的数据。| 669| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 670| version | number | 否 | 指示要发布的数据版本，越大表示数据版本越新。如果发布的版本号小于数据库中的记录，则更新失败。<br/> 如果不检查要发布的数据版本，则不填。 | 671 672**返回值：** 673 674| 类型 | 说明 | 675| ---------------- | ------------------------------------------------------------ | 676| Promise<Array<[OperationResult](#operationresult10)>> | 发布数据结果。| 677 678**错误码：** 679 680以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 681 682| 错误码ID | 错误信息 | 683| -------- | -------------------------- | 684| 15700012 | The data area is not exist.| 685 686**示例：** 687 688```ts 689let dataArray: Array<dataShare.PublishedItem> = [ 690 {key:"city", subscriberId:"11", data:"xian"}, 691 {key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo", subscriberId:"11", data:"appinfo is just a test app"}, 692 {key:"empty", subscriberId:"11", data:"nobody sub"}]; 693if (dataShareHelper != undefined) { 694 let result: Promise<Array<dataShare.OperationResult>> = (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest"); 695} 696``` 697 698### getPublishedData<sup>10+</sup> 699 700getPublishedData(bundleName: string, callback: AsyncCallback<Array<PublishedItem>>): void 701 702获取给定的APP和模板指定的数据。 703 704**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 705 706**参数：** 707 708| 参数名 | 类型 | 必填 | 说明 | 709| -------- | -----------------| ---- | ----------------------------- | 710| bundleName | string | 是 | 表示数据所属的APP。 | 711| callback | AsyncCallback<Array<[PublishedItem](#publisheditem10)>> | 是 | 回调函数。 | 712 713**错误码：** 714 715以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 716 717| 错误码ID | 错误信息 | 718| -------- | -------------------------- | 719| 15700012 | The data area is not exist.| 720 721**示例：** 722 723```ts 724import { BusinessError } from '@ohos.base' 725 726let publishCallback: (err: BusinessError, data: Array<dataShare.PublishedItem>) => void = (err: BusinessError, result: Array<dataShare.PublishedItem>): void => { 727 console.info("**** Observer publish callback ****"); 728} 729if (dataShareHelper != undefined) { 730 (dataShareHelper as dataShare.DataShareHelper).getPublishedData("com.acts.ohos.data.datasharetest", publishCallback); 731} 732``` 733 734### getPublishedData<sup>10+</sup> 735 736getPublishedData(bundleName: string): Promise<Array<PublishedItem>> 737 738获取给定的APP和模板指定的数据。 739 740**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 741 742**参数：** 743 744| 参数名 | 类型 | 必填 | 说明 | 745| -------- | --------------| ---- | -------------------------------------- | 746| bundleName | string | 是 | 表示数据所属的APP。 | 747 748**返回值：** 749 750| 类型 | 说明 | 751| ---------------- | ------------------------------------------------------------ | 752| Promise<Array<[PublishedItem](#publisheditem10)>> | Promise对象。返回给定的APP和模板指定的数据。| 753 754**错误码：** 755 756以下错误码的详细介绍请参见[数据共享错误码](../errorcodes/errorcode-datashare.md)。 757 758| 错误码ID | 错误信息 | 759| -------- | -------------------------- | 760| 15700012 | The data area is not exist.| 761 762**示例：** 763 764```ts 765if (dataShareHelper != undefined) { 766 let publishedData: Promise<Array<dataShare.PublishedItem>> = (dataShareHelper as dataShare.DataShareHelper).getPublishedData("com.acts.ohos.data.datasharetest"); 767} 768``` 769 770### insert 771 772insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void 773 774将单条数据插入数据库。使用callback异步回调。 775 776**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 782| uri | string | 是 | 指示要插入的数据的路径。 | 783| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。如果此参数为空，将插入一个空行。 | 784| callback | AsyncCallback<number> | 是 | 回调函数。当将单条数据插入数据库成功，err为undefined，data为获取到的插入数据记录的索引；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此callback也无法返回索引值。 | 785 786**示例：** 787 788```ts 789import { ValuesBucket } from '@ohos.data.ValuesBucket' 790import { BusinessError } from '@ohos.base' 791 792let uri = ("datashare:///com.samples.datasharetest.DataShare"); 793let key1: string = "name"; 794let value1: string = "rose"; 795let key2: string = "age"; 796let value2: number = 22; 797let key3: string = "salary"; 798let value3: number = 200.5; 799const valueBucket: ValuesBucket = { 800 key1: value1, 801 key2: value2, 802 key3: value3, 803} 804try { 805 if (dataShareHelper != undefined) { 806 (dataShareHelper as dataShare.DataShareHelper).insert(uri, valueBucket, (err: BusinessError, data: number) => { 807 if (err !== undefined) { 808 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 809 return; 810 } 811 console.info("insert succeed, data : " + data); 812 }); 813 } 814} catch (err) { 815 let code = (err as BusinessError).code; 816 let message = (err as BusinessError).message; 817 console.error(`insert error: code: ${code}, message: ${message} `); 818}; 819``` 820 821### insert 822 823insert(uri: string, value: ValuesBucket): Promise<number> 824 825将单条数据插入数据库。使用Promise异步回调。 826 827**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 828 829**参数：** 830 831| 参数名 | 类型 | 必填 | 说明 | 832| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- | 833| uri | string | 是 | 指示要插入的数据的路径。 | 834| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要插入的数据。如果此参数为空，将插入一个空行。 | 835 836**返回值：** 837 838| 类型 | 说明 | 839| ---------------- | ------------------------------------------------------------ | 840| Promise<number> | Promise对象。返回插入数据记录的索引。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此Promise也无法返回索引值。 | 841 842**示例：** 843 844```ts 845import { BusinessError } from '@ohos.base' 846import { ValuesBucket } from '@ohos.data.ValuesBucket' 847 848let uri = ("datashare:///com.samples.datasharetest.DataShare"); 849let key1: string = "name"; 850let value1: string = "rose1"; 851let key2: string = "age"; 852let value2: number = 21; 853let key3: string = "salary"; 854let value3: number = 20.5; 855const valueBucket: ValuesBucket = { 856 key1: value1, 857 key2: value2, 858 key3: value3, 859} 860try { 861 if (dataShareHelper != undefined) { 862 (dataShareHelper as dataShare.DataShareHelper).insert(uri, valueBucket).then((data: number) => { 863 console.info("insert succeed, data : " + data); 864 }).catch((err: BusinessError) => { 865 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 866 }); 867 } 868} catch (err) { 869 let code = (err as BusinessError).code; 870 let message = (err as BusinessError).message; 871 console.error(`insert error: code: ${code}, message: ${message} `); 872}; 873``` 874 875### delete 876 877delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 878 879从数据库中删除一条或多条数据记录。使用callback异步回调。 880 881**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 882 883**参数：** 884 885| 参数名 | 类型 | 必填 | 说明 | 886| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 887| uri | string | 是 | 指示要删除的数据的路径。 | 888| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。 | 889| callback | AsyncCallback<number> | 是 | 回调函数。当从数据库中删除一条或多条数据记录成功，err为undefined，data为获取到的已删除的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回删除的数据记录数。 | 890 891**示例：** 892 893```ts 894import dataSharePredicates from '@ohos.data.dataSharePredicates'; 895import { BusinessError } from '@ohos.base' 896 897let uri = ("datashare:///com.samples.datasharetest.DataShare"); 898let da = new dataSharePredicates.DataSharePredicates(); 899da.equalTo("name", "ZhangSan"); 900try { 901 if (dataShareHelper != undefined) { 902 (dataShareHelper as dataShare.DataShareHelper).delete(uri, da, (err: BusinessError, data: number) => { 903 if (err !== undefined) { 904 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 905 return; 906 } 907 console.info("delete succeed, data : " + data); 908 }); 909 } 910} catch (err) { 911 let code = (err as BusinessError).code; 912 let message = (err as BusinessError).message; 913 console.error(`delete error: code: ${code}, message: ${message} `); 914}; 915``` 916 917### delete 918 919delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number> 920 921从数据库中删除一条或多条数据记录。使用Promise异步回调。 922 923**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 924 925**参数：** 926 927| 参数名 | 类型 | 必填 | 说明 | 928| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 929| uri | string | 是 | 指示要删除的数据的路径。 | 930| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。 | 931 932**返回值：** 933 934| 类型 | 说明 | 935| ---------------- | ------------------------------------------------------------ | 936| Promise<number> | Promise对象。返回已删除的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回删除的数据记录数。 | 937 938**示例：** 939 940```ts 941import dataSharePredicates from '@ohos.data.dataSharePredicates'; 942import { BusinessError } from '@ohos.base' 943 944let uri = ("datashare:///com.samples.datasharetest.DataShare"); 945let da = new dataSharePredicates.DataSharePredicates(); 946da.equalTo("name", "ZhangSan"); 947try { 948 if (dataShareHelper != undefined) { 949 (dataShareHelper as dataShare.DataShareHelper).delete(uri, da).then((data: number) => { 950 console.info("delete succeed, data : " + data); 951 }).catch((err: BusinessError) => { 952 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 953 }); 954 } 955} catch (err) { 956 let code = (err as BusinessError).code; 957 let message = (err as BusinessError).message; 958 console.error(`delete error: code: ${code}, message: ${message} `); 959}; 960``` 961 962### query 963 964query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void 965 966查询数据库中的数据。使用callback异步回调。 967 968**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 969 970**参数：** 971 972| 参数名 | 类型 | 必填 | 说明 | 973| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 974| uri | string | 是 | 指示要查询的数据的路径。 | 975| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。 | 976| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 | 977| callback | AsyncCallback<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | 是 | 回调函数。当查询数据库中的数据成功，err为undefined，data为获取到的查询到的结果集；否则为错误对象。 | 978 979**示例：** 980 981```ts 982import dataSharePredicates from '@ohos.data.dataSharePredicates'; 983import { BusinessError } from '@ohos.base' 984import DataShareResultSet from '@ohos.data.DataShareResultSet' 985 986let uri = ("datashare:///com.samples.datasharetest.DataShare"); 987let columns = ["*"]; 988let da = new dataSharePredicates.DataSharePredicates(); 989da.equalTo("name", "ZhangSan"); 990try { 991 if (dataShareHelper != undefined) { 992 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns, (err: BusinessError, data: DataShareResultSet) => { 993 if (err !== undefined) { 994 console.error(`query error: code: ${err.code}, message: ${err.message} `); 995 return; 996 } 997 console.info("query succeed, rowCount : " + data.rowCount); 998 }); 999 } 1000} catch (err) { 1001 let code = (err as BusinessError).code; 1002 let message = (err as BusinessError).message; 1003 console.error(`query error: code: ${code}, message: ${message} `); 1004}; 1005``` 1006 1007### query 1008 1009query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet> 1010 1011查询数据库中的数据。使用Promise异步回调。 1012 1013**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1014 1015**参数：** 1016 1017| 参数名 | 类型 | 必填 | 说明 | 1018| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1019| uri | string | 是 | 指示要查询的数据的路径。 | 1020| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。 | 1021| columns | Array<string> | 是 | 指示要查询的列。如果此参数为空，则查询所有列。 | 1022 1023**返回值：** 1024 1025| 类型 | 说明 | 1026| ------------------------------------------------------------ | --------------------------------- | 1027| Promise<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Promise对象。返回查询到的结果集。 | 1028 1029**示例：** 1030 1031```ts 1032import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1033import { BusinessError } from '@ohos.base' 1034import DataShareResultSet from '@ohos.data.DataShareResultSet' 1035 1036let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1037let columns = ["*"]; 1038let da = new dataSharePredicates.DataSharePredicates(); 1039da.equalTo("name", "ZhangSan"); 1040try { 1041 if (dataShareHelper != undefined) { 1042 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns).then((data: DataShareResultSet) => { 1043 console.info("query succeed, rowCount : " + data.rowCount); 1044 }).catch((err: BusinessError) => { 1045 console.error(`query error: code: ${err.code}, message: ${err.message} `); 1046 }); 1047 } 1048} catch (err) { 1049 let code = (err as BusinessError).code; 1050 let message = (err as BusinessError).message; 1051 console.error(`query error: code: ${code}, message: ${message} `); 1052}; 1053``` 1054 1055### update 1056 1057update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void 1058 1059更新数据库中的数据记录。使用callback异步回调。 1060 1061**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1062 1063**参数：** 1064 1065| 参数名 | 类型 | 必填 | 说明 | 1066| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1067| uri | string | 是 | 指示要更新的数据的路径。 | 1068| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。 | 1069| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 | 1070| callback | AsyncCallback<number> | 是 | 回调函数。当更新数据库中的数据记录成功，err为undefined，data为获取到的更新的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回更新的数据记录数。 | 1071 1072**示例：** 1073 1074```ts 1075import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1076import { BusinessError } from '@ohos.base' 1077import { ValuesBucket } from '@ohos.data.ValuesBucket' 1078 1079let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1080let da = new dataSharePredicates.DataSharePredicates(); 1081da.equalTo("name", "ZhangSan"); 1082let key1: string = "name"; 1083let value1: string = "roe1" 1084let key2: string = "age"; 1085let value2: number = 21 1086let key3: string = "salary"; 1087let value3: number = 20.5; 1088const va: ValuesBucket = { 1089 key1: value1, 1090 key2: value2, 1091 key3: value3, 1092} 1093try { 1094 if (dataShareHelper != undefined) { 1095 (dataShareHelper as dataShare.DataShareHelper).update(uri, da, va, (err: BusinessError, data: number) => { 1096 if (err !== undefined) { 1097 console.error(`update error: code: ${err.code}, message: ${err.message} `); 1098 return; 1099 } 1100 console.info("update succeed, data : " + data); 1101 }); 1102 } 1103} catch (err) { 1104 let code = (err as BusinessError).code; 1105 let message = (err as BusinessError).message; 1106 console.error(`update error: code: ${code}, message: ${message} `); 1107}; 1108``` 1109 1110### update 1111 1112update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number> 1113 1114更新数据库中的数据记录。使用Promise异步回调。 1115 1116**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1117 1118**参数：** 1119 1120| 参数名 | 类型 | 必填 | 说明 | 1121| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1122| uri | string | 是 | 指示要更新的数据的路径。 | 1123| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。 | 1124| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 指示要更新的数据。 | 1125 1126**返回值：** 1127 1128| 类型 | 说明 | 1129| ---------------- | ------------------------------------------------------------ | 1130| Promise<number> | Promise对象。返回更新的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回更新的数据记录数。 | 1131 1132**示例：** 1133 1134```ts 1135import dataSharePredicates from '@ohos.data.dataSharePredicates'; 1136import { ValuesBucket } from '@ohos.data.ValuesBucket' 1137import { BusinessError } from '@ohos.base' 1138 1139let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1140let da = new dataSharePredicates.DataSharePredicates(); 1141da.equalTo("name", "ZhangSan"); 1142let key1: string = "name"; 1143let value1: string = "roe1" 1144let key2: string = "age"; 1145let value2: number = 21 1146let key3: string = "salary"; 1147let value3: number = 20.5; 1148const va: ValuesBucket = { 1149 key1: value1, 1150 key2: value2, 1151 key3: value3, 1152} 1153try { 1154 if (dataShareHelper != undefined) { 1155 (dataShareHelper as dataShare.DataShareHelper).update(uri, da, va).then((data: number) => { 1156 console.info("update succeed, data : " + data); 1157 }).catch((err: BusinessError) => { 1158 console.error(`update error: code: ${err.code}, message: ${err.message} `); 1159 }); 1160 } 1161} catch (err) { 1162 let code = (err as BusinessError).code; 1163 let message = (err as BusinessError).message; 1164 console.error(`update error: code: ${code}, message: ${message} `); 1165}; 1166``` 1167 1168### batchInsert 1169 1170batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void 1171 1172将批量数据插入数据库。使用callback异步回调。暂不支持静默访问。 1173 1174**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1175 1176**参数：** 1177 1178| 参数名 | 类型 | 必填 | 说明 | 1179| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1180| uri | string | 是 | 指示要插入的数据的路径。 | 1181| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 指示要插入的数据。 | 1182| callback | AsyncCallback<number> | 是 | 回调函数。当将批量数据插入数据库成功，err为undefined，data为获取到的插入的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 1183 1184**示例：** 1185 1186```ts 1187import { ValuesBucket } from '@ohos.data.ValuesBucket' 1188import { BusinessError } from '@ohos.base' 1189 1190let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1191let key1: string = "name"; 1192let value11: string = "roe11" 1193let key2: string = "age"; 1194let value21: number = 21; 1195let key3: string = "salary"; 1196let value31: number = 20.5; 1197let valuesBucket1: ValuesBucket = { 1198 key1: value11, 1199 key2: value21, 1200 key3: value31, 1201} 1202let vbs = new Array(valuesBucket1); 1203try { 1204 if (dataShareHelper != undefined) { 1205 (dataShareHelper as dataShare.DataShareHelper).batchInsert(uri, vbs, (err, data) => { 1206 if (err !== undefined) { 1207 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 1208 return; 1209 } 1210 console.info("batchInsert succeed, data : " + data); 1211 }); 1212 } 1213} catch (err) { 1214 let code = (err as BusinessError).code; 1215 let message = (err as BusinessError).message; 1216 console.error(`batchInsert error: code: ${code}, message: ${message} `); 1217}; 1218``` 1219 1220### batchInsert 1221 1222batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number> 1223 1224将批量数据插入数据库。使用Promise异步回调。暂不支持静默访问。 1225 1226**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1227 1228**参数：** 1229 1230| 参数名 | 类型 | 必填 | 说明 | 1231| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 1232| uri | string | 是 | 指示要插入的数据的路径。 | 1233| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 指示要插入的数据。 | 1234 1235**返回值：** 1236 1237| 类型 | 说明 | 1238| ---------------- | ------------------------------------------------------------ | 1239| Promise<number> | Promise对象。返回插入的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 1240 1241**示例：** 1242 1243```ts 1244import { ValuesBucket } from '@ohos.data.ValuesBucket' 1245import { BusinessError } from '@ohos.base' 1246 1247let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1248let key1: string = "name"; 1249let value11: string = "roe11" 1250let key2: string = "age"; 1251let value21: number = 21; 1252let key3: string = "salary"; 1253let value31: number = 20.5; 1254let valuesBucket1: ValuesBucket = { 1255 key1: value11, 1256 key2: value21, 1257 key3: value31, 1258} 1259let vbs = new Array(valuesBucket1); 1260try { 1261 if (dataShareHelper != undefined) { 1262 (dataShareHelper as dataShare.DataShareHelper).batchInsert(uri, vbs).then((data: number) => { 1263 console.info("batchInsert succeed, data : " + data); 1264 }).catch((err: BusinessError) => { 1265 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 1266 }); 1267 } 1268} catch (err) { 1269 let code = (err as BusinessError).code; 1270 let message = (err as BusinessError).message 1271 console.error(`batchInsert error: code: ${code}, message: ${message} `); 1272}; 1273``` 1274 1275### normalizeUri 1276 1277normalizeUri(uri: string, callback: AsyncCallback<string>): void 1278 1279将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用callback异步回调。暂不支持静默访问。 1280 1281**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1282 1283**参数：** 1284 1285| 参数名 | 类型 | 必填 | 说明 | 1286| -------- | ---------------------- | ---- | -------------------------------------------------------- | 1287| uri | string | 是 | 指示要规范化的[URI](js-apis-uri.md#uri)。 | 1288| callback | AsyncCallback<string> | 是 | 回调函数。当将给定的DataShare URI转换为规范化URI成功，err为undefined，data为获取到的规范化URI（如果支持URI规范化，则返回规范化URI，否则返回空）；否则为错误对象。 | 1289 1290**示例：** 1291 1292```ts 1293import { BusinessError } from '@ohos.base' 1294 1295let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1296if (dataShareHelper != undefined) { 1297 (dataShareHelper as dataShare.DataShareHelper).normalizeUri(uri, (err: BusinessError, data: string) => { 1298 if (err !== undefined) { 1299 console.info("normalizeUri failed, error message : " + err); 1300 } else { 1301 console.info("normalizeUri = " + data); 1302 } 1303 }); 1304} 1305``` 1306 1307### normalizeUri 1308 1309normalizeUri(uri: string): Promise<string> 1310 1311将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用Promise异步回调。暂不支持静默访问。 1312 1313**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1314 1315**参数：** 1316 1317| 参数名 | 类型 | 必填 | 说明 | 1318| ---- | ------ | ---- | ----------------------------------------- | 1319| uri | string | 是 | 指示要规范化的[URI](js-apis-uri.md#uri)。 | 1320 1321**返回值：** 1322 1323| 类型 | 说明 | 1324| ---------------- | ---------------------------------------------- | 1325| Promise<string> | Promise对象。如果支持URI规范化，则返回规范化URI，否则返回空。 | 1326 1327**示例：** 1328 1329```ts 1330import { BusinessError } from '@ohos.base' 1331 1332let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1333if (dataShareHelper != undefined) { 1334 (dataShareHelper as dataShare.DataShareHelper).normalizeUri(uri).then((data: string) => { 1335 console.info("normalizeUri = " + data); 1336 }).catch((err: BusinessError) => { 1337 console.info("normalizeUri failed, error message : " + err); 1338 }); 1339} 1340``` 1341 1342### denormalizeUri 1343 1344denormalizeUri(uri: string, callback: AsyncCallback<string>): void 1345 1346将指定的URI转换为非规范化URI。使用callback异步回调。暂不支持静默访问。 1347 1348**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1349 1350**参数：** 1351 1352| 参数名 | 类型 | 必填 | 说明 | 1353| -------- | ---------------------- | ---- | --------------------------------------------------- | 1354| uri | string | 是 | 指示要反规范化的[URI](js-apis-uri.md#uri)。 | 1355| callback | AsyncCallback<string> | 是 | 回调函数。当将指定的URI转换为非规范化URI，err为undefined，data为获取到的反规范化URI（如果反规范化成功，则返回反规范化的URI；如果无需进行反规范化，则返回原始URI；若不支持则返回空）；否则为错误对象。 | 1356 1357**示例：** 1358 1359```ts 1360import { BusinessError } from '@ohos.base' 1361 1362let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1363if (dataShareHelper != undefined) { 1364 (dataShareHelper as dataShare.DataShareHelper).denormalizeUri(uri, (err: BusinessError, data: string) => { 1365 if (err !== undefined) { 1366 console.error("denormalizeUri failed, error message : " + err); 1367 } else { 1368 console.info("denormalizeUri = " + data); 1369 } 1370 }); 1371} 1372``` 1373 1374### denormalizeUri 1375 1376denormalizeUri(uri: string): Promise<string> 1377 1378将指定的URI转换为非规范化URI。使用Promise异步回调。暂不支持静默访问。 1379 1380**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1381 1382**参数：** 1383 1384| 参数名 | 类型 | 必填 | 说明 | 1385| ---- | ------ | ---- | ------------------------------------------- | 1386| uri | string | 是 | 指示要反规范化的[URI](js-apis-uri.md#uri)。 | 1387 1388**返回值：** 1389 1390| 类型 | 说明 | 1391| ---------------- | ----------------------------------------- | 1392| Promise<string> | Promise对象。如果反规范化成功，则返回反规范化的URI；如果无需执行任何操作，则返回原始URI；若不支持则返回空。 | 1393 1394**示例：** 1395 1396```ts 1397import { BusinessError } from '@ohos.base' 1398 1399let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1400if (dataShareHelper != undefined) { 1401 (dataShareHelper as dataShare.DataShareHelper).denormalizeUri(uri).then((data: string) => { 1402 console.info("denormalizeUri = " + data); 1403 }).catch((err: BusinessError) => { 1404 console.error("denormalizeUri failed, error message : " + err); 1405 }); 1406} 1407``` 1408 1409### notifyChange 1410 1411notifyChange(uri: string, callback: AsyncCallback<void>): void 1412 1413通知已注册的观察者指定URI对应的数据资源已发生变更。使用callback异步回调。暂不支持静默访问。 1414 1415**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1416 1417**参数：** 1418 1419| 参数名 | 类型 | 必填 | 说明 | 1420| -------- | -------------------- | ---- | ------------------------ | 1421| uri | string | 是 | 表示指定的数据路径。 | 1422| callback | AsyncCallback<void> | 是 | 回调函数。当通知已注册的观察者指定URI对应的数据资源已发生变更成功，err为undefined；否则为错误对象。 | 1423 1424**示例：** 1425 1426```ts 1427let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1428if (dataShareHelper != undefined) { 1429 (dataShareHelper as dataShare.DataShareHelper).notifyChange(uri, () => { 1430 console.info("***** notifyChange *****"); 1431 }); 1432} 1433``` 1434 1435### notifyChange 1436 1437notifyChange(uri: string): Promise<void> 1438 1439通知已注册的观察者指定URI对应的数据资源已发生变更。使用Promise异步回调。暂不支持静默访问。 1440 1441**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1442 1443**参数：** 1444 1445| 参数名 | 类型 | 必填 | 说明 | 1446| ---- | ------ | ---- | -------------------- | 1447| uri | string | 是 | 表示指定的数据路径。 | 1448 1449**返回值：** 1450 1451| 类型 | 说明 | 1452| -------------- | --------------------- | 1453| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1454 1455**示例：** 1456 1457```ts 1458let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1459if (dataShareHelper != undefined) { 1460 (dataShareHelper as dataShare.DataShareHelper).notifyChange(uri); 1461} 1462```