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