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