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