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