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> - 本模块接口仅可在Stage模型下使用。 16 17 18## 导入模块 19 20```ts 21import { dataShare } from '@kit.ArkData'; 22``` 23 24 25## dataShare.createDataProxyHandle<sup>20+</sup> 26 27createDataProxyHandle(): Promise<DataProxyHandle> 28 29创建DataProxyHandle实例。使用Promise异步回调。 30 31**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 32 33**返回值：** 34 35| 类型 | 说明 | 36| -------------------------------------------------- | -------------------------------------- | 37| Promise<[DataProxyHandle](#dataproxyhandle20)> | Promise对象。返回DataProxyHandle实例。 | 38 39**错误码：** 40 41错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 42 43| 错误码ID | 错误信息 | 44| -------- | ---------------------------------------------------- | 45| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally. | 46 47**示例：** 48```ts 49import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 50import { BusinessError } from '@kit.BasicServicesKit'; 51 52export default class EntryAbility extends UIAbility { 53 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 54 dataShare.createDataProxyHandle().then((dataProxyHandle) => { 55 console.info("createDataProxyHandle succeed"); 56 }).catch((err: BusinessError) => { 57 console.error(`createDataProxyHandle error: code: ${err.code}, message: ${err.message}`); 58 }); 59 }; 60}; 61``` 62 63## ChangeType<sup>20+</sup> 64 65数据变更类型枚举。 66 67**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 68 69| 名称 | 值 | 说明 | 70| ---------| ------------| --------------| 71| INSERT | 0 | 表示数据添加。| 72| DELETE | 1 | 表示数据删除。| 73| UPDATE | 2 | 表示数据更新。| 74 75## ProxyData<sup>20+</sup> 76 77共享配置的数据结构。 78 79**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 80 81| 名称 | 类型 | 只读 | 可选 | 说明 | 82| ---------- | ----------------------------------------------------------- | ----| ---- | -------------- | 83| uri | string | 否 | 否 | 共享配置的全局唯一标识。固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复。字符串长度不超过256个字节。 | 84| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) | 否 | 是 | 共享配置的值。不填则为空字符串。字符串长度不超过4096个字节。当首次发布共享配置时，如果未填写，将默认设置为空字符串。在更新共享配置时，如果未填写，共享配置的值将不会被更新。 | 85| allowList | string\[] | 否 | 是 | 允许订阅和读取共享配置的应用程序列表。不填则为空的字符串数组。数组最大长度为256，超过256的部分不生效。数组中每个元素为应用的[appIdentifier](../../quick-start/common_problem_of_application.md#什么是appidentifier)，单个appIdentifier最大长度128字节，超过128字节的appIdentifier不会生效。当首次发布共享配置时，如果未填写，将默认为空的允许列表。在更新共享配置时，如果未填写，共享配置的允许列表将不会被更新。一个空的允许列表表示只有发布者能够访问该共享配置。 | 86 87## DataProxyChangeInfo<sup>20+</sup> 88 89通知订阅者共享配置变更的数据结构。包括数据变更类型、变化的URI、变更的数据内容。 90 91**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 92 93| 名称 | 类型 | 只读 | 可选 | 说明 | 94| ---------- | ----------------------------------------------------------- | ----| ---- | -------------- | 95| type | [ChangeType](#changetype20) | 否 | 否 | 通知变更的类型。 | 96| uri | string | 否 | 否 | 通知变更指定URI。| 97| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) | 否 | 否 | 更新的数据。 | 98 99## DataProxyErrorCode<sup>20+</sup> 100 101配置共享批量操作返回值的状态码枚举。 102 103**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 104 105| 名称 | 值 | 说明 | 106| ---------- | ----------------------------------------------------------| -------------- | 107| SUCCESS | 0 | 表示操作成功。 | 108| URI_NOT_EXIST | 1 | URI不存在或取消订阅一个未订阅过的URI。| 109| NO_PERMISSION | 2 | 没有权限在该URI上执行此操作。 | 110| OVER_LIMIT | 3 | 表示当前应用发布的配置超过32个配置的上限。 | 111 112## DataProxyResult<sup>20+</sup> 113 114配置共享批量操作结果的数据结构。 115 116**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 117 118| 名称 | 类型 | 只读 | 可选 | 说明 | 119| ---------- | ----------------------------------------------------------- | ---- | ---- | -------------- | 120| uri | string | 否 | 否 | 被操作的URI。固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 121| result | [DataProxyErrorCode](#dataproxyerrorcode20) | 否 | 否 | 操作结果的错误码。| 122 123## DataProxyGetResult<sup>20+</sup> 124 125配置共享批量获取操作结果的数据结构。 126 127**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 128 129| 名称 | 类型 | 只读 | 可选 | 说明 | 130| ---------- | ----------------------------------------------------------- | ---- | ---- | -------------- | 131| uri | string | 否 | 否 | 被操作的URI。固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 132| result | [DataProxyErrorCode](#dataproxyerrorcode20) | 否 | 否 | 操作结果的错误码。| 133| value | [ValueType](js-apis-data-valuesBucket.md#valuetype) \| undefined | 否 | 否 | 如果获取操作成功，则为共享配置的值；如果获取操作失败，则未定义。| 134| allowList | string\[] \| undefined | 否 | 否 | 如果获取操作成功，则为共享配置的允许列表；如果获取操作失败，则未定义。只有发布者才能获取允许列表，其他应用只能获取值。| 135 136## DataProxyType<sup>20+</sup> 137 138数据代理类型的枚举。 139 140**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 141 142| 名称 | 值 | 说明 | 143| ---------- | ---------------------------------------------------------| -------------- | 144| SHARED_CONFIG | 0 | 表示应用之间的共享配置。 | 145 146## DataProxyConfig<sup>20+</sup> 147 148数据代理操作配置的数据结构。 149 150**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 151 152| 名称 | 类型 | 只读 | 可选 | 说明 | 153| ---------- | ----------------------------------------------------------- | ---- | ---- | -------------- | 154| type | [DataProxyType](#dataproxytype20) | 否 | 否 | 数据代理操作的类型。 | 155 156 157## DataProxyHandle<sup>20+</sup> 158 159数据代理操作句柄的实例，可使用此实例访问或管理共享配置信息。在调用DataProxyHandle提供的方法前，需要先通过[createDataProxyHandle](#datasharecreatedataproxyhandle20)构建一个实例。 160 161### on('dataChange')<sup>20+</sup> 162 163on(event: 'dataChange', uris: string[], config: DataProxyConfig, callback: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] 164 165订阅指定URI对应共享配置变更事件。若订阅者已注册变更通知，当配置发布方修改配置时，订阅者将会接收到callback通知，通知携带数据变更类型、变化的URI、变更的共享配置内容。使用callback异步回调。该功能不允许跨用户订阅通知，不允许订阅未发布的配置。订阅成功后若权限被收回，则后续不再通知订阅者。 166 167触发通知：配置发布方调用[publish](#publish20)、[delete](#delete20)接口发布、删除配置时会自动触发通知。 168 169**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 170 171**参数：** 172 173| 参数名 | 类型 | 必填 | 说明 | 174| -------- | ----------------------------- | ---- | ------------------------ | 175| event | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'，当配置发布方修改配置时，触发该事件。 | 176| uris | string\[] | 是 | 表示要订阅的共享配置对应的URI数组，数组最大长度为32。URI固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 177| config | [DataProxyConfig](#dataproxyconfig20) | 是 | 表示数据代理操作的配置。 | 178| callback | AsyncCallback<[DataProxyChangeInfo](#dataproxychangeinfo20)\[]> | 是 | 回调函数。当配置发布方修改配置时会回调该函数。| 179 180**返回值：** 181 182| 类型 | 说明 | 183| ---------------- | ------------------------------------------------------------ | 184| [DataProxyResult](#dataproxyresult20)\[] | 批量操作的结果数组。| 185 186**错误码：** 187 188以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 189 190| 错误码ID | 错误信息 | 191| -------- | -------------------- | 192| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally.| 193| 15700014 | The parameter format is incorrect or the value range is invalid.| 194 195**示例：** 196 197```ts 198const urisToWatch: string[] = 199 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 200const config: dataShare.DataProxyConfig = { 201 type: dataShare.DataProxyType.SHARED_CONFIG, 202}; 203const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => { 204 if (err) { 205 console.error('err:', err); 206 } else { 207 changes.forEach((change) => { 208 console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`); 209 }); 210 } 211}; 212const results: dataShare.DataProxyResult[] = dataProxyHandle.on('dataChange', urisToWatch, config, callback); 213results.forEach((result) => { 214 console.info(`URI: ${result.uri}, Result: ${result.result}`); 215}); 216``` 217 218### off('dataChange')<sup>20+</sup> 219 220off(event: 'dataChange', uris: string[], config: DataProxyConfig, callback?: AsyncCallback<DataProxyChangeInfo[]>): DataProxyResult[] 221 222取消订阅指定URI对应代理数据变更事件。 223 224**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 225 226**参数：** 227 228| 参数名 | 类型 | 必填 | 说明 | 229| -------- | ----------------------------- | ---- | ------------------------ | 230| event | string | 是 | 订阅的事件/回调类型，支持的事件为'dataChange'。 | 231| uris | string\[] | 是 | 表示要取消订阅的共享配置对应的URI数组，数组最大长度为32。URI固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 232| config | [DataProxyConfig](#dataproxyconfig20) | 是 | 表示数据代理操作的配置。 | 233| callback | AsyncCallback<[DataProxyChangeInfo](#dataproxychangeinfo20)\[]> | 否 | 回调函数。表示指定取消订阅的callback通知，如果为空、undefined或null，则取消订阅这些URI下所有的通知事件。| 234 235**返回值：** 236 237| 类型 | 说明 | 238| ---------------- | ------------------------------------------------------------ | 239| [DataProxyResult](#dataproxyresult20)\[] | 批量操作的结果数组。| 240 241**错误码：** 242 243以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 244 245| 错误码ID | 错误信息 | 246| -------- | -------------------- | 247| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally.| 248| 15700014 | The parameter format is incorrect or the value range is invalid.| 249 250**示例：** 251 252```ts 253const urisToUnWatch: string[] = 254 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 255const config: dataShare.DataProxyConfig = { 256 type: dataShare.DataProxyType.SHARED_CONFIG, 257}; 258const callback = (err: BusinessError<void>, changes: dataShare.DataProxyChangeInfo[]): void => { 259 if (err) { 260 console.error('err:', err); 261 } else { 262 changes.forEach((change) => { 263 console.info(`Change Type: ${change.type}, URI: ${change.uri}, Value: ${change.value}`); 264 }); 265 } 266}; 267const results: dataShare.DataProxyResult[] = dataProxyHandle.off('dataChange', urisToUnWatch, config, callback); 268results.forEach((result) => { 269 console.info(`URI: ${result.uri}, Result: ${result.result}`); 270}); 271``` 272 273### publish<sup>20+</sup> 274 275publish(data: ProxyData[], config: DataProxyConfig): Promise<DataProxyResult[]> 276 277发布共享配置项。发布后，发布者和允许列表中指定的应用可以访问该共享配置项。如果要发布的URI已经存在，则更新对应的共享配置项。如果发布的配置项中存在任一URI的长度超出上限或者格式校验失败，则当前发布操作失败。只有发布者才允许更新共享配置项，每个应用支持最多32个共享配置。 278 279**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 280 281**参数：** 282 283| 参数名 | 类型 | 必填 | 说明 | 284| -------- | ----------------------------- | ---- | ------------------------ | 285| data | [ProxyData](#proxydata20)\[] | 是 | 表示需要创建或者更新的共享配置项数组。数组最大长度为32。 | 286| config | [DataProxyConfig](#dataproxyconfig20) | 是 | 表示数据代理操作的配置。 | 287 288**返回值：** 289 290| 类型 | 说明 | 291| ---------------- | ------------------------------------------------------------ | 292| Promise<[DataProxyResult](#dataproxyresult20)\[]> | Promise对象。返回批量操作的结果数组。| 293 294**错误码：** 295 296以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 297 298| 错误码ID | 错误信息 | 299| -------- | -------------------- | 300| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally.| 301| 15700014 | The parameter format is incorrect or the value range is invalid.| 302 303**示例：** 304 305```ts 306const newConfigData: dataShare.ProxyData[] = [{ 307 uri: 'datashareproxy://com.example.app1/config1', 308 value: 'Value1', 309 allowList: ['com.example.app2', 'com.example.app3'], 310}, { 311 uri: 'datashareproxy://com.example.app1/config2', 312 value: 'Value2', 313 allowList: ['com.example.app3', 'com.example.app4'], 314},]; 315const config: dataShare.DataProxyConfig = { 316 type: dataShare.DataProxyType.SHARED_CONFIG, 317}; 318dataProxyHandle.publish(newConfigData, config).then((results: dataShare.DataProxyResult[]) => { 319 results.forEach((result) => { 320 console.info(`URI: ${result.uri}, Result: ${result.result}`); 321 }); 322}).catch((error: BusinessError) => { 323 console.error('Error publishing config:', error); 324}); 325``` 326 327### delete<sup>20+</sup> 328 329delete(uris: string[], config: DataProxyConfig): Promise<DataProxyResult[]> 330 331根据URI删除指定的共享配置项，只有配置发布方能删除共享配置项。 332 333**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 334 335**参数：** 336 337| 参数名 | 类型 | 必填 | 说明 | 338| -------- | ----------------------------- | ---- | ------------------------ | 339| uris | string\[] | 是 | 表示需要删除的共享配置对应的URI数组，数组最大长度为32。URI固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 340| config | [DataProxyConfig](#dataproxyconfig20) | 是 | 表示共享配置的类型。 | 341 342**返回值：** 343 344| 类型 | 说明 | 345| ---------------- | ------------------------------------------------------------ | 346| Promise<[DataProxyResult](#dataproxyresult20)\[]> | Promise对象。返回批量操作的结果数组。| 347 348**错误码：** 349 350以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 351 352| 错误码ID | 错误信息 | 353| -------- | -------------------- | 354| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally.| 355| 15700014 | The parameter format is incorrect or the value range is invalid.| 356 357**示例：** 358 359```ts 360const urisToDelete: string[] = 361 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 362const config: dataShare.DataProxyConfig = { 363 type: dataShare.DataProxyType.SHARED_CONFIG, 364}; 365dataProxyHandle.delete(urisToDelete, config).then((results: dataShare.DataProxyResult[]) => { 366 results.forEach((result) => { 367 console.info(`URI: ${result.uri}, Result: ${result.result}`); 368 }); 369}).catch((error: BusinessError) => { 370 console.error('Error deleting config:', error); 371}); 372``` 373 374### get<sup>20+</sup> 375 376get(uris: string[], config: DataProxyConfig): Promise<DataProxyGetResult[]> 377 378根据URI获取指定的共享配置项。只有发布者和允许列表中指定的应用可以访问该共享配置项。 379 380**系统能力：** SystemCapability.DistributedDataManager.DataShare.Consumer 381 382**参数：** 383 384| 参数名 | 类型 | 必填 | 说明 | 385| -------- | ----------------------------- | ---- | ------------------------ | 386| uris | string\[] | 是 | 表示需要获取的共享配置的URI数组，数组最大长度为32。URI固定格式为`"datashareproxy://{bundleName}/{path}"`，其中bundleName为配置发布方应用的bundleName，path可随意填写，但同一应用内不允许重复，字符串长度不超过256个字节。 | 387| config | [DataProxyConfig](#dataproxyconfig20) | 是 | 表示共享配置的类型。 | 388 389**返回值：** 390 391| 类型 | 说明 | 392| ---------------- | ------------------------------------------------------------ | 393| Promise<[DataProxyGetResult](#dataproxygetresult20)\[]> | Promise对象。返回批量获取操作的结果数组。| 394 395**错误码：** 396 397以下错误码的详细介绍请参见[数据共享错误码](errorcode-datashare.md)。 398 399| 错误码ID | 错误信息 | 400| -------- | -------------------- | 401| 15700000 | Inner error. Possible causes: The service is not ready or is being restarted abnormally.| 402| 15700014 | The parameter format is incorrect or the value range is invalid.| 403 404**示例：** 405 406```ts 407const urisToGet: string[] = 408 ['datashareproxy://com.example.app1/config1', 'datashareproxy://com.example.app1/config2',]; 409const config: dataShare.DataProxyConfig = { 410 type: dataShare.DataProxyType.SHARED_CONFIG, 411}; 412dataProxyHandle.get(urisToGet, config).then((results: dataShare.DataProxyGetResult[]) => { 413 results.forEach((result) => { 414 console.info(`URI: ${result.uri}, Result: ${result.result}, AllowList: ${result.allowList}`); 415 }); 416}).catch((error: BusinessError) => { 417 console.error('Error getting config:', error); 418}); 419```