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 '@kit.ArkData'; 18``` 19 20## dataShare.createDataShareHelper 21 22createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void 23 24创建DataShareHelper实例。使用callback异步回调。 25 26> **说明：** 27> 28> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 29 30**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 36| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 37| uri | string | 是 | 要连接的服务端应用的路径。 | 38| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是 | 回调函数。当创建DataShareHelper实例成功，err为undefined，data为获取到的DataShareHelper实例；否则为错误对象。 | 39 40**错误码：** 41 42以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 43 44| 错误码ID | 错误信息 | 45| -------- | ---------------------------------------------------- | 46| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 47| 15700010 | The DataShareHelper is not initialized successfully. | 48 49**示例：** 50 51```ts 52import { BusinessError } from '@kit.BasicServicesKit' 53import { UIAbility } from '@kit.AbilityKit'; 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> 81> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 82 83**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 84 85 86| 参数名 | 类型 | 必填 | 说明 | 87| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | 88| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 89| uri | string | 是 | 要连接的服务端应用的路径。 | 90| options | [DataShareHelperOptions](#datasharehelperoptions10)| 是 | 可选配置。指定[DataShareHelper](#datasharehelper)是否在代理模式下。| 91| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | 是 | 回调函数。当创建DataShareHelper实例成功，err为undefined，data为获取到的DataShareHelper实例；否则为错误对象。 | 92 93**错误码：** 94 95以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 96 97| 错误码ID | 错误信息 | 98| -------- | ---------------------------------------------------- | 99| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 100| 15700010 | The DataShareHelper is not initialized successfully. | 101 102**示例：** 103 104```ts 105import { BusinessError } from '@kit.BasicServicesKit' 106import { UIAbility } from '@kit.AbilityKit'; 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> 134> 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md)。 135 136**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| ------- | ------------------------------------------------- | ---- | ------------------------------ | 142| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 143| uri | string | 是 | 要连接的服务端应用的路径。 | 144| options<sup>10+</sup> | [DataShareHelperOptions](#datasharehelperoptions10) | 否 | 可选配置。从API version 10开始支持此参数，如果不设置，则表示[DataShareHelper](#datasharehelper)不在代理模式下。| 145 146**返回值：** 147 148| 类型 | 说明 | 149| -------------------------------------------------- | -------------------------------------- | 150| Promise<[DataShareHelper](#datasharehelper)> | Promise对象。返回DataShareHelper实例。 | 151 152**错误码：** 153 154以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 155 156| 错误码ID | 错误信息 | 157| -------- | ---------------------------------------------------- | 158| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 159| 15700010 | The DataShareHelper is not initialized successfully. | 160 161**示例：** 162 163```ts 164import { BusinessError } from '@kit.BasicServicesKit' 165import { UIAbility } from '@kit.AbilityKit'; 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为undefined、uri为null，会清空掉之前设置的所有uri开关状态，开启数据提供方静默访问。<br />2、精准开关状态：uri的入参为固定的值，仅开启该uri对应的静默访问。<br />在调用datashareHelper相关接口时，优先精准匹配uri的开关状态。如果匹配不到，继续匹配全局的开关状态。<br />uri格式：datashare:///{bundleName}/{moduleName}/{storeName}/{tableName} | 203 204**返回值：** 205 206| 类型 | 说明 | 207| -------------------------------------------------- | -------------------------------------- | 208| Promise<void> | 无返回结果的Promise对象。 | 209 210**错误码：** 211 212错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 213 214| 错误码ID | 错误信息 | 215| -------- | ---------------------------------------------------- | 216| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 217| 15700011 | The URI is not exist. | 218 219**示例：** 220 221```ts 222import { BusinessError } from '@kit.BasicServicesKit' 223import { UIAbility } from '@kit.AbilityKit'; 224 225let uri = ("datashare:///com.acts.datasharetest/entry/DB00/TBL00?Proxy=true"); 226let context = getContext(UIAbility); 227dataShare.enableSilentProxy(context, uri).then(() => { 228 console.info("enableSilentProxy succeed"); 229}). catch((err: BusinessError) => { 230 console.error(`enableSilentProxy error: code: ${err.code}, message: ${err.message} `); 231}); 232``` 233 234## dataShare.disableSilentProxy<sup>11+</sup> 235 236disableSilentProxy(context: Context, uri?: string): Promise<void> 237 238关闭静默访问。使用Promise异步回调。 239 240使用规则： 241 - 数据提供方调用此接口，来关闭静默访问功能。 242 - 此接口设置的关闭结果在校验的时候是搭配data_share_config.json文件中isSilentProxyEnable字段进行工作的。支持的配置可参考[data_share_config.json配置](../../database/share-data-by-datashareextensionability.md)。 243 - 此接口生效在调用datashareHelper相关接口过程中，如果此接口有关闭过相关uri，那么会按照此接口的配置来关闭静默访问。如果此接口未调用过，则会读取data_share_config.json中的配置来校验Datashare的关闭状态。 244 245**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 246 247**参数：** 248 249| 参数名 | 类型 | 必填 | 说明 | 250| ------- | ------------------------------------------------------- | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 251| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md#context) | 是 | 应用的上下文环境。 | 252| uri | string | 否 | 要关闭的数据提供方的数据路径。<br />1、全局开关状态：入参不带uri、uri为undefined、uri为null，会清空掉之前设置的uri开关状态，关闭数据提供方静默访问。<br />2、精准开关状态：uri的入参为固定的值，仅关闭该uri对应的静默访问。<br />在调用datashareHelper相关接口时，优先精准匹配uri的开关状态。如果匹配不到，继续匹配全局的开关状态。<br />uri格式：datashare:///{bundleName}/{moduleName}/{storeName}/{tableName} | 253 254**返回值：** 255 256| 类型 | 说明 | 257| -------------------------------------------------- | -------------------------------------- | 258| Promise<void> | 无返回结果的Promise对象。 | 259 260**错误码：** 261 262错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 263 264| 错误码ID | 错误信息 | 265| -------- | ---------------------------------------------------- | 266| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 267| 15700011 | The URI is not exist. | 268 269**示例：** 270 271```ts 272import { BusinessError } from '@kit.BasicServicesKit' 273import { UIAbility } from '@kit.AbilityKit'; 274 275let uri = ("datashare:///com.acts.datasharetest/entry/DB00/TBL00?Proxy=true"); 276let context = getContext(UIAbility); 277dataShare.disableSilentProxy(context, uri).then(() => { 278 console.info("disableSilentProxy succeed"); 279}). catch((err: BusinessError) => { 280 console.error(`disableSilentProxy error: code: ${err.code}, message: ${err.message} `); 281}); 282``` 283 284## DataShareHelperOptions<sup>10+</sup> 285 286指定[DataShareHelper](#datasharehelper)是否在代理模式下。 287 288**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 289 290| 名称 | 类型 | 必填 | 说明 | 291| -------- | -------- | -------- | -------- | 292| isProxy | boolean | 否 | 默认为false，如果为true，则要创建的[DataShareHelper](#datasharehelper)处于代理模式，所有操作都不会打开数据提供者APP，除非数据库不存在，当数据库不存在时，[createDataShareHelper](#datasharecreatedatasharehelper10)会拉起数据提供者创建数据库。 | 293 294## TemplateId<sup>10+</sup> 295 296标记模板的数据结构，TemplateId是在[addTemplate](#addtemplate10)中自动生成的，在[addTemplate](#addtemplate10)后，可以使用模板id来标记模板。 297 298**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 299 300| 名称 | 类型 | 必填 | 说明 | 301| -------- | -------- | -------- | -------- | 302| subscriberId | string | 是 | 指定处理回调的订阅者的id，与[addTemplate](#addtemplate10)中的subscriberId相同，每个订阅者的ID是唯一的。 | 303| bundleNameOfOwner | string | 是 | 指定创建模板的模板所有者的bundleName，与[addTemplate](#addtemplate10)中的bundleName相同。 | 304 305## PublishedItem<sup>10+</sup> 306 307指定发布的数据类型。 308 309**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 310 311| 名称 | 类型 | 必填 | 说明 | 312| -------- | -------- | -------- | -------- | 313| key | string | 是 | 指定发布数据的键。 | 314| data | string \| ArrayBuffer | 是 | 指定发布的数据。如果发布数据大小超过20KB，建议使用ArrayBuffer。 | 315| subscriberId | string | 是 | 指定订阅者id。 | 316 317## RdbDataChangeNode<sup>10+</sup> 318 319订阅/取消订阅RDB数据变更的结果。 320 321**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 322 323| 名称 | 类型 | 必填 | 说明 | 324| -------- | -------- | -------- | -------- | 325| uri | string | 是 | 指定回调的uri。 | 326| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 327| data | Array<string> | 是 | 指定回调的数据。 | 328 329## PublishedDataChangeNode<sup>10+</sup> 330 331订阅/取消订阅已发布数据变更的结果。 332 333**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 334 335| 名称 | 类型 | 必填 | 说明 | 336| -------- | -------- | -------- | -------- | 337| bundleName | string | 是 | 指定回调的bundleName。 | 338| data | Array<[PublishedItem](#publisheditem10)> | 是 | 指定回调的数据。 | 339 340## Template<sup>10+</sup> 341 342指定订阅中的模板结构。 343 344**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 345 346| 名称 | 类型 | 必填 | 说明 | 347| -------- | -------- | -------- | -------- | 348| predicates | Record<string, string> | 是 | 指定模板的谓词。当调用[on](#onrdbdatachange10)的回调时，谓词用于生成数据。仅适用于rdb存储数据。 | 349| scheduler | string | 是 | 指定模板的调度程序sql。其中嵌入自定义函数处理，目前预置自定义函数remindTimer处理。remindTimer在指定场景触发一次订阅刷新。<br/>触发场景：<br/>1. 修改数据时且有订阅的情况下触发对应的调度程序sql语句。<br/>2. 添加对应库第一个订阅的情况下触发对应的调度程序sql语句。 | 350 351## OperationResult<sup>10+</sup> 352 353订阅/取消订阅数据变更和发布数据的操作结果。 354 355**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 356 357| 名称 | 类型 | 必填 | 说明 | 358| -------- | -------- | ----- | -------- | 359| key | string | 是 | 指定运算结果的键。 | 360| result | number | 是 | 指定运算结果。正常情况下返回0，异常情况下返回错误码。 | 361## UpdateOperation<sup>12+</sup> 362 363批量更新操作的参数结构。 364 365**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 366 367| 名称 | 类型 | 必填 | 说明 | 368| ---------- | ------------------------------------------------------------ | ---- | -------------- | 369| values | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 要更新的数据。 | 370| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。 | 371 372## ChangeType<sup>12+</sup> 373 374数据变更类型枚举。 375 376**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 377 378| 名称 | 值 | 说明 | 379| ---------| ------------| --------------| 380| INSERT | 0 | 表示数据添加。| 381| DELETE | 1 | 表示数据删除。| 382| UPDATE | 2 | 表示数据更新。| 383 384## SubscriptionType<sup>12+</sup> 385 386数据订阅类型枚举。 387 388**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 389 390| 名称 | 值 | 说明 | 391| ----------------------------|------| ---------------------------- | 392| SUBSCRIPTION_TYPE_EXACT_URI | 0 | 表示订阅指定uri路径的数据变更。| 393 394## ChangeInfo<sup>12+</sup> 395 396数据变更时通知用户具体变更的内容，包括数据变更类型、变化的uri、变更的数据内容。 397 398**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 399 400| 名称 | 类型 | 必填 | 说明 | 401| ---------- | ------------------------------------------------------------ | ---- | -------------- | 402| type | [ChangeType](#changetype12) | 是 | 通知变更的类型 | 403| uri | string | 是 | 指定uri。 | 404| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)>| 是 | 更新的数据。 | 405 406## DataShareHelper 407 408DataShare管理工具实例，可使用此实例访问或管理服务端的数据。在调用DataShareHelper提供的方法前，需要先通过[createDataShareHelper](#datasharecreatedatasharehelper)构建一个实例。 409 410### on('dataChange') 411 412on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void 413 414订阅指定URI对应数据的数据变更事件。若用户（订阅者）已注册了观察者，当有其他用户触发了变更通知时（调用了下文中的notifyChange方法），订阅者将会接收到callback通知。使用callback异步回调。 415 416**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 417 418**参数：** 419 420| 参数名 | 类型 | 必填 | 说明 | 421| -------- | -------------------- | ---- | ------------------------ | 422| type | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当数据更改时，触发该事件。 | 423| uri | string | 是 | 表示指定的数据路径。 | 424| callback | AsyncCallback<void> | 是 | 回调函数。当有其他用户触发了变更通知时调用，err为undefined；否则不被触发或为错误对象。 | 425 426**错误码：** 427 428以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 429 430| 错误码ID | 错误信息 | 431| -------- | -------------------- | 432| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 433| 15700013 | The DataShareHelper instance is already closed.| 434 435**示例：** 436 437```ts 438let onCallback: () => void = (): void => { 439 console.info("**** Observer on callback ****"); 440} 441let uri = ("datashare:///com.samples.datasharetest.DataShare"); 442if (dataShareHelper !== undefined) { 443 (dataShareHelper as dataShare.DataShareHelper).on("dataChange", uri, onCallback); 444} 445``` 446 447### on('dataChange')<sup>12+</sup> 448 449on(event: 'dataChange', type:SubscriptionType, uri: string, callback: AsyncCallback<ChangeInfo>): void 450 451订阅指定URI对应数据的数据变更事件。若用户（订阅者）已注册变更通知，当有其他用户触发了变更通知时（调用了下文中的notifyChange方法），订阅者将会接收到callback通知，通知携带数据变更类型、变化的uri、变更的数据内容。使用callback回调。仅支持非静默访问。 452 453**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 454 455**参数：** 456 457| 参数名 | 类型 | 必填 | 说明 | 458| -------- | -------------------- | ---- | ------------------------ | 459| event | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当有其他用户触发了变更通知时，触发该事件。 | 460| type | [SubscriptionType](#subscriptiontype12)| 是 | 表示数据更改时按指定数据路径通知变更。 | 461| uri | string | 是 | 表示指定的数据路径。 | 462| callback | AsyncCallback<[ChangeInfo](#changeinfo12)> | 是 | 回调函数。当有其他用户触发了变更通知时会回调该函数。| 463 464**错误码：** 465 466以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 467 468| 错误码ID | 错误信息 | 469| -------- | -------------------- | 470| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 471| 15700013 | The DataShareHelper instance is already closed.| 472 473**示例：** 474 475<!--code_no_check--> 476```ts 477import { BusinessError } from '@kit.BasicServicesKit' 478 479let uri = ("datashare:///com.acts.datasharetest"); 480export function callback(error:BusinessError, ChangeInfo:dataShare.ChangeInfo) { 481 console.info(' **** Observer callback **** ChangeInfo:' + JSON.stringify(ChangeInfo)); 482} 483if (dataShareHelper !== undefined) { 484 (dataShareHelper as dataShare.DataShareHelper).on('dataChange', dataShare.SubscriptionType.SUBSCRIPTION_TYPE_EXACT_URI, uri, callback); 485} 486``` 487 488### off('dataChange') 489 490off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void 491 492取消订阅指定URI下指定callback对应的数据资源的变更通知。 493 494**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 495 496**参数：** 497 498| 参数名 | 类型 | 必填 | 说明 | 499| -------- | -------------------- | ---- | ------------------------ | 500| type | string | 是 | 取消订阅的事件/回调类型，支持的事件为'dataChange'。 | 501| uri | string | 是 | 表示指定的数据路径。 | 502| callback | AsyncCallback<void> | 否 | 表示指定取消订阅的callback通知，如果为空、为undefined、null，则取消订阅该uri下所有的通知事件。 | 503 504**错误码：** 505 506以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 507 508| 错误码ID | 错误信息 | 509| -------- | -------------------- | 510| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 511| 15700013 | The DataShareHelper instance is already closed.| 512 513**示例：** 514 515```ts 516let callback: () => void = (): void => { 517 console.info("**** Observer on callback ****"); 518} 519let uri = ("datashare:///com.samples.datasharetest.DataShare"); 520if (dataShareHelper != undefined) { 521 (dataShareHelper as dataShare.DataShareHelper).on("dataChange", uri, callback); 522 (dataShareHelper as dataShare.DataShareHelper).off("dataChange", uri, callback); 523} 524``` 525 526 527### off('dataChange')<sup>12+</sup> 528 529off(event: 'dataChange', type:SubscriptionType, uri: string, callback?: AsyncCallback<ChangeInfo>): void 530 531取消订阅指定URI下指定callback对应的数据资源的变更通知。仅支持非静默访问。 532 533**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| -------- | -------------------- | ---- | ------------------------ | 539| event | string | 是 | 取消订阅的事件/回调类型，支持的事件为'dataChange'。 | 540| type | [SubscriptionType](#subscriptiontype12)| 是 | 表示数据更改时按指定数据路径通知变更。 | 541| uri | string | 是 | 表示指定的数据路径。 | 542| callback | AsyncCallback<[ChangeInfo](#changeinfo12)>| 否 | 表示指定取消订阅的callback通知，如果为空、为undefined、null，则取消订阅该uri下所有的通知事件。如果不为空，传入的callback必须和注册为同一个。| 543 544**错误码：** 545 546以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 547 548| 错误码ID | 错误信息 | 549| -------- | -------------------- | 550| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 551| 15700013 | The DataShareHelper instance is already closed.| 552 553**示例：** 554 555<!--code_no_check--> 556```ts 557import { BusinessError } from '@kit.BasicServicesKit' 558 559let uri = ("datashare:///com.acts.datasharetest"); 560export function callback(error:BusinessError, ChangeInfo:dataShare.ChangeInfo) { 561 console.info(' **** Observer callback **** ChangeInfo:' + JSON.stringify(ChangeInfo)); 562} 563if (dataShareHelper !== undefined) { 564 (dataShareHelper as dataShare.DataShareHelper).on("dataChange", dataShare.SubscriptionType.SUBSCRIPTION_TYPE_EXACT_URI, uri, callback); 565 (dataShareHelper as dataShare.DataShareHelper).off("dataChange", dataShare.SubscriptionType.SUBSCRIPTION_TYPE_EXACT_URI, uri, callback); 566} 567``` 568 569### addTemplate<sup>10+</sup> 570 571addTemplate(uri: string, subscriberId: string, template: Template): void 572 573添加一个指定订阅者的数据模板。 574 575**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 576 577**参数：** 578 579| 参数名 | 类型 | 必填 | 说明 | 580| -------- | ------------------------ | ---- | -------------------------| 581| uri | string | 是 | 要插入的数据的路径。 | 582| subscriberId | string | 是 | 要添加模板的订阅者ID，每个订阅者的ID是唯一的。 | 583| template | [Template](#template10) | 是 | 要添加的数据模板。 | 584 585**错误码：** 586 587以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 588 589| 错误码ID | 错误信息 | 590| -------- | -------------------- | 591| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 592| 15700011 | The URI is not exist.| 593| 15700013 | The DataShareHelper instance is already closed.| 594 595**示例：** 596 597```ts 598let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 599let subscriberId = '11'; 600let key1: string = "p1"; 601let value1: string = "select cityColumn as city_1, visitedCilumn as visited_1 from citys where like = true"; 602let key2: string = "p2"; 603let value2: string = "select cityColumn as city_2, visitedCilumn as visited_2 from citys where like = false"; 604let template: dataShare.Template = { 605 predicates : { 606 key1 : value1, 607 key2 : value2, 608 }, 609 scheduler : "select remindTimer(time) from TBL00" 610} 611if (dataShareHelper != undefined) { 612 (dataShareHelper as dataShare.DataShareHelper).addTemplate(uri, subscriberId, template); 613} 614``` 615 616### delTemplate<sup>10+</sup> 617 618delTemplate(uri: string, subscriberId: string): void 619 620删除一个指定订阅者的数据模板。 621 622**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 623 624**参数：** 625 626| 参数名 | 类型 | 必填 | 说明 | 627| -------- | -------------| ---- | ------------------------- | 628| uri | string | 是 | 要删除的数据的路径。 | 629| subscriberId | string | 是 | 订阅者ID，每个订阅者的ID是唯一的。 | 630 631**错误码：** 632 633以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 634 635| 错误码ID | 错误信息 | 636| -------- | -------------------- | 637| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 638| 15700011 | The URI is not exist.| 639| 15700013 | The DataShareHelper instance is already closed.| 640 641**示例：** 642 643```ts 644let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 645let subscriberId = '11'; 646let key1: string = "p1"; 647let value1: string = "select cityColumn as city_1, visitedCilumn as visited_1 from citys where like = true"; 648let key2: string = "p2"; 649let value2: string = "select cityColumn as city_2, visitedCilumn as visited_2 from citys where like = false"; 650let template: dataShare.Template = { 651 predicates : { 652 key1 : value1, 653 key2 : value2, 654 }, 655 scheduler : "select remindTimer(time) from TBL00" 656} 657if (dataShareHelper != undefined) { 658 (dataShareHelper as dataShare.DataShareHelper).addTemplate(uri, subscriberId, template); 659 (dataShareHelper as dataShare.DataShareHelper).delTemplate(uri, subscriberId); 660} 661``` 662 663### on('rdbDataChange')<sup>10+</sup> 664 665on(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback: AsyncCallback<RdbDataChangeNode>): Array<OperationResult> 666 667订阅指定URI和模板对应的数据变更事件。 668 669**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 670 671**参数：** 672 673| 参数名 | 类型 | 必填 | 说明 | 674| -------- | ----------------------------------| ---- | ------------------------------------------------------------ | 675| type | string | 是 | 订阅的事件类型，支持的事件为'rdbDataChange'，表示rdb数据的变更事件。type是固定值以外时，接口无响应。 | 676| uris | Array<string> | 是 | 要操作的数据的路径。 | 677| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 678| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | 是 | 回调函数。当触发变更通知时调用，err为undefined，node为订阅数据变更结果；否则不被触发或为错误对象。 | 679 680**返回值：** 681 682| 类型 | 说明 | 683| ---------------- | ------------------------------------------------------------ | 684| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 685 686**错误码：** 687 688以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 689 690| 错误码ID | 错误信息 | 691| -------- | -------------------- | 692| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 693| 15700013 | The DataShareHelper instance is already closed.| 694 695**示例：** 696 697```ts 698import { BusinessError } from '@kit.BasicServicesKit' 699 700let onCallback: (err: BusinessError, node: dataShare.RdbDataChangeNode) => void = (err: BusinessError, node:dataShare.RdbDataChangeNode): void => { 701 console.info("onCallback " + JSON.stringify(node.uri)); 702 console.info("onCallback " + JSON.stringify(node.templateId)); 703 console.info("onCallback " + node.data.length); 704 for (let i = 0; i < node.data.length; i++) { 705 console.info("onCallback " + typeof node.data[i] + " " + node.data[i]); 706 } 707} 708 709let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 710let templateId:dataShare.TemplateId = {subscriberId:"11", bundleNameOfOwner:"com.acts.ohos.data.datasharetest"}; 711if (dataShareHelper != undefined) { 712 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).on("rdbDataChange", [uri], templateId, onCallback); 713} 714``` 715 716### off('rdbDataChange')<sup>10+</sup> 717 718off(type: 'rdbDataChange', uris: Array<string>, templateId: TemplateId, callback?: AsyncCallback<RdbDataChangeNode>): Array<OperationResult> 719 720取消订阅指定URI和模板对应的数据变更事件。 721 722**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 723 724**参数：** 725 726| 参数名 | 类型 | 必填 | 说明 | 727| -------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | 728| type | string | 是 | 取消订阅的事件类型，支持的事件为'rdbDataChange'，表示rdb数据的变更事件。 | 729| uris | Array<string> | 是 | 要操作的数据的路径。 | 730| templateId | [TemplateId](#templateid10) | 是 | 处理回调的templateId。 | 731| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | 否 | 回调函数。表示指定取消订阅的callback通知，如果为空、为undefined、null，则取消订阅该uri下所有的通知事件。 | 732 733**返回值：** 734 735| 类型 | 说明 | 736| ---------------- | ------------------------------------------------------------ | 737| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 738 739**错误码：** 740 741以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 742 743| 错误码ID | 错误信息 | 744| -------- | -------------------- | 745| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 746| 15700013 | The DataShareHelper instance is already closed.| 747 748**示例：** 749 750```ts 751let uri = ("datashareproxy://com.samples.datasharetest.DataShare"); 752let templateId:dataShare.TemplateId = {subscriberId:"11", bundleNameOfOwner:"com.acts.ohos.data.datasharetest"}; 753if (dataShareHelper != undefined) { 754 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).off("rdbDataChange", [uri], templateId); 755} 756``` 757 758### on('publishedDataChange')<sup>10+</sup> 759 760on(type: 'publishedDataChange', uris: Array<string>, subscriberId: string, callback: AsyncCallback<PublishedDataChangeNode>): Array<OperationResult> 761 762订阅已发布数据的数据变更通知。 763 764**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 765 766**参数：** 767 768| 参数名 | 类型 | 必填 | 说明 | 769| -------- | ----------------------------------| ---- | ------------------------------------------------------------ | 770| type | string | 是 | 订阅的事件类型，支持的事件为'publishedDataChange'，表示已发布数据的变更事件。 | 771| uris | Array<string> | 是 | 要操作的数据的路径。 | 772| subscriberId | string | 是 | 指定处理回调的用户ID。 | 773| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | 是 | 回调函数。当触发变更通知时调用，err为undefined，node为订阅数据变更结果；否则不被触发或为错误对象。 | 774 775**返回值：** 776 777| 类型 | 说明 | 778| ---------------- | ------------------------------------------------------------ | 779| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 780 781**错误码：** 782 783以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 784 785| 错误码ID | 错误信息 | 786| -------- | -------------------- | 787| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 788| 15700013 | The DataShareHelper instance is already closed.| 789 790**示例：** 791 792```ts 793import { BusinessError } from '@kit.BasicServicesKit' 794 795let onPublishCallback: (err: BusinessError, node: dataShare.PublishedDataChangeNode) => void = (err: BusinessError, node:dataShare.PublishedDataChangeNode): void => { 796 console.info("onPublishCallback node bundleName " + JSON.stringify(node.bundleName)); 797 console.info("onPublishCallback node data size" + node.data.length); 798 for (let i = 0; i < node.data.length; i++) { 799 console.info("onPublishCallback node " + typeof node.data[i].data); 800 if (typeof node.data[i].data != 'string') { 801 let array: ArrayBuffer = node.data[i].data as ArrayBuffer; 802 let data: Uint8Array = new Uint8Array(array); 803 console.info("onPublishCallback " + i + " " + JSON.stringify(data)); 804 } 805 console.info("onPublishCallback data " + i + " " + JSON.stringify(node.data[i])); 806 } 807} 808let uris:Array<string> = ['city', 'datashareproxy://com.acts.ohos.data.datasharetest/appInfo', 'key2']; 809let subscriberId = '11'; 810if (dataShareHelper != undefined) { 811 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).on('publishedDataChange', uris, subscriberId, onPublishCallback); 812} 813``` 814 815### off('publishedDataChange')<sup>10+</sup> 816 817off(type: 'publishedDataChange', uris: Array<string>, subscriberId: string, callback?: AsyncCallback<PublishedDataChangeNode>): Array<OperationResult> 818 819取消订阅已发布数据的数据变更通知。 820 821**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 822 823**参数：** 824 825| 参数名 | 类型 | 必填 | 说明 | 826| -------- | -------------------------------------------- | ---- | ---------------------------------------------------------- | 827| type | string | 是 | 取消订阅的事件类型，支持的事件为'publishedDataChange'，表示已发布数据的变更事件。| 828| uris | Array<string> | 是 | 要操作的数据的路径。 | 829| subscriberId | string | 是 | 指定处理回调的用户ID。 | 830| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | 否 | 回调函数。表示指定取消订阅的callback通知，如果为空、为undefined、null，则取消订阅该uri下所有的通知事件。 | 831 832**返回值：** 833 834| 类型 | 说明 | 835| ---------------- | ------------------------------------------------------------ | 836| Array<[OperationResult](#operationresult10)> | 返回操作结果。| 837 838**错误码：** 839 840以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 841 842| 错误码ID | 错误信息 | 843| -------- | -------------------- | 844| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 845| 15700013 | The DataShareHelper instance is already closed.| 846 847**示例：** 848 849```ts 850import { BusinessError } from '@kit.BasicServicesKit' 851 852let offCallback: (err: BusinessError, node: dataShare.PublishedDataChangeNode) => void = (err: BusinessError, node:dataShare.PublishedDataChangeNode): void => { 853 console.info("**** Observer off callback ****"); 854} 855let uris:Array<string> = ["city", "datashareproxy://com.acts.ohos.data.datasharetest/appInfo", "key2"]; 856let subscriberId = '11'; 857if (dataShareHelper != undefined) { 858 let result: Array<dataShare.OperationResult> = (dataShareHelper as dataShare.DataShareHelper).off("publishedDataChange", uris, subscriberId, offCallback); 859} 860``` 861 862### publish<sup>10+</sup> 863 864publish(data: Array<PublishedItem>, bundleName: string, version: number, callback: AsyncCallback<Array<OperationResult>>): void 865 866发布数据，将数据更新至数据库。 867 868**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 869 870**参数：** 871 872| 参数名 | 类型 | 必填 | 说明 | 873| --------- | -------------------------------------------------| ---- | ------------------- | 874| data | Array<[PublishedItem](#publisheditem10)> | 是 | 要发布的数据。 | 875| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 876| version | number | 是 | 要发布的数据版本，越大表示数据版本越新。如果发布的版本号小于数据库中的记录，则更新失败。 | 877| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | 是 | 回调函数。当发布数据时调用，err为undefined，result为发布数据结果；否则不被触发或为错误对象。 | 878 879**错误码：** 880 881以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 882 883| 错误码ID | 错误信息 | 884| -------- | -------------------------- | 885| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 886| 15700012 | The data area is not exist.| 887| 15700013 | The DataShareHelper instance is already closed.| 888 889**示例：** 890 891```ts 892import { BusinessError } from '@kit.BasicServicesKit' 893 894let arrayBuffer = new ArrayBuffer(1); 895let version = 1; 896let dataArray : Array<dataShare.PublishedItem> = [{key:"key2", subscriberId:"11", data:arrayBuffer}]; 897let publishCallback: (err: BusinessError, result: Array<dataShare.OperationResult>) => void = (err: BusinessError, result: Array<dataShare.OperationResult>): void => { 898 console.info("publishCallback " + JSON.stringify(result)); 899} 900try { 901 console.info("dataArray length is:", dataArray.length); 902 if (dataShareHelper != undefined) { 903 (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest", version, publishCallback); 904 } 905} catch (e) { 906 console.error("publish error " + JSON.stringify(e)); 907} 908``` 909 910### publish<sup>10+</sup> 911 912publish(data: Array<PublishedItem>, bundleName: string, callback: AsyncCallback<Array<OperationResult>>): void 913 914发布数据，将数据更新至数据库。 915 916**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 917 918**参数：** 919 920| 参数名 | 类型 | 必填 | 说明 | 921| -------- | ------------------------------------------------- | ---- | ---------------------------------- | 922| data | Array<[PublishedItem](#publisheditem10)> | 是 | 要发布的数据。 | 923| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 924| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | 是 | 回调函数。当发布数据时调用，err为undefined，result为发布数据结果；否则不被触发或为错误对象。 | 925 926**错误码：** 927 928以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 929 930| 错误码ID | 错误信息 | 931| -------- | -------------------------- | 932| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 933| 15700012 | The data area is not exist.| 934| 15700013 | The DataShareHelper instance is already closed.| 935 936**示例：** 937 938```ts 939import { BusinessError } from '@kit.BasicServicesKit' 940 941let publishCallback: (err: BusinessError, result: Array<dataShare.OperationResult>) => void = (err: BusinessError, result: Array<dataShare.OperationResult>): void => { 942 console.info("publishCallback " + JSON.stringify(result)); 943} 944let dataArray : Array<dataShare.PublishedItem> = [ 945 {key:"city", subscriberId:"11", data:"xian"}, 946 {key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo", subscriberId:"11", data:"appinfo is just a test app"}, 947 {key:"empty", subscriberId:"11", data:"nobody sub"}]; 948if (dataShareHelper != undefined) { 949 (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest", publishCallback); 950} 951``` 952 953### publish<sup>10+</sup> 954 955publish(data: Array<PublishedItem>, bundleName: string, version?: number): Promise<Array<OperationResult>> 956 957发布数据，将数据更新至数据库。 958 959**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 960 961**参数：** 962 963| 参数名 | 类型 | 必填 | 说明 | 964| -------- | ----------------------------- | ---- | ------------------------------ | 965| data | Array<[PublishedItem](#publisheditem10)> | 是 | 要发布的数据。| 966| bundleName | string | 是 | 表示要发布数据所属的APP，对发布的私有数据生效，仅该app可以读取数据。 | 967| version | number | 否 | 要发布的数据版本，越大表示数据版本越新。如果发布的版本号小于数据库中的记录，则更新失败。<br/> 如果不检查要发布的数据版本，则不填。 | 968 969**返回值：** 970 971| 类型 | 说明 | 972| ---------------- | ------------------------------------------------------------ | 973| Promise<Array<[OperationResult](#operationresult10)>> | 发布数据结果。| 974 975**错误码：** 976 977以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 978 979| 错误码ID | 错误信息 | 980| -------- | -------------------------- | 981| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 982| 15700012 | The data area is not exist.| 983| 15700013 | The DataShareHelper instance is already closed.| 984 985**示例：** 986 987```ts 988let dataArray: Array<dataShare.PublishedItem> = [ 989 {key:"city", subscriberId:"11", data:"xian"}, 990 {key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo", subscriberId:"11", data:"appinfo is just a test app"}, 991 {key:"empty", subscriberId:"11", data:"nobody sub"}]; 992if (dataShareHelper != undefined) { 993 let result: Promise<Array<dataShare.OperationResult>> = (dataShareHelper as dataShare.DataShareHelper).publish(dataArray, "com.acts.ohos.data.datasharetest"); 994} 995``` 996 997### getPublishedData<sup>10+</sup> 998 999getPublishedData(bundleName: string, callback: AsyncCallback<Array<PublishedItem>>): void 1000 1001获取给定的APP和模板指定的数据。 1002 1003**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1004 1005**参数：** 1006 1007| 参数名 | 类型 | 必填 | 说明 | 1008| -------- | -----------------| ---- | ----------------------------- | 1009| bundleName | string | 是 | 表示数据所属的APP。 | 1010| callback | AsyncCallback<Array<[PublishedItem](#publisheditem10)>> | 是 | 回调函数，返回给定的APP和模板发布的数据。 | 1011 1012**错误码：** 1013 1014以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1015 1016| 错误码ID | 错误信息 | 1017| -------- | -------------------------- | 1018| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1019| 15700012 | The data area is not exist.| 1020| 15700013 | The DataShareHelper instance is already closed.| 1021 1022**示例：** 1023 1024```ts 1025import { BusinessError } from '@kit.BasicServicesKit' 1026 1027let publishCallback: (err: BusinessError, data: Array<dataShare.PublishedItem>) => void = (err: BusinessError, result: Array<dataShare.PublishedItem>): void => { 1028 console.info("**** Observer publish callback ****"); 1029} 1030if (dataShareHelper != undefined) { 1031 (dataShareHelper as dataShare.DataShareHelper).getPublishedData("com.acts.ohos.data.datasharetest", publishCallback); 1032} 1033``` 1034 1035### getPublishedData<sup>10+</sup> 1036 1037getPublishedData(bundleName: string): Promise<Array<PublishedItem>> 1038 1039获取给定的APP和模板指定的数据。 1040 1041**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1042 1043**参数：** 1044 1045| 参数名 | 类型 | 必填 | 说明 | 1046| -------- | --------------| ---- | -------------------------------------- | 1047| bundleName | string | 是 | 表示数据所属的APP。 | 1048 1049**返回值：** 1050 1051| 类型 | 说明 | 1052| ------------------------------------------------------------ | ----------------------------------- | 1053| Promise<Array<[PublishedItem](#publisheditem10)>> | Promise对象，返回给定的APP和模板发布的数据。 | 1054 1055**错误码：** 1056 1057以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1058 1059| 错误码ID | 错误信息 | 1060| -------- | -------------------------- | 1061| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1062| 15700012 | The data area is not exist.| 1063| 15700013 | The DataShareHelper instance is already closed.| 1064 1065**示例：** 1066 1067```ts 1068if (dataShareHelper != undefined) { 1069 let publishedData: Promise<Array<dataShare.PublishedItem>> = (dataShareHelper as dataShare.DataShareHelper).getPublishedData("com.acts.ohos.data.datasharetest"); 1070} 1071``` 1072 1073### insert 1074 1075insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void 1076 1077将单条数据插入数据库。使用callback异步回调。 1078 1079**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1080 1081**参数：** 1082 1083| 参数名 | 类型 | 必填 | 说明 | 1084| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1085| uri | string | 是 | 要插入的数据的路径。 | 1086| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 要插入的数据。如果此参数为空，将插入一个空行。 | 1087| callback | AsyncCallback<number> | 是 | 回调函数。当将单条数据插入数据库成功，err为undefined，data为获取到的插入数据记录的索引；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此callback也无法返回索引值。 | 1088 1089**错误码：** 1090 1091以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1092 1093| 错误码ID | 错误信息 | 1094| -------- | -------------------- | 1095| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1096| 15700013 | The DataShareHelper instance is already closed.| 1097 1098**示例：** 1099 1100```ts 1101import { ValuesBucket } from '@kit.ArkData' 1102import { BusinessError } from '@kit.BasicServicesKit' 1103 1104let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1105let key1: string = "name"; 1106let value1: string = "rose"; 1107let key2: string = "age"; 1108let value2: number = 22; 1109let key3: string = "salary"; 1110let value3: number = 200.5; 1111const valueBucket: ValuesBucket = { 1112 key1: value1, 1113 key2: value2, 1114 key3: value3, 1115} 1116try { 1117 if (dataShareHelper != undefined) { 1118 (dataShareHelper as dataShare.DataShareHelper).insert(uri, valueBucket, (err: BusinessError, data: number) => { 1119 if (err !== undefined) { 1120 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 1121 return; 1122 } 1123 console.info("insert succeed, data : " + data); 1124 }); 1125 } 1126} catch (err) { 1127 let code = (err as BusinessError).code; 1128 let message = (err as BusinessError).message; 1129 console.error(`insert error: code: ${code}, message: ${message} `); 1130}; 1131``` 1132 1133### insert 1134 1135insert(uri: string, value: ValuesBucket): Promise<number> 1136 1137将单条数据插入数据库。使用Promise异步回调。 1138 1139**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1140 1141**参数：** 1142 1143| 参数名 | 类型 | 必填 | 说明 | 1144| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- | 1145| uri | string | 是 | 要插入的数据的路径。 | 1146| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 要插入的数据。如果此参数为空，将插入一个空行。 | 1147 1148**返回值：** 1149 1150| 类型 | 说明 | 1151| ---------------- | ------------------------------------------------------------ | 1152| Promise<number> | Promise对象。返回插入数据记录的索引。<br />因部分数据库（如KVDB）的相应接口并不支持返回索引，故若服务端使用了不支持索引的数据库，则此Promise也无法返回索引值。 | 1153 1154**错误码：** 1155 1156以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1157 1158| 错误码ID | 错误信息 | 1159| -------- | -------------------- | 1160| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1161| 15700013 | The DataShareHelper instance is already closed.| 1162 1163**示例：** 1164 1165```ts 1166import { BusinessError } from '@kit.BasicServicesKit' 1167import { ValuesBucket } from '@kit.ArkData' 1168 1169let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1170let key1: string = "name"; 1171let value1: string = "rose1"; 1172let key2: string = "age"; 1173let value2: number = 21; 1174let key3: string = "salary"; 1175let value3: number = 20.5; 1176const valueBucket: ValuesBucket = { 1177 key1: value1, 1178 key2: value2, 1179 key3: value3, 1180} 1181try { 1182 if (dataShareHelper != undefined) { 1183 (dataShareHelper as dataShare.DataShareHelper).insert(uri, valueBucket).then((data: number) => { 1184 console.info("insert succeed, data : " + data); 1185 }).catch((err: BusinessError) => { 1186 console.error(`insert error: code: ${err.code}, message: ${err.message} `); 1187 }); 1188 } 1189} catch (err) { 1190 let code = (err as BusinessError).code; 1191 let message = (err as BusinessError).message; 1192 console.error(`insert error: code: ${code}, message: ${message} `); 1193}; 1194``` 1195 1196### delete 1197 1198delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void 1199 1200从数据库中删除一条或多条数据记录。使用callback异步回调。 1201 1202**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1203 1204**参数：** 1205 1206| 参数名 | 类型 | 必填 | 说明 | 1207| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1208| uri | string | 是 | 要删除的数据的路径。 | 1209| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。谓词内方法为空时，默认全表删除。 | 1210| callback | AsyncCallback<number> | 是 | 回调函数。当从数据库中删除一条或多条数据记录成功，err为undefined，data为获取到的已删除的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回删除的数据记录数。 | 1211 1212**错误码：** 1213 1214以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1215 1216| 错误码ID | 错误信息 | 1217| -------- | -------------------- | 1218| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1219| 15700013 | The DataShareHelper instance is already closed.| 1220 1221**示例：** 1222 1223```ts 1224import { dataSharePredicates } from '@kit.ArkData' 1225import { BusinessError } from '@kit.BasicServicesKit' 1226 1227let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1228let da = new dataSharePredicates.DataSharePredicates(); 1229da.equalTo("name", "ZhangSan"); 1230try { 1231 if (dataShareHelper != undefined) { 1232 (dataShareHelper as dataShare.DataShareHelper).delete(uri, da, (err: BusinessError, data: number) => { 1233 if (err !== undefined) { 1234 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 1235 return; 1236 } 1237 console.info("delete succeed, data : " + data); 1238 }); 1239 } 1240} catch (err) { 1241 let code = (err as BusinessError).code; 1242 let message = (err as BusinessError).message; 1243 console.error(`delete error: code: ${code}, message: ${message} `); 1244}; 1245``` 1246 1247### delete 1248 1249delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number> 1250 1251从数据库中删除一条或多条数据记录。使用Promise异步回调。 1252 1253**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1254 1255**参数：** 1256 1257| 参数名 | 类型 | 必填 | 说明 | 1258| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1259| uri | string | 是 | 要删除的数据的路径。 | 1260| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />delete接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB的删除目前仅支持inKeys谓词。谓词内方法为空时，默认全表删除。 | 1261 1262**返回值：** 1263 1264| 类型 | 说明 | 1265| ---------------- | ------------------------------------------------------------ | 1266| Promise<number> | Promise对象。返回已删除的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回删除的数据记录数。 | 1267 1268**错误码：** 1269 1270以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1271 1272| 错误码ID | 错误信息 | 1273| -------- | -------------------- | 1274| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1275| 15700013 | The DataShareHelper instance is already closed.| 1276 1277**示例：** 1278 1279```ts 1280import { dataSharePredicates } from '@kit.ArkData' 1281import { BusinessError } from '@kit.BasicServicesKit' 1282 1283let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1284let da = new dataSharePredicates.DataSharePredicates(); 1285da.equalTo("name", "ZhangSan"); 1286try { 1287 if (dataShareHelper != undefined) { 1288 (dataShareHelper as dataShare.DataShareHelper).delete(uri, da).then((data: number) => { 1289 console.info("delete succeed, data : " + data); 1290 }).catch((err: BusinessError) => { 1291 console.error(`delete error: code: ${err.code}, message: ${err.message} `); 1292 }); 1293 } 1294} catch (err) { 1295 let code = (err as BusinessError).code; 1296 let message = (err as BusinessError).message; 1297 console.error(`delete error: code: ${code}, message: ${message} `); 1298}; 1299``` 1300 1301### query 1302 1303query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void 1304 1305查询数据库中的数据。使用callback异步回调。 1306 1307**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1308 1309**参数：** 1310 1311| 参数名 | 类型 | 必填 | 说明 | 1312| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1313| uri | string | 是 | 要查询的数据的路径。 | 1314| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。谓词内方法为空时，默认全表查询。 | 1315| columns | Array<string> | 是 | 要查询的列。如果此参数为空，则查询所有列。 | 1316| callback | AsyncCallback<[DataShareResultSet](js-apis-data-DataShareResultSet-sys.md#datashareresultset)> | 是 | 回调函数。当查询数据库中的数据成功，err为undefined，data为获取到的查询到的结果集；否则为错误对象。 | 1317 1318**错误码：** 1319 1320以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1321 1322| 错误码ID | 错误信息 | 1323| -------- | -------------------- | 1324| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1325| 15700013 | The DataShareHelper instance is already closed.| 1326 1327**示例：** 1328 1329```ts 1330import { dataSharePredicates, DataShareResultSet } from '@kit.ArkData' 1331import { BusinessError } from '@kit.BasicServicesKit' 1332 1333let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1334let columns = ["*"]; 1335let da = new dataSharePredicates.DataSharePredicates(); 1336da.equalTo("name", "ZhangSan"); 1337try { 1338 if (dataShareHelper != undefined) { 1339 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns, (err: BusinessError, data: DataShareResultSet) => { 1340 if (err !== undefined) { 1341 console.error(`query error: code: ${err.code}, message: ${err.message} `); 1342 return; 1343 } 1344 console.info("query succeed, rowCount : " + data.rowCount); 1345 }); 1346 } 1347} catch (err) { 1348 let code = (err as BusinessError).code; 1349 let message = (err as BusinessError).message; 1350 console.error(`query error: code: ${code}, message: ${message} `); 1351}; 1352``` 1353 1354### query 1355 1356query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet> 1357 1358查询数据库中的数据。使用Promise异步回调。 1359 1360**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1361 1362**参数：** 1363 1364| 参数名 | 类型 | 必填 | 说明 | 1365| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1366| uri | string | 是 | 要查询的数据的路径。 | 1367| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />query接口所支持的谓词方法取决于服务端所选用的数据库，如KVDB目前仅支持inKeys和prefixKey。谓词内方法为空时，默认全表查询。 | 1368| columns | Array<string> | 是 | 要查询的列。如果此参数为空，则查询所有列。 | 1369 1370**返回值：** 1371 1372| 类型 | 说明 | 1373| ------------------------------------------------------------ | --------------------------------- | 1374| Promise<[DataShareResultSet](js-apis-data-DataShareResultSet-sys.md#datashareresultset)> | Promise对象。返回查询到的结果集。 | 1375 1376**错误码：** 1377 1378以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1379 1380| 错误码ID | 错误信息 | 1381| -------- | -------------------- | 1382| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1383| 15700013 | The DataShareHelper instance is already closed.| 1384 1385**示例：** 1386 1387```ts 1388import { dataSharePredicates, DataShareResultSet } from '@kit.ArkData' 1389import { BusinessError } from '@kit.BasicServicesKit' 1390 1391let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1392let columns = ["*"]; 1393let da = new dataSharePredicates.DataSharePredicates(); 1394da.equalTo("name", "ZhangSan"); 1395try { 1396 if (dataShareHelper != undefined) { 1397 (dataShareHelper as dataShare.DataShareHelper).query(uri, da, columns).then((data: DataShareResultSet) => { 1398 console.info("query succeed, rowCount : " + data.rowCount); 1399 }).catch((err: BusinessError) => { 1400 console.error(`query error: code: ${err.code}, message: ${err.message} `); 1401 }); 1402 } 1403} catch (err) { 1404 let code = (err as BusinessError).code; 1405 let message = (err as BusinessError).message; 1406 console.error(`query error: code: ${code}, message: ${message} `); 1407}; 1408``` 1409 1410### update 1411 1412update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void 1413 1414更新数据库中的数据记录。使用callback异步回调。 1415 1416**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1417 1418**参数：** 1419 1420| 参数名 | 类型 | 必填 | 说明 | 1421| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1422| uri | string | 是 | 要更新的数据的路径。 | 1423| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。谓词内方法为空时，默认全表更新。 | 1424| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 要更新的数据。可以为null。 | 1425| callback | AsyncCallback<number> | 是 | 回调函数。当更新数据库中的数据记录成功，err为undefined，data为获取到的更新的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此callback也无法返回更新的数据记录数。 | 1426 1427**错误码：** 1428 1429以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1430 1431| 错误码ID | 错误信息 | 1432| -------- | -------------------- | 1433| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1434| 15700013 | The DataShareHelper instance is already closed.| 1435 1436**示例：** 1437 1438```ts 1439import { dataSharePredicates, ValuesBucket } from '@kit.ArkData' 1440import { BusinessError } from '@kit.BasicServicesKit' 1441 1442let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1443let da = new dataSharePredicates.DataSharePredicates(); 1444da.equalTo("name", "ZhangSan"); 1445let key1: string = "name"; 1446let value1: string = "roe1" 1447let key2: string = "age"; 1448let value2: number = 21 1449let key3: string = "salary"; 1450let value3: number = 20.5; 1451const va: ValuesBucket = { 1452 key1: value1, 1453 key2: value2, 1454 key3: value3, 1455} 1456try { 1457 if (dataShareHelper != undefined) { 1458 (dataShareHelper as dataShare.DataShareHelper).update(uri, da, va, (err: BusinessError, data: number) => { 1459 if (err !== undefined) { 1460 console.error(`update error: code: ${err.code}, message: ${err.message} `); 1461 return; 1462 } 1463 console.info("update succeed, data : " + data); 1464 }); 1465 } 1466} catch (err) { 1467 let code = (err as BusinessError).code; 1468 let message = (err as BusinessError).message; 1469 console.error(`update error: code: ${code}, message: ${message} `); 1470}; 1471``` 1472 1473### update 1474 1475update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number> 1476 1477更新数据库中的数据记录。使用Promise异步回调。 1478 1479**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1480 1481**参数：** 1482 1483| 参数名 | 类型 | 必填 | 说明 | 1484| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1485| uri | string | 是 | 要更新的数据的路径。 | 1486| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 筛选条件。<br />update接口是否支持谓词筛选条件取决于服务端所选用的数据库，如KVDB目前并不支持谓词筛选条件，仅RDB支持。谓词内方法为空时，默认全表更新。 | 1487| value | [ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket) | 是 | 要更新的数据。可以为null。 | 1488 1489**返回值：** 1490 1491| 类型 | 说明 | 1492| ---------------- | ------------------------------------------------------------ | 1493| Promise<number> | Promise对象。返回更新的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回更新的数据记录数。 | 1494 1495**错误码：** 1496 1497以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1498 1499| 错误码ID | 错误信息 | 1500| -------- | -------------------- | 1501| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1502| 15700013 | The DataShareHelper instance is already closed.| 1503 1504**示例：** 1505 1506```ts 1507import { dataSharePredicates, ValuesBucket } from '@kit.ArkData' 1508import { BusinessError } from '@kit.BasicServicesKit' 1509 1510let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1511let da = new dataSharePredicates.DataSharePredicates(); 1512da.equalTo("name", "ZhangSan"); 1513let key1: string = "name"; 1514let value1: string = "roe1" 1515let key2: string = "age"; 1516let value2: number = 21 1517let key3: string = "salary"; 1518let value3: number = 20.5; 1519const va: ValuesBucket = { 1520 key1: value1, 1521 key2: value2, 1522 key3: value3, 1523} 1524try { 1525 if (dataShareHelper != undefined) { 1526 (dataShareHelper as dataShare.DataShareHelper).update(uri, da, va).then((data: number) => { 1527 console.info("update succeed, data : " + data); 1528 }).catch((err: BusinessError) => { 1529 console.error(`update error: code: ${err.code}, message: ${err.message} `); 1530 }); 1531 } 1532} catch (err) { 1533 let code = (err as BusinessError).code; 1534 let message = (err as BusinessError).message; 1535 console.error(`update error: code: ${code}, message: ${message} `); 1536}; 1537``` 1538 1539### batchUpdate<sup>12+</sup> 1540 1541batchUpdate(operations: Record<string, Array<UpdateOperation>>): Promise<Record<string, Array<number>>> 1542 1543批量更新数据库中的数据记录，Record最多支持900K的数据，超出该限制更新失败；该接口的事务性取决于provider（数据提供方）。使用Promise异步回调。 1544 1545**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1546 1547**参数：** 1548 1549| 参数名 | 类型 | 必填 | 说明 | 1550| ---------- | ------------------------------------------------------------ | ---- | -------------------------------------- | 1551| operations | Record<string, Array<[UpdateOperation](#updateoperation12)>> | 是 | 要更新数据的路径、筛选条件和数据集合。 | 1552 1553**返回值：** 1554 1555| 类型 | 说明 | 1556| ----------------------------------------------------- | ------------------------------------------------------------ | 1557| Promise<Record<string, Array<number>>> | Promise对象。返回更新的数据记录数集合，更新失败的UpdateOperation的数据记录数为-1。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回更新的数据记录数。 | 1558 1559**错误码：** 1560 1561以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1562 1563| 错误码ID | 错误信息 | 1564| -------- | ------------------------------------ | 1565| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1566| 15700000 | Inner error. | 1567| 15700013 | The DataShareHelper instance is already closed. | 1568 1569**示例：** 1570 1571```ts 1572import { dataSharePredicates, ValuesBucket } from '@kit.ArkData' 1573import { BusinessError } from '@kit.BasicServicesKit' 1574 1575let record: Record<string, Array<dataShare.UpdateOperation>> = {}; 1576let operations1: Array<dataShare.UpdateOperation> = []; 1577let operations2: Array<dataShare.UpdateOperation> = []; 1578 1579let pre1: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1580pre1.equalTo("name", "ZhangSan"); 1581let vb1: ValuesBucket = { 1582 "name": "ZhangSan1", 1583} 1584let operation1: dataShare.UpdateOperation = { 1585 values: vb1, 1586 predicates: pre1 1587} 1588operations1.push(operation1); 1589 1590let pre2: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates(); 1591pre2.equalTo("name", "ZhangSan2"); 1592let vb2: ValuesBucket = { 1593 "name": "ZhangSan3", 1594} 1595let operation2: dataShare.UpdateOperation = { 1596 values: vb2, 1597 predicates: pre2 1598} 1599operations2.push(operation2); 1600record["uri1"] = operations1; 1601record["uri2"] = operations2; 1602 1603try { 1604 if (dataShareHelper != undefined) { 1605 (dataShareHelper as dataShare.DataShareHelper).batchUpdate(record).then((data: Record<string, Array<number>>) => { 1606 // 遍历data获取每条数据的更新结果， value为更新成功的数据记录数，若小于0，说明该次更新失败 1607 let a = Object.entries(data); 1608 for (let i = 0; i < a.length; i++) { 1609 let key = a[i][0]; 1610 let values = a[i][1] 1611 console.info(`Update uri:${key}`); 1612 for (const value of values) { 1613 console.info(`Update result:${value}`); 1614 } 1615 } 1616 }).catch((err: BusinessError) => { 1617 console.error(`Batch update error: code: ${err.code}, message: ${err.message} `); 1618 }); 1619 } 1620} catch (err) { 1621 let code = (err as BusinessError).code; 1622 let message = (err as BusinessError).message; 1623 console.error(`Batch update error: code: ${code}, message: ${message} `); 1624}; 1625``` 1626 1627### batchInsert 1628 1629batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void 1630 1631将批量数据插入数据库。使用callback异步回调。暂不支持静默访问。 1632 1633**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1634 1635**参数：** 1636 1637| 参数名 | 类型 | 必填 | 说明 | 1638| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1639| uri | string | 是 | 要插入的数据的路径。 | 1640| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 要插入的数据。 | 1641| callback | AsyncCallback<number> | 是 | 回调函数。当将批量数据插入数据库成功，err为undefined，data为获取到的插入的数据记录数；否则为错误对象。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 1642 1643**错误码：** 1644 1645以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1646 1647| 错误码ID | 错误信息 | 1648| -------- | -------------------- | 1649| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1650| 15700013 | The DataShareHelper instance is already closed.| 1651 1652**示例：** 1653 1654```ts 1655import { ValuesBucket } from '@kit.ArkData' 1656import { BusinessError } from '@kit.BasicServicesKit' 1657 1658let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1659let key1: string = "name"; 1660let value11: string = "roe11" 1661let key2: string = "age"; 1662let value21: number = 21; 1663let key3: string = "salary"; 1664let value31: number = 20.5; 1665let valuesBucket1: ValuesBucket = { 1666 key1: value11, 1667 key2: value21, 1668 key3: value31, 1669} 1670let vbs = new Array(valuesBucket1); 1671try { 1672 if (dataShareHelper != undefined) { 1673 (dataShareHelper as dataShare.DataShareHelper).batchInsert(uri, vbs, (err, data) => { 1674 if (err !== undefined) { 1675 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 1676 return; 1677 } 1678 console.info("batchInsert succeed, data : " + data); 1679 }); 1680 } 1681} catch (err) { 1682 let code = (err as BusinessError).code; 1683 let message = (err as BusinessError).message; 1684 console.error(`batchInsert error: code: ${code}, message: ${message} `); 1685}; 1686``` 1687 1688### batchInsert 1689 1690batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number> 1691 1692将批量数据插入数据库。使用Promise异步回调。暂不支持静默访问。 1693 1694**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1695 1696**参数：** 1697 1698| 参数名 | 类型 | 必填 | 说明 | 1699| ------ | ------------------------------------------------------------ | ---- | ------------------------ | 1700| uri | string | 是 | 要插入的数据的路径。 | 1701| values | Array<[ValuesBucket](js-apis-data-valuesBucket.md#valuesbucket)> | 是 | 要插入的数据。 | 1702 1703**返回值：** 1704 1705| 类型 | 说明 | 1706| ---------------- | ------------------------------------------------------------ | 1707| Promise<number> | Promise对象。返回插入的数据记录数。<br />因部分数据库（如KVDB）的相应接口并不提供相应支持，故若服务端使用此数据库，则此Promise也无法返回插入的数据记录数。 | 1708 1709**错误码：** 1710 1711以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1712 1713| 错误码ID | 错误信息 | 1714| -------- | -------------------- | 1715| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1716| 15700013 | The DataShareHelper instance is already closed.| 1717 1718**示例：** 1719 1720```ts 1721import { ValuesBucket } from '@kit.ArkData' 1722import { BusinessError } from '@kit.BasicServicesKit' 1723 1724let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1725let key1: string = "name"; 1726let value11: string = "roe11" 1727let key2: string = "age"; 1728let value21: number = 21; 1729let key3: string = "salary"; 1730let value31: number = 20.5; 1731let valuesBucket1: ValuesBucket = { 1732 key1: value11, 1733 key2: value21, 1734 key3: value31, 1735} 1736let vbs = new Array(valuesBucket1); 1737try { 1738 if (dataShareHelper != undefined) { 1739 (dataShareHelper as dataShare.DataShareHelper).batchInsert(uri, vbs).then((data: number) => { 1740 console.info("batchInsert succeed, data : " + data); 1741 }).catch((err: BusinessError) => { 1742 console.error(`batchInsert error: code: ${err.code}, message: ${err.message} `); 1743 }); 1744 } 1745} catch (err) { 1746 let code = (err as BusinessError).code; 1747 let message = (err as BusinessError).message 1748 console.error(`batchInsert error: code: ${code}, message: ${message} `); 1749}; 1750``` 1751 1752### close<sup>12+</sup> 1753 1754close(): Promise <void> 1755 1756关闭DataShareHelper实例，调用后该实例失效。使用Promise异步回调。 1757 1758**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1759 1760**返回值：** 1761 1762| 类型 | 说明 | 1763| ------------------- | -------------------------------------- | 1764| Promise<void> | 无返回结果的Promise对象。 | 1765 1766**错误码：** 1767 1768以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 1769 1770| 错误码ID | 错误信息 | 1771| -------- | ------------ | 1772| 15700000 | Inner error. | 1773 1774**示例：** 1775 1776```ts 1777if (dataShareHelper != undefined) { 1778 (dataShareHelper as dataShare.DataShareHelper).close(); 1779} 1780``` 1781 1782### normalizeUri 1783 1784normalizeUri(uri: string, callback: AsyncCallback<string>): void 1785 1786将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用callback异步回调。暂不支持静默访问。 1787 1788**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1789 1790**参数：** 1791 1792| 参数名 | 类型 | 必填 | 说明 | 1793| -------- | ---------------------- | ---- | -------------------------------------------------------- | 1794| uri | string | 是 | 要规范化的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 1795| callback | AsyncCallback<string> | 是 | 回调函数。当将给定的DataShare URI转换为规范化URI成功，err为undefined，data为获取到的规范化URI（如果支持URI规范化，则返回规范化URI，否则返回空）；否则为错误对象。 | 1796 1797**错误码：** 1798 1799以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1800 1801| 错误码ID | 错误信息 | 1802| -------- | -------------------- | 1803| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1804| 15700013 | The DataShareHelper instance is already closed.| 1805 1806**示例：** 1807 1808```ts 1809import { BusinessError } from '@kit.BasicServicesKit' 1810 1811let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1812if (dataShareHelper != undefined) { 1813 (dataShareHelper as dataShare.DataShareHelper).normalizeUri(uri, (err: BusinessError, data: string) => { 1814 if (err !== undefined) { 1815 console.info("normalizeUri failed, error message : " + err); 1816 } else { 1817 console.info("normalizeUri = " + data); 1818 } 1819 }); 1820} 1821``` 1822 1823### normalizeUri 1824 1825normalizeUri(uri: string): Promise<string> 1826 1827将给定的DataShare URI转换为规范化URI，规范化URI可供跨设备使用，DataShare URI仅供本地环境中使用。使用Promise异步回调。暂不支持静默访问。 1828 1829**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1830 1831**参数：** 1832 1833| 参数名 | 类型 | 必填 | 说明 | 1834| ---- | ------ | ---- | ----------------------------------------- | 1835| uri | string | 是 | 要规范化的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 1836 1837**返回值：** 1838 1839| 类型 | 说明 | 1840| ---------------- | ---------------------------------------------- | 1841| Promise<string> | Promise对象。如果支持URI规范化，则返回规范化URI，否则返回空。 | 1842 1843**错误码：** 1844 1845以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1846 1847| 错误码ID | 错误信息 | 1848| -------- | -------------------- | 1849| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1850| 15700013 | The DataShareHelper instance is already closed.| 1851 1852**示例：** 1853 1854```ts 1855import { BusinessError } from '@kit.BasicServicesKit' 1856 1857let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1858if (dataShareHelper != undefined) { 1859 (dataShareHelper as dataShare.DataShareHelper).normalizeUri(uri).then((data: string) => { 1860 console.info("normalizeUri = " + data); 1861 }).catch((err: BusinessError) => { 1862 console.info("normalizeUri failed, error message : " + err); 1863 }); 1864} 1865``` 1866 1867### denormalizeUri 1868 1869denormalizeUri(uri: string, callback: AsyncCallback<string>): void 1870 1871将指定的URI转换为非规范化URI。使用callback异步回调。暂不支持静默访问。 1872 1873**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1874 1875**参数：** 1876 1877| 参数名 | 类型 | 必填 | 说明 | 1878| -------- | ---------------------- | ---- | --------------------------------------------------- | 1879| uri | string | 是 | 要反规范化的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 1880| callback | AsyncCallback<string> | 是 | 回调函数。当将指定的URI转换为非规范化URI，err为undefined，data为获取到的反规范化URI（如果反规范化成功，则返回反规范化的URI；如果无需进行反规范化，则返回原始URI；若不支持则返回空）；否则为错误对象。 | 1881 1882**错误码：** 1883 1884以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1885 1886| 错误码ID | 错误信息 | 1887| -------- | -------------------- | 1888| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1889| 15700013 | The DataShareHelper instance is already closed.| 1890 1891**示例：** 1892 1893```ts 1894import { BusinessError } from '@kit.BasicServicesKit' 1895 1896let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1897if (dataShareHelper != undefined) { 1898 (dataShareHelper as dataShare.DataShareHelper).denormalizeUri(uri, (err: BusinessError, data: string) => { 1899 if (err !== undefined) { 1900 console.error("denormalizeUri failed, error message : " + err); 1901 } else { 1902 console.info("denormalizeUri = " + data); 1903 } 1904 }); 1905} 1906``` 1907 1908### denormalizeUri 1909 1910denormalizeUri(uri: string): Promise<string> 1911 1912将指定的URI转换为非规范化URI。使用Promise异步回调。暂不支持静默访问。 1913 1914**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1915 1916**参数：** 1917 1918| 参数名 | 类型 | 必填 | 说明 | 1919| ---- | ------ | ---- | ------------------------------------------- | 1920| uri | string | 是 | 要反规范化的[URI](../apis-arkts/js-apis-uri.md#uri)。 | 1921 1922**返回值：** 1923 1924| 类型 | 说明 | 1925| ---------------- | ----------------------------------------- | 1926| Promise<string> | Promise对象。如果反规范化成功，则返回反规范化的URI；如果无需执行任何操作，则返回原始URI；若不支持则返回空。 | 1927 1928**错误码：** 1929 1930以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1931 1932| 错误码ID | 错误信息 | 1933| -------- | -------------------- | 1934| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 1935| 15700013 | The DataShareHelper instance is already closed.| 1936 1937**示例：** 1938 1939```ts 1940import { BusinessError } from '@kit.BasicServicesKit' 1941 1942let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1943if (dataShareHelper != undefined) { 1944 (dataShareHelper as dataShare.DataShareHelper).denormalizeUri(uri).then((data: string) => { 1945 console.info("denormalizeUri = " + data); 1946 }).catch((err: BusinessError) => { 1947 console.error("denormalizeUri failed, error message : " + err); 1948 }); 1949} 1950``` 1951 1952### notifyChange 1953 1954notifyChange(uri: string, callback: AsyncCallback<void>): void 1955 1956通知已注册的观察者指定URI对应的数据资源已发生变更。使用callback异步回调。暂不支持静默访问。 1957 1958**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1959 1960**参数：** 1961 1962| 参数名 | 类型 | 必填 | 说明 | 1963| -------- | -------------------- | ---- | ------------------------ | 1964| uri | string | 是 | 表示指定的数据路径。 | 1965| callback | AsyncCallback<void> | 是 | 回调函数。当通知已注册的观察者指定URI对应的数据资源已发生变更成功，err为undefined；否则为错误对象。 | 1966 1967**错误码：** 1968 1969以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 1970 1971| 错误码ID | 错误信息 | 1972| -------- | -------------------- | 1973| 401 | Parameter error.Mandatory parameters are left unspecified.| 1974| 15700013 | The DataShareHelper instance is already closed.| 1975 1976**示例：** 1977 1978```ts 1979let uri = ("datashare:///com.samples.datasharetest.DataShare"); 1980if (dataShareHelper != undefined) { 1981 (dataShareHelper as dataShare.DataShareHelper).notifyChange(uri, () => { 1982 console.info("***** notifyChange *****"); 1983 }); 1984} 1985``` 1986 1987### notifyChange 1988 1989notifyChange(uri: string): Promise<void> 1990 1991通知已注册的观察者指定URI对应的数据资源已发生变更。使用Promise异步回调。暂不支持静默访问。 1992 1993**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 1994 1995**参数：** 1996 1997| 参数名 | 类型 | 必填 | 说明 | 1998| ---- | ------ | ---- | -------------------- | 1999| uri | string | 是 | 表示指定的数据路径。 | 2000 2001**返回值：** 2002 2003| 类型 | 说明 | 2004| -------------- | --------------------- | 2005| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2006 2007**错误码：** 2008 2009以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 2010 2011| 错误码ID | 错误信息 | 2012| -------- | -------------------- | 2013| 401 | Parameter error.Mandatory parameters are left unspecified.| 2014| 15700013 | The DataShareHelper instance is already closed.| 2015 2016**示例：** 2017 2018```ts 2019let uri = ("datashare:///com.samples.datasharetest.DataShare"); 2020if (dataShareHelper != undefined) { 2021 (dataShareHelper as dataShare.DataShareHelper).notifyChange(uri); 2022} 2023``` 2024 2025### notifyChange<sup>12+</sup> 2026 2027notifyChange(data: ChangeInfo): Promise<void> 2028 2029通知已注册的观察者指定URI对应的数据资源已发生变更类型及变更内容。使用Promise异步回调。仅支持非静默访问。 2030 2031**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 2032 2033**参数：** 2034 2035| 参数名 | 类型 | 必填 | 说明 | 2036| ---- | ------ | ---- | -------------------- | 2037| data | [ChangeInfo](#changeinfo12) | 是 | 表示数据变更类型、变化的uri、变更的数据内容。 | 2038 2039**返回值：** 2040 2041| 类型 | 说明 | 2042| -------------- | --------------------- | 2043| Promise<void> | 无返回结果的Promise对象。 | 2044 2045**错误码：** 2046 2047以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)和[通用错误码](../errorcode-universal.md)。 2048 2049| 错误码ID | 错误信息 | 2050| -------- | -------------------- | 2051| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified; 2.Incorrect parameters types.| 2052| 15700013 | The DataShareHelper instance is already closed.| 2053 2054**示例：** 2055 2056```ts 2057import { ValuesBucket } from '@kit.ArkData' 2058 2059let dsUri = ("datashare:///com.acts.datasharetest"); 2060let bucket1: ValuesBucket = {"name": "LiSi"}; 2061let bucket2: ValuesBucket = {"name": "WangWu"}; 2062let bucket3: ValuesBucket = {"name": "ZhaoLiu"}; 2063let people: Array<ValuesBucket> = new Array(bucket1, bucket2, bucket3); 2064let changeData:dataShare.ChangeInfo= { type:dataShare.ChangeType.INSERT, uri:dsUri, values:people}; 2065if (dataShareHelper != undefined) { 2066 (dataShareHelper as dataShare.DataShareHelper).notifyChange(changeData); 2067} 2068```