1# @ohos.data.unifiedDataChannel (标准化数据通路) 2 3本模块为统一数据管理框架（Unified Data Management Framework,UDMF）的组成部分，针对多对多跨应用数据共享的不同业务场景提供了标准化的数据通路，提供了标准化的数据接入与读取接口。同时对文本、图片等数据类型提供了标准化定义，方便不同应用间进行数据交互，减少数据类型适配的工作量。 4 5> **说明：** 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { unifiedDataChannel } from '@kit.ArkData'; 13``` 14 15## ShareOptions<sup>12+</sup> 16 17UDMF支持的设备内使用范围类型枚举。 18 19**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 20 21**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 22 23| 名称 | 值 | 说明 | 24|-------------|---|-------------------| 25| IN_APP | 0 | 表示允许在本设备同应用内使用。 | 26| CROSS_APP | 1 | 表示允许在本设备内跨应用使用。 | 27 28## GetDelayData<sup>12+</sup> 29 30type GetDelayData = (type: string) => UnifiedData 31 32对UnifiedData的延迟封装，支持延迟获取数据。当前只支持同设备剪贴板场景，后续场景待开发。 33 34**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 37 38**参数：** 39 40| 参数名 | 类型 | 必填 | 说明 | 41| -------- | -------- | -------- | -------- | 42| type | string | 是 | 作为延迟封装的标识。 | 43 44**返回值：** 45 46| 类型 | 说明 | 47| ---------------------------------------- |-------------------------| 48| [UnifiedData](#unifieddata) | 当延迟封装触发时，返回一个UnifiedData对象。 | 49 50**示例：** 51 52```ts 53import { uniformTypeDescriptor } from '@kit.ArkData'; 54 55let getDelayData: unifiedDataChannel.GetDelayData = ((type: string) => { 56 if (type == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 57 let text = new unifiedDataChannel.Text(); 58 text.details = { 59 Key: 'textKey', 60 Value: 'textValue', 61 }; 62 let textData = new unifiedDataChannel.UnifiedData(text); 63 return textData; 64 } 65 return new unifiedDataChannel.UnifiedData(); 66}); 67``` 68 69## ValueType<sup>12+</sup> 70 71type ValueType = number | string | boolean | image.PixelMap | Want | ArrayBuffer | object | null | undefined 72 73用于表示统一数据记录允许的数据字段类型。 74 75**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 76 77**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 78 79| 类型 | 说明 | 80| -------- | -------- | 81| number | 表示number的类型。 | 82| string | 表示string的类型。 | 83| boolean | 表示boolean的类型。 | 84| image.PixelMap | 表示[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)的类型。 | 85| Want | 表示[Want](../apis-ability-kit/js-apis-app-ability-want.md)的类型。 | 86| ArrayBuffer | 表示ArrayBuffer的类型。 | 87| object | 表示object的类型。 | 88| null | 表示null。 | 89| undefined | 表示undefined。 | 90 91## UnifiedDataProperties<sup>12+</sup> 92 93定义统一数据对象中所有数据记录的属性，包含时间戳、标签、粘贴范围以及一些附加数据等。 94 95**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 96 97**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 98 99| 名称 | 类型 | 只读 | 可选 | 说明 | 100| -------- | -------- | -------- | -------- | -------- | 101| extras<sup>12+</sup> | Record<string, object> | 否 | 是 | 是一个字典类型对象，用于设置其他附加属性数据。非必填字段，默认值为空字典对象。 | 102| tag<sup>12+</sup> | string | 否 | 是 | 用户自定义标签。非必填字段，默认值为空字符串。 | 103| timestamp<sup>12+</sup> | Date | 是 | 是 | [UnifiedData](#unifieddata)的生成时间戳。默认值为1970年1月1日（UTC）。 | 104| shareOptions<sup>12+</sup> | [ShareOptions](#shareoptions12) | 否 | 是 | 指示[UnifiedData](#unifieddata)支持的设备内使用范围，非必填字段，默认值为CROSS_APP。 | 105| getDelayData<sup>12+</sup> | [GetDelayData](#getdelaydata12) | 否 | 是 | 延迟获取数据回调。当前只支持同设备剪贴板场景，后续场景待开发。非必填字段，默认值为undefined。 | 106 107**示例：** 108 109```ts 110import { uniformTypeDescriptor } from '@kit.ArkData'; 111 112let properties = new unifiedDataChannel.UnifiedDataProperties(); 113properties.extras = { 114 key: { 115 title: 'MyTitle', 116 content: 'MyContent' 117 } 118}; 119properties.tag = "this is tag of properties"; 120properties.shareOptions = unifiedDataChannel.ShareOptions.CROSS_APP; 121properties.getDelayData = ((type: string) => { 122 if (type == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 123 let text = new unifiedDataChannel.Text(); 124 text.details = { 125 Key: 'textKey', 126 Value: 'textValue', 127 }; 128 let textData = new unifiedDataChannel.UnifiedData(text); 129 return textData; 130 } 131 return new unifiedDataChannel.UnifiedData(); 132}); 133``` 134 135## UnifiedData 136 137表示UDMF统一数据对象，提供封装一组数据记录的方法。 138 139**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 140 141### 属性 142 143| 名称 | 类型 | 只读 | 可选 | 说明 | 144| -------- | -------- | -------- | -------- |-------------------------------------------------------------------------------------------------| 145| properties<sup>12+</sup> | [UnifiedDataProperties](#unifieddataproperties12) | 否 | 否 | 当前统一数据对象中所有数据记录的属性，包含时间戳、标签、粘贴范围以及一些附加数据等。<br />**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 146 147### constructor<sup>12+</sup> 148 149constructor() 150 151用于创建统一数据对象。 152 153**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 156 157**示例：** 158 159```ts 160let unifiedData = new unifiedDataChannel.UnifiedData(); 161``` 162 163### constructor 164 165constructor(record: UnifiedRecord) 166 167用于创建带有一条数据记录的统一数据对象。 168 169**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 170 171**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| ------ | ------------------------------- | ---- |-----------------------------------------| 177| record | [UnifiedRecord](#unifiedrecord) | 是 | 要添加到统一数据对象中的数据记录，该记录为UnifiedRecord或其子类对象。 | 178 179**错误码：** 180 181以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 182 183| **错误码ID** | **错误信息** | 184| ------------ | ------------------------------------------- | 185| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 186 187**示例：** 188 189```ts 190let text = new unifiedDataChannel.PlainText(); 191text.textContent = 'this is textContent of text'; 192let unifiedData = new unifiedDataChannel.UnifiedData(text); 193``` 194 195### addRecord 196 197addRecord(record: UnifiedRecord): void 198 199在当前统一数据对象中添加一条数据记录。 200 201**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 202 203**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------------------------------- | ---- |---------------------------------------------| 209| record | [UnifiedRecord](#unifiedrecord) | 是 | 要添加到统一数据对象中的数据记录，该记录为UnifiedRecord子类对象。| 210 211**错误码：** 212 213以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 214 215| **错误码ID** | **错误信息** | 216| ------------ | ------------------------------------------- | 217| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 218 219**示例：** 220 221```ts 222let text1 = new unifiedDataChannel.PlainText(); 223text1.textContent = 'this is textContent of text1'; 224let unifiedData = new unifiedDataChannel.UnifiedData(text1); 225 226let text2 = new unifiedDataChannel.PlainText(); 227text2.textContent = 'this is textContent of text2'; 228unifiedData.addRecord(text2); 229``` 230 231### getRecords 232 233getRecords(): Array\<UnifiedRecord\> 234 235将当前统一数据对象中的所有数据记录取出。通过本接口取出的数据为UnifiedRecord类型，需通过[getType](#gettype)获取数据类型后转为子类再使用。 236 237**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 238 239**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 240 241**返回值：** 242 243| 类型 | 说明 | 244| ---------------------------------------- |-------------------------| 245| Array\<[UnifiedRecord](#unifiedrecord)\> | 当前统一数据对象内所添加的记录。 | 246 247**示例：** 248 249```ts 250import { uniformTypeDescriptor } from '@kit.ArkData'; 251 252let text = new unifiedDataChannel.PlainText(); 253text.textContent = 'this is textContent of text'; 254let unifiedData = new unifiedDataChannel.UnifiedData(text); 255 256let link = new unifiedDataChannel.Hyperlink(); 257link.url = 'www.XXX.com'; 258unifiedData.addRecord(link); 259 260let records = unifiedData.getRecords(); 261for (let i = 0; i < records.length; i++) { 262 let record = records[i]; 263 if (record.getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 264 let plainText = record as unifiedDataChannel.PlainText; 265 console.info(`textContent: ${plainText.textContent}`); 266 } else if (record.getType() == uniformTypeDescriptor.UniformDataType.HYPERLINK) { 267 let hyperlink = record as unifiedDataChannel.Hyperlink; 268 console.info(`linkUrl: ${hyperlink.url}`); 269 } 270} 271``` 272 273### hasType<sup>12+</sup> 274 275hasType(type: string): boolean 276 277检查当前统一数据对象中是否有指定的数据类型。 278 279**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 280 281**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 282 283| 参数名 | 类型 | 必填 | 说明 | 284| ------ | ------------------------------- | ---- |---------------------------------------------| 285| type | string | 是 | 要查询的数据类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。| 286 287**返回值：** 288 289| 类型 | 说明 | 290| ---------------------------------------- |-------------------------| 291| boolean | 有指定的数据类型返回true，否则返回false。 | 292 293**错误码：** 294 295以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 296 297| **错误码ID** | **错误信息** | 298| ------------ | ------------------------------------------- | 299| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 300 301**示例：** 302 303```ts 304import { uniformTypeDescriptor } from '@kit.ArkData'; 305 306let text = new unifiedDataChannel.PlainText(); 307text.textContent = 'this is textContent of text'; 308let unifiedData = new unifiedDataChannel.UnifiedData(text); 309 310let link = new unifiedDataChannel.Hyperlink(); 311link.url = 'www.XXX.com'; 312unifiedData.addRecord(link); 313 314let hasPlainText = unifiedData.hasType(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT); 315let hasLink = unifiedData.hasType(uniformTypeDescriptor.UniformDataType.HYPERLINK); 316``` 317 318### getTypes<sup>12+</sup> 319 320getTypes(): Array\<string\> 321 322获取当前统一数据对象所有数据记录的类型。 323 324**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 325 326**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 327 328**返回值：** 329 330| 类型 | 说明 | 331| ---------------------------------------- |-------------------------| 332| Array\<string\> | [UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)类型的数组，表示当前统一数据对象所有数据记录对应的数据类型。 | 333 334**示例：** 335 336```ts 337let text = new unifiedDataChannel.PlainText(); 338text.textContent = 'this is textContent of text'; 339let unifiedData = new unifiedDataChannel.UnifiedData(text); 340 341let link = new unifiedDataChannel.Hyperlink(); 342link.url = 'www.XXX.com'; 343unifiedData.addRecord(link); 344 345let types = unifiedData.getTypes(); 346``` 347 348## Summary 349 350描述某一统一数据对象的数据摘要，包括所含数据类型及大小。 351 352**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 353 354**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 355 356| 名称 | 类型 | 只读 | 可选 | 说明 | 357| -------- | -------- | -------- | -------- | -------- | 358| summary | Record<string, number> | 否 | 否 | 是一个字典类型对象，key表示数据类型（见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)），value为统一数据对象中该类型记录大小总和（单位：Byte）。 | 359| totalSize | number | 否 | 否 | 统一数据对象内记录总大小（单位：Byte）。 | 360 361## UnifiedRecord 362 363对UDMF支持的数据内容的抽象定义，称为数据记录。一个统一数据对象内包含一条或多条数据记录，例如一条文本记录、一条图片记录、一条HTML记录等。 364 365### constructor<sup>12+</sup> 366 367constructor() 368 369用于创建数据记录。 370 371**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 372 373**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 374 375**示例：** 376 377```ts 378let unifiedRecord = new unifiedDataChannel.UnifiedRecord(); 379``` 380 381### constructor<sup>12+</sup> 382 383constructor(type: string, value: ValueType) 384 385用于创建指定类型和值的数据记录。<br />当参数value为[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)类型时，参数type必须对应为[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)中OPENHARMONY_PIXEL_MAP的值;<br />当参数value为[Want](../apis-ability-kit/js-apis-app-ability-want.md)类型时，参数type必须对应为[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)中OPENHARMONY_WANT的值。 386 387**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 388 389**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 390 391**参数：** 392 393| 参数名 | 类型 | 必填 | 说明 | 394| ------ | ------------------------------- | ---- |-----------------------------------------| 395| type | string | 是 | 要创建的数据记录的类型。 | 396| value | [ValueType](#valuetype12) | 是 | 要创建的数据记录的值。 | 397 398**错误码：** 399 400以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 401 402| **错误码ID** | **错误信息** | 403| ------------ | ------------------------------------------- | 404| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 405 406**示例：** 407 408```ts 409import { image } from '@kit.ImageKit'; 410import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 411import { Want } from '@kit.AbilityKit'; 412 413let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, 'this is value of text'); 414let link = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, 'www.XXX.com'); 415let object: Want = { 416 bundleName: 'com.example.myapplication', 417 abilityName: 'entryAbility', 418}; 419let wantRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_WANT, object); 420 421const color = new ArrayBuffer(96); 422let opts: image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 4, width: 6 } }; 423let pixelMap = image.createPixelMapSync(color, opts); 424let pixelMapRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP, pixelMap); 425 426let hyperlinkDetails : Record<string, string> = { 427 'attr1': 'value1', 428 'attr2': 'value2', 429} 430let hyperlink : uniformDataStruct.Hyperlink = { 431 uniformDataType:'general.hyperlink', 432 url : 'www.XXX.com', 433 description : 'This is the description of this hyperlink', 434 details : hyperlinkDetails, 435} 436let hyperlinkRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 437``` 438 439### getType 440 441getType(): string 442 443获取当前数据记录的类型。由于从统一数据对象中调用[getRecords](#getrecords)所取出的数据是UnifiedRecord对象，因此需要通过本接口查询此记录的具体类型，再将该UnifiedRecord对象转换为其子类，调用子类接口。 444 445**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 446 447**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 448 449**返回值：** 450 451| 类型 | 说明 | 452| ------ |------------------------------------------------------| 453| string | 当前数据记录对应的具体数据类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。| 454 455**示例：** 456 457```ts 458import { uniformTypeDescriptor } from '@kit.ArkData'; 459 460let text = new unifiedDataChannel.PlainText(); 461text.textContent = 'this is textContent of text'; 462let unifiedData = new unifiedDataChannel.UnifiedData(text); 463 464let records = unifiedData.getRecords(); 465if (records[0].getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 466 let plainText = records[0] as unifiedDataChannel.PlainText; 467 console.info(`textContent: ${plainText.textContent}`); 468} 469``` 470 471### getValue<sup>12+</sup> 472 473getValue(): ValueType 474 475获取当前数据记录的值。 476 477**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 478 479**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 480 481**返回值：** 482 483| 类型 | 说明 | 484| ------ |------------------------------------------------------| 485| [ValueType](#valuetype12) | 当前数据记录对应的值。 | 486 487**示例：** 488 489```ts 490import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 491 492let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, 'this is value of text'); 493let value = text.getValue(); 494 495let hyperlinkDetails : Record<string, string> = { 496 'attr1': 'value1', 497 'attr2': 'value2', 498} 499let hyperlink : uniformDataStruct.Hyperlink = { 500 uniformDataType:'general.hyperlink', 501 url : 'www.XXX.com', 502 description : 'This is the description of this hyperlink', 503 details : hyperlinkDetails, 504} 505let hyperlinkRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 506let hyperlinkValue = hyperlinkRecord.getValue(); 507``` 508 509## Text 510 511文本类型数据，是[UnifiedRecord](#unifiedrecord)的子类，也是文本类型数据的基类，用于描述文本类数据，推荐开发者优先使用Text的子类描述数据，如[PlainText](#plaintext)、[Hyperlink](#hyperlink)、[HTML](#html)等具体子类。 512 513**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 514 515**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 516 517| 名称 | 类型 | 只读 | 可选 | 说明 | 518| -------- | -------- | -------- | -------- | -------- | 519| details | Record<string, string> | 否 | 是 | 是一个字典类型对象，key和value都是string类型，用于描述文本内容。例如，可生成一个details内容为<br />{<br />"title":"标题",<br />"content":"内容"<br />}<br />的数据对象，用于描述一篇文章。非必填字段，默认值为空字典对象。 | 520 521**示例：** 522 523```ts 524let text = new unifiedDataChannel.Text(); 525text.details = { 526 title: 'MyTitle', 527 content: 'this is content', 528}; 529let unifiedData = new unifiedDataChannel.UnifiedData(text); 530``` 531 532## PlainText 533 534纯文本类型数据，是[Text](#text)的子类，用于描述纯文本类数据。 535 536**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 537 538**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 539 540| 名称 | 类型 | 只读 | 可选 | 说明 | 541| -------- | -------- | -------- | -------- | -------- | 542| textContent | string | 否 | 否 | 纯文本内容。 | 543| abstract | string | 否 | 是 | 纯文本摘要，非必填字段，默认值为空字符串。 | 544 545**示例：** 546 547```ts 548let text = new unifiedDataChannel.PlainText(); 549text.textContent = 'this is textContent'; 550text.abstract = 'this is abstract'; 551``` 552 553## Hyperlink 554 555超链接类型数据，是[Text](#text)的子类，用于描述超链接类型数据。 556 557**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 558 559**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 560 561| 名称 | 类型 | 只读 | 可选 | 说明 | 562| -------- | -------- | -------- | -------- | -------- | 563| url | string | 否 | 否 | 链接url。 | 564| description | string | 否 | 是 | 链接内容描述，非必填字段，默认值为空字符串。 | 565 566**示例：** 567 568```ts 569let link = new unifiedDataChannel.Hyperlink(); 570link.url = 'www.XXX.com'; 571link.description = 'this is description'; 572``` 573 574## HTML 575 576HTML类型数据，是[Text](#text)的子类，用于描述超文本标记语言数据。 577 578**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 579 580**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 581 582| 名称 | 类型 | 只读 | 可选 | 说明 | 583| -------- | -------- | -------- | -------- | -------- | 584| htmlContent | string | 否 | 否 | html格式内容。 | 585| plainContent | string | 否 | 是 | 去除html标签后的纯文本内容，非必填字段，默认值为空字符串。 | 586 587**示例：** 588 589```ts 590let html = new unifiedDataChannel.HTML(); 591html.htmlContent = '<div><p>标题</p></div>'; 592html.plainContent = 'this is plainContent'; 593``` 594 595## File 596 597File类型数据，是[UnifiedRecord](#unifiedrecord)的子类，也是文件类型数据的基类，用于描述文件类型数据，推荐开发者优先使用File的子类描述数据，如[Image](#image)、[Video](#video)、[Folder](#folder)等具体子类。 598 599**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 600 601**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 602 603| 名称 | 类型 | 只读 | 可选 | 说明 | 604| -------- | -------- | -------- | -------- | -------- | 605| details | Record<string, string> | 否 | 是 | 是一个字典类型对象，key和value都是string类型，用于描述文件相关信息。例如，可生成一个details内容为<br />{<br />"name":"文件名",<br />"type":"文件类型"<br />}<br />的数据对象，用于描述一个文件。非必填字段，默认值为空字典对象。 | 606| uri | string | 否 | 否 | 文件数据uri。 | 607 608**示例：** 609 610```ts 611let file = new unifiedDataChannel.File(); 612file.details = { 613 name: 'test', 614 type: 'txt', 615}; 616file.uri = 'schema://com.samples.test/files/test.txt'; 617``` 618 619## Image 620 621图片类型数据，是[File](#file)的子类，用于描述图片文件。 622 623**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 624 625**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 626 627| 名称 | 类型 | 只读 | 可选 | 说明 | 628| -------- | -------- | -------- | -------- | -------- | 629| imageUri | string | 否 | 否 | 图片数据uri。 | 630 631**示例：** 632 633```ts 634let image = new unifiedDataChannel.Image(); 635image.imageUri = 'schema://com.samples.test/files/test.jpg'; 636``` 637 638## Video 639 640视频类型数据，是[File](#file)的子类，用于描述视频文件。 641 642**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 643 644**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 645 646| 名称 | 类型 | 只读 | 可选 | 说明 | 647| -------- | -------- | -------- | -------- | -------- | 648| videoUri | string | 否 | 否 | 视频数据uri。 | 649 650**示例：** 651 652```ts 653let video = new unifiedDataChannel.Video(); 654video.videoUri = 'schema://com.samples.test/files/test.mp4'; 655``` 656 657## Audio 658 659音频类型数据，是[File](#file)的子类，用于描述音频文件。 660 661**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 662 663**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 664 665| 名称 | 类型 | 只读 | 可选 | 说明 | 666| -------- | -------- | -------- | -------- | -------- | 667| audioUri | string | 否 | 否 | 音频数据uri。 | 668 669**示例：** 670 671```ts 672let audio = new unifiedDataChannel.Audio(); 673audio.audioUri = 'schema://com.samples.test/files/test.mp3'; 674``` 675 676## Folder 677 678文件夹类型数据，是[File](#file)的子类，用于描述文件夹。 679 680**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 681 682**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 683 684| 名称 | 类型 | 只读 | 可选 | 说明 | 685| -------- | -------- | -------- | -------- | -------- | 686| folderUri | string | 否 | 否 | 文件夹uri。 | 687 688**示例：** 689 690```ts 691let folder = new unifiedDataChannel.Folder(); 692folder.folderUri = 'schema://com.samples.test/files/folder/'; 693``` 694 695## SystemDefinedRecord 696 697SystemDefinedRecord是[UnifiedRecord](#unifiedrecord)的子类，也是OpenHarmony系统特有数据类型的基类，用于描述仅在OpenHarmony系统范围内流通的特有数据类型，推荐开发者优先使用SystemDefinedRecord的子类描述数据，如[SystemDefinedForm](#systemdefinedform)、[SystemDefinedAppItem](#systemdefinedappitem)、[SystemDefinedPixelMap](#systemdefinedpixelmap)等具体子类。 698 699**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 700 701**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 702 703| 名称 | 类型 | 只读 | 可选 | 说明 | 704| -------- | -------- | -------- | -------- | -------- | 705| details | Record<string, number \| string \| Uint8Array> | 否 | 是 | 是一个字典类型对象，key是string类型，value可以写入number（数值类型）、string（字符串类型）、Uint8Array（二进制字节数组）类型数据。非必填字段，默认值为空字典对象。| 706 707**示例：** 708 709```ts 710let sdr = new unifiedDataChannel.SystemDefinedRecord(); 711let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 712sdr.details = { 713 title: 'recordTitle', 714 version: 1, 715 content: u8Array, 716}; 717let unifiedData = new unifiedDataChannel.UnifiedData(sdr); 718``` 719 720## SystemDefinedForm 721 722系统定义的桌面卡片类型数据，是[SystemDefinedRecord](#systemdefinedrecord)的子类。 723 724**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 725 726**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 727 728| 名称 | 类型 | 只读 | 可选 | 说明 | 729| -------- | -------- | -------- | -------- | -------- | 730| formId | number | 否 | 否 | 卡片id。 | 731| formName | string | 否 | 否 | 卡片名称。 | 732| bundleName | string | 否 | 否 | 卡片所属的bundle名。 | 733| abilityName | string | 否 | 否 | 卡片对应的ability名。 | 734| module | string | 否 | 否 | 卡片所属的module名。 | 735 736**示例：** 737 738```ts 739let form = new unifiedDataChannel.SystemDefinedForm(); 740form.formId = 123456; 741form.formName = 'MyFormName'; 742form.bundleName = 'MyBundleName'; 743form.abilityName = 'MyAbilityName'; 744form.module = 'MyModule'; 745let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 746form.details = { 747 formKey1: 123, 748 formKey2: 'formValue', 749 formKey3: u8Array, 750}; 751let unifiedData = new unifiedDataChannel.UnifiedData(form); 752``` 753 754## SystemDefinedAppItem 755 756系统定义的桌面图标类型数据，是[SystemDefinedRecord](#systemdefinedrecord)的子类。 757 758**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 759 760**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 761 762| 名称 | 类型 | 只读 | 可选 | 说明 | 763| -------- | -------- | -------- | -------- | -------- | 764| appId | string | 否 | 否 | 图标对应的应用id。 | 765| appName | string | 否 | 否 | 图标对应的应用名。 | 766| appIconId | string | 否 | 否 | 图标的图片id。 | 767| appLabelId | string | 否 | 否 | 图标名称对应的标签id。 | 768| bundleName | string | 否 | 否 | 图标对应的应用bundle名。 | 769| abilityName | string | 否 | 否 | 图标对应的应用ability名。 | 770 771**示例：** 772 773```ts 774let appItem = new unifiedDataChannel.SystemDefinedAppItem(); 775appItem.appId = 'MyAppId'; 776appItem.appName = 'MyAppName'; 777appItem.appIconId = 'MyAppIconId'; 778appItem.appLabelId = 'MyAppLabelId'; 779appItem.bundleName = 'MyBundleName'; 780appItem.abilityName = 'MyAbilityName'; 781let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 782appItem.details = { 783 appItemKey1: 123, 784 appItemKey2: 'appItemValue', 785 appItemKey3: u8Array, 786}; 787let unifiedData = new unifiedDataChannel.UnifiedData(appItem); 788``` 789 790## SystemDefinedPixelMap 791 792与系统侧定义的[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)数据类型对应的图片数据类型，是[SystemDefinedRecord](#systemdefinedrecord)的子类，仅保存PixelMap的二进制数据。 793 794**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 795 796**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 797 798| 名称 | 类型 | 只读 | 可选 | 说明 | 799| -------- | -------- | -------- | -------- | -------- | 800| rawData | Uint8Array | 否 | 否 | PixelMap对象的二进制数据。 | 801 802**示例：** 803 804```ts 805import { image } from '@kit.ImageKit'; // PixelMap类定义所在模块 806import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData'; 807import { BusinessError } from '@kit.BasicServicesKit'; 808 809const color = new ArrayBuffer(96); // 创建pixelmap对象 810let opts: image.InitializationOptions = { 811 editable: true, pixelFormat: 3, size: { 812 height: 4, width: 6 813 } 814} 815image.createPixelMap(color, opts, (error, pixelmap) => { 816 if (error) { 817 console.error('Failed to create pixelmap.'); 818 } else { 819 console.info('Succeeded in creating pixelmap.'); 820 let arrayBuf = new ArrayBuffer(pixelmap.getPixelBytesNumber()); 821 pixelmap.readPixelsToBuffer(arrayBuf); 822 let u8Array = new Uint8Array(arrayBuf); 823 let sdpixel = new unifiedDataChannel.SystemDefinedPixelMap(); 824 sdpixel.rawData = u8Array; 825 let unifiedData = new unifiedDataChannel.UnifiedData(sdpixel); 826 827 // 从unifiedData中读取pixelMap类型的record 828 let records = unifiedData.getRecords(); 829 for (let i = 0; i < records.length; i++) { 830 if (records[i].getType() === uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP) { 831 let pixelmapRecord = records[i] as unifiedDataChannel.SystemDefinedPixelMap; 832 let newArraybuf = pixelmapRecord.rawData.buffer; 833 pixelmap.writeBufferToPixels(newArraybuf).then(() => { 834 console.info('Succeeded in writing data from buffer to a pixelMap'); 835 }).catch((error: BusinessError) => { 836 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 837 }) 838 } 839 } 840 } 841}) 842``` 843 844## ApplicationDefinedRecord 845 846ApplicationDefinedRecord是[UnifiedRecord](#unifiedrecord)的子类，也是应用自定义数据类型的基类，用于描述仅在应用生态内部流通的自定义数据类型，应用可基于此类进行自定义数据类型的扩展。 847 848**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 849 850**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 851 852| 名称 | 类型 | 只读 | 可选 | 说明 | 853| -------- | -------- | -------- | -------- | -------- | 854| applicationDefinedType | string | 否 | 否 | 应用自定义类型标识符，必须以'ApplicationDefined'开头。 | 855| rawData | Uint8Array | 否 | 否 | 应用自定义数据类型的二进制数据。 | 856 857**示例：** 858 859```ts 860let record = new unifiedDataChannel.ApplicationDefinedRecord(); 861let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 862record.applicationDefinedType = 'ApplicationDefinedType'; 863record.rawData = u8Array; 864let unifiedData = new unifiedDataChannel.UnifiedData(record); 865``` 866 867## Intention 868 869UDMF已经支持的数据通路枚举类型。其主要用途是标识各种UDMF数据通路所面向的不同业务场景。 870 871**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 872 873| 名称 | 值 | 说明 | 874|----------|-----------|---------| 875| DATA_HUB | 'DataHub' | 公共数据通路。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 876| DRAG<sup>14+</sup> | 'Drag' | 拖拽类型数据通道。<br/>**模型约束：** 此接口仅可在Stage模型下使用。 | 877 878## Options 879 880type Options = { intention?: Intention; key?: string; } 881 882UDMF提供的数据操作接口可选项，包含intention和key两个可选参数。无默认值，当对应接口不需要此参数时可不填，具体要求参照方法接口的参数说明。 883 884**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 885 886**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 887 888 889| 名称 | 类型 | 必填 | 说明 | 890| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 891| intention | [Intention](#intention) | 否 | 表示数据操作相关的数据通路类型。 | 892| key | string | 否 | UDMF中数据对象的唯一标识符，可通过[insertData](#unifieddatachannelinsertdata)接口的返回值获取。<br>由udmf:/、intention、bundleName和groupId四部分组成，以'/'连接，比如：udmf://DataHub/com.ohos.test/0123456789。<br>其中udmf:/固定，DataHub为对应枚举的取值，com.ohos.test为包名，0123456789为随机生成的groupId。 | 893 894 895 896## unifiedDataChannel.insertData 897 898insertData(options: Options, data: UnifiedData, callback: AsyncCallback<string>): void 899 900将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用callback异步回调。 901 902**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 903 904**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 905 906**参数：** 907 908| 参数名 | 类型 | 必填 | 说明 | 909|----------|----------------------------|----|------------------------------| 910| options | [Options](#options) | 是 | 配置项参数，仅需要intention的值。 | 911| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 912| callback | AsyncCallback<string> | 是 | 回调函数，返回写入UDMF的数据的唯一标识符key的值。 | 913 914**错误码：** 915 916以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 917 918| **错误码ID** | **错误信息** | 919| ------------ | ------------------------------------------- | 920| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 921 922**示例：** 923 924```ts 925import { unifiedDataChannel } from '@kit.ArkData'; 926import { BusinessError } from '@kit.BasicServicesKit'; 927 928let plainText = new unifiedDataChannel.PlainText(); 929plainText.textContent = 'hello world!'; 930let unifiedData = new unifiedDataChannel.UnifiedData(plainText); 931 932let options: unifiedDataChannel.Options = { 933 intention: unifiedDataChannel.Intention.DATA_HUB 934} 935try { 936 unifiedDataChannel.insertData(options, unifiedData, (err, data) => { 937 if (err === undefined) { 938 console.info(`Succeeded in inserting data. key = ${data}`); 939 } else { 940 console.error(`Failed to insert data. code is ${err.code},message is ${err.message} `); 941 } 942 }); 943 } catch (e) { 944 let error: BusinessError = e as BusinessError; 945 console.error(`Insert data throws an exception. code is ${error.code},message is ${error.message} `); 946} 947 948``` 949 950## unifiedDataChannel.insertData 951 952insertData(options: Options, data: UnifiedData): Promise<string> 953 954将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用Promise异步回调。 955 956**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 957 958**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 959 960**参数：** 961 962| 参数名 | 类型 | 必填 | 说明 | 963|---------|-----------------------------|----|-----------------------| 964| options | [Options](#options) | 是 | 配置项参数，仅需要intention的值。 | 965| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 966 967**返回值：** 968 969| 类型 | 说明 | 970|-----------------------|-----------------------------------| 971| Promise<string> | Promise对象，返回写入UDMF的数据的唯一标识符key的值。 | 972 973**错误码：** 974 975以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 976 977| **错误码ID** | **错误信息** | 978| ------------ | ------------------------------------------- | 979| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 980 981**示例：** 982 983```ts 984import { unifiedDataChannel } from '@kit.ArkData'; 985import { BusinessError } from '@kit.BasicServicesKit'; 986 987let plainText = new unifiedDataChannel.PlainText(); 988plainText.textContent = 'hello world!'; 989let unifiedData = new unifiedDataChannel.UnifiedData(plainText); 990 991let options: unifiedDataChannel.Options = { 992 intention: unifiedDataChannel.Intention.DATA_HUB 993} 994try { 995 unifiedDataChannel.insertData(options, unifiedData).then((data) => { 996 console.info(`Succeeded in inserting data. key = ${data}`); 997 }).catch((err: BusinessError) => { 998 console.error(`Failed to insert data. code is ${err.code},message is ${err.message} `); 999 }); 1000} catch (e) { 1001 let error: BusinessError = e as BusinessError; 1002 console.error(`Insert data throws an exception. code is ${error.code},message is ${error.message} `); 1003} 1004``` 1005 1006## unifiedDataChannel.updateData 1007 1008updateData(options: Options, data: UnifiedData, callback: AsyncCallback<void>): void 1009 1010更新已写入UDMF的公共数据通路的数据，使用callback异步回调。 1011 1012**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1013 1014**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1015 1016**参数：** 1017 1018| 参数名 | 类型 | 必填 | 说明 | 1019|----------|-----------------------------|----|-------------------------------------| 1020| options | [Options](#options) | 是 | 配置项参数，仅需要key的值。 | 1021| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1022| callback | AsyncCallback<void> | 是 | 回调函数。当更新数据成功，err为undefined，否则为错误对象。 | 1023 1024**错误码：** 1025 1026以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1027 1028| **错误码ID** | **错误信息** | 1029| ------------ | ------------------------------------------- | 1030| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1031 1032**示例：** 1033 1034```ts 1035import { unifiedDataChannel } from '@kit.ArkData'; 1036import { BusinessError } from '@kit.BasicServicesKit'; 1037 1038let plainText = new unifiedDataChannel.PlainText(); 1039plainText.textContent = 'hello world!'; 1040let unifiedData = new unifiedDataChannel.UnifiedData(plainText); 1041 1042let options: unifiedDataChannel.Options = { 1043 key: 'udmf://DataHub/com.ohos.test/0123456789' 1044}; 1045 1046try { 1047 unifiedDataChannel.updateData(options, unifiedData, (err) => { 1048 if (err === undefined) { 1049 console.info('Succeeded in updating data.'); 1050 } else { 1051 console.error(`Failed to update data. code is ${err.code},message is ${err.message} `); 1052 } 1053 }); 1054} catch (e) { 1055 let error: BusinessError = e as BusinessError; 1056 console.error(`Update data throws an exception. code is ${error.code},message is ${error.message} `); 1057} 1058``` 1059 1060## unifiedDataChannel.updateData 1061 1062updateData(options: Options, data: UnifiedData): Promise<void> 1063 1064更新已写入UDMF的公共数据通路的数据，使用Promise异步回调。 1065 1066**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1067 1068**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1069 1070**参数：** 1071 1072| 参数名 | 类型 | 必填 | 说明 | 1073|---------|-----------------------------|----|-----------------| 1074| options | [Options](#options) | 是 | 配置项参数，仅需要key的值。 | 1075| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1076 1077**返回值：** 1078 1079| 类型 | 说明 | 1080|---------------------|----------------------------| 1081| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1082 1083**错误码：** 1084 1085以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1086 1087| **错误码ID** | **错误信息** | 1088| ------------ | ------------------------------------------- | 1089| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1090 1091**示例：** 1092 1093```ts 1094import { unifiedDataChannel } from '@kit.ArkData'; 1095import { BusinessError } from '@kit.BasicServicesKit'; 1096 1097let plainText = new unifiedDataChannel.PlainText(); 1098plainText.textContent = 'hello world!'; 1099let unifiedData = new unifiedDataChannel.UnifiedData(plainText); 1100 1101let options: unifiedDataChannel.Options = { 1102 key: 'udmf://DataHub/com.ohos.test/0123456789' 1103}; 1104 1105try { 1106 unifiedDataChannel.updateData(options, unifiedData).then(() => { 1107 console.info('Succeeded in updating data.'); 1108 }).catch((err: BusinessError) => { 1109 console.error(`Failed to update data. code is ${err.code},message is ${err.message} `); 1110 }); 1111} catch (e) { 1112 let error: BusinessError = e as BusinessError; 1113 console.error(`Update data throws an exception. code is ${error.code},message is ${error.message} `); 1114} 1115``` 1116 1117## unifiedDataChannel.queryData 1118 1119queryData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void 1120 1121查询UDMF公共数据通路的数据，使用callback异步回调。 1122 1123**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1124 1125**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1126 1127**参数：** 1128 1129| 参数名 | 类型 | 必填 | 说明 | 1130|----------|---------------------------------------------------------------|----|------------------------------------------------------------------------------------------------------------------------------------------------------------------| 1131| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1132| callback | AsyncCallback<Array<[UnifiedData](#unifieddata)>> | 是 | 回调函数，返回查询到的所有数据。<br>如果options中填入的是key，则返回key对应的数据。<br>如果options中填入的是intention，则返回intention下所有数据。<br>如intention和key均填写了，取两者查询数据的交集，与options只填入key的获取结果一致；如没有交集报错。 | 1133 1134**错误码：** 1135 1136以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1137 1138| **错误码ID** | **错误信息** | 1139| ------------ | ------------------------------------------- | 1140| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1141 1142**示例：** 1143 1144```ts 1145import { unifiedDataChannel } from '@kit.ArkData'; 1146import { uniformTypeDescriptor } from '@kit.ArkData'; 1147import { BusinessError } from '@kit.BasicServicesKit'; 1148 1149let options: unifiedDataChannel.Options = { 1150 intention: unifiedDataChannel.Intention.DATA_HUB 1151}; 1152 1153try { 1154 unifiedDataChannel.queryData(options, (err, data) => { 1155 if (err === undefined) { 1156 console.info(`Succeeded in querying data. size = ${data.length}`); 1157 for (let i = 0; i < data.length; i++) { 1158 let records = data[i].getRecords(); 1159 for (let j = 0; j < records.length; j++) { 1160 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 1161 let text = records[j] as unifiedDataChannel.PlainText; 1162 console.info(`${i + 1}.${text.textContent}`); 1163 } 1164 } 1165 } 1166 } else { 1167 console.error(`Failed to query data. code is ${err.code},message is ${err.message} `); 1168 } 1169 }); 1170} catch (e) { 1171 let error: BusinessError = e as BusinessError; 1172 console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `); 1173} 1174``` 1175 1176## unifiedDataChannel.queryData 1177 1178queryData(options: Options): Promise<Array<UnifiedData>> 1179 1180查询UDMF公共数据通路的数据，使用Promise异步回调。 1181 1182**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1183 1184**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1185 1186**参数：** 1187 1188| 参数名 | 类型 | 必填 | 说明 | 1189|---------|---------------------|----|-----------------------------------------------| 1190| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1191 1192**返回值：** 1193 1194| 类型 | 说明 | 1195|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| 1196| Promise<Array<[UnifiedData](#unifieddata)>> | Promise对象，返回查询到的所有数据。<br>如果options中填入的是key，则返回key对应的数据。<br>如果options中填入的是intention，则返回intention下所有数据。<br>如intention和key均填写了，取两者查询数据的交集，与options只填入key的获取结果一致；如没有交集报错。 | 1197 1198**错误码：** 1199 1200以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1201 1202| **错误码ID** | **错误信息** | 1203| ------------ | ------------------------------------------- | 1204| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1205 1206**示例：** 1207 1208```ts 1209import { unifiedDataChannel } from '@kit.ArkData'; 1210import { uniformTypeDescriptor } from '@kit.ArkData'; 1211import { BusinessError } from '@kit.BasicServicesKit'; 1212 1213let options: unifiedDataChannel.Options = { 1214 key: 'udmf://DataHub/com.ohos.test/0123456789' 1215}; 1216 1217try { 1218 unifiedDataChannel.queryData(options).then((data) => { 1219 console.info(`Succeeded in querying data. size = ${data.length}`); 1220 for (let i = 0; i < data.length; i++) { 1221 let records = data[i].getRecords(); 1222 for (let j = 0; j < records.length; j++) { 1223 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 1224 let text = records[j] as unifiedDataChannel.PlainText; 1225 console.info(`${i + 1}.${text.textContent}`); 1226 } 1227 } 1228 } 1229 }).catch((err: BusinessError) => { 1230 console.error(`Failed to query data. code is ${err.code},message is ${err.message} `); 1231 }); 1232} catch (e) { 1233 let error: BusinessError = e as BusinessError; 1234 console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `); 1235} 1236``` 1237 1238## unifiedDataChannel.deleteData 1239 1240deleteData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void 1241 1242删除UDMF公共数据通路的数据，返回删除的数据集，使用callback异步回调。 1243 1244**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1245 1246**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1247 1248**参数：** 1249 1250| 参数名 | 类型 | 必填 | 说明 | 1251|----------|---------------------------------------------------------------|----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 1252| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1253| callback | AsyncCallback<Array<[UnifiedData](#unifieddata)>> | 是 | 回调函数，返回删除的所有数据。<br>如果options中填入的是key，则删除key对应的数据并返回该数据。<br>如果options中填入的是intention，则删除intention下所有数据并返回删除的数据。<br>如intention和key均填写了，取两者数据的交集进行删除，并返回删除的数据，与options只填入key的结果一致；如没有交集报错。 | 1254 1255**错误码：** 1256 1257以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1258 1259| **错误码ID** | **错误信息** | 1260| ------------ | ------------------------------------------- | 1261| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1262 1263**示例：** 1264 1265```ts 1266import { unifiedDataChannel } from '@kit.ArkData'; 1267import { uniformTypeDescriptor } from '@kit.ArkData'; 1268import { BusinessError } from '@kit.BasicServicesKit'; 1269 1270let options: unifiedDataChannel.Options = { 1271 intention: unifiedDataChannel.Intention.DATA_HUB 1272}; 1273 1274try { 1275 unifiedDataChannel.deleteData(options, (err, data) => { 1276 if (err === undefined) { 1277 console.info(`Succeeded in deleting data. size = ${data.length}`); 1278 for (let i = 0; i < data.length; i++) { 1279 let records = data[i].getRecords(); 1280 for (let j = 0; j < records.length; j++) { 1281 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 1282 let text = records[j] as unifiedDataChannel.PlainText; 1283 console.info(`${i + 1}.${text.textContent}`); 1284 } 1285 } 1286 } 1287 } else { 1288 console.error(`Failed to delete data. code is ${err.code},message is ${err.message} `); 1289 } 1290 }); 1291} catch (e) { 1292 let error: BusinessError = e as BusinessError; 1293 console.error(`Delete data throws an exception. code is ${error.code},message is ${error.message} `); 1294} 1295``` 1296 1297## unifiedDataChannel.deleteData 1298 1299deleteData(options: Options): Promise<Array<UnifiedData>> 1300 1301删除UDMF公共数据通路的数据，返回删除的数据集，使用Promise异步回调。 1302 1303**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1304 1305**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1306 1307**参数：** 1308 1309| 参数名 | 类型 | 必填 | 说明 | 1310|---------|---------------------|----|--------| 1311| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1312 1313**返回值：** 1314 1315| 类型 | 说明 | 1316|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| 1317| Promise<Array<[UnifiedData](#unifieddata)>> | Promise对象，返回删除的所有数据。<br>如果options中填入的是key，则删除key对应的数据并返回该数据。<br>如果options中填入的是intention，则删除intention下所有数据并返回删除的数据。<br>如intention和key均填写了，取两者数据的交集进行删除，并返回删除的数据，与options只填入key的结果一致；如没有交集报错。 | 1318 1319**错误码：** 1320 1321以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1322 1323| **错误码ID** | **错误信息** | 1324| ------------ | ------------------------------------------- | 1325| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1326 1327**示例：** 1328 1329```ts 1330import { unifiedDataChannel } from '@kit.ArkData'; 1331import { uniformTypeDescriptor } from '@kit.ArkData'; 1332import { BusinessError } from '@kit.BasicServicesKit'; 1333 1334let options: unifiedDataChannel.Options = { 1335 key: 'udmf://DataHub/com.ohos.test/0123456789' 1336}; 1337 1338try { 1339 unifiedDataChannel.deleteData(options).then((data) => { 1340 console.info(`Succeeded in deleting data. size = ${data.length}`); 1341 for (let i = 0; i < data.length; i++) { 1342 let records = data[i].getRecords(); 1343 for (let j = 0; j < records.length; j++) { 1344 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 1345 let text = records[j] as unifiedDataChannel.PlainText; 1346 console.info(`${i + 1}.${text.textContent}`); 1347 } 1348 } 1349 } 1350 }).catch((err: BusinessError) => { 1351 console.error(`Failed to delete data. code is ${err.code},message is ${err.message} `); 1352 }); 1353} catch (e) { 1354 let error: BusinessError = e as BusinessError; 1355 console.error(`Query data throws an exception. code is ${error.code},message is ${error.message} `); 1356} 1357``` 1358 1359## unifiedDataChannel.setAppShareOptions<sup>14+</sup> 1360 1361setAppShareOptions(intention: Intention, shareOptions: ShareOptions): void 1362 1363设置应用内拖拽通道数据可使用的范围[ShareOptions](#shareoptions12)，目前仅支持DRAG类型数据通道的管控设置。 1364 1365**需要权限:** ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION 1366 1367**模型约束：** 此接口仅可在Stage模型下使用。 1368 1369**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1370 1371**参数：** 1372 1373| 参数名 | 类型 | 必填 | 说明 | 1374|----------|----------------------------|----|------------------------------| 1375| intention | [Intention](#intention) | 是 | 表示数据操作相关的数据通路类型，目前仅支持DRAG类型数据通道。 | 1376| shareOptions | [ShareOptions](#shareoptions12) | 是 | 指示[UnifiedData](#unifieddata)支持的设备内使用范围。 | 1377 1378**错误码：** 1379 1380以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[统一数据管理框架错误码](errorcode-udmf.md)。 1381 1382| **错误码ID** | **错误信息** | 1383| ------------ | ------------------------------------------------------------ | 1384| 201 | Permission denied. Interface caller does not have permission "ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION". | 1385| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1386| 20400001 | Settings already exist. | 1387 1388**示例：** 1389 1390```ts 1391import { BusinessError } from '@kit.BasicServicesKit'; 1392try { 1393 unifiedDataChannel.setAppShareOptions(unifiedDataChannel.Intention.DRAG, unifiedDataChannel.ShareOptions.IN_APP); 1394 console.info(`[UDMF]setAppShareOptions success. `); 1395}catch (e){ 1396 let error: BusinessError = e as BusinessError; 1397 console.error(`[UDMF]setAppShareOptions throws an exception. code is ${error.code},message is ${error.message} `); 1398} 1399``` 1400 1401## unifiedDataChannel.removeAppShareOptions<sup>14+</sup> 1402 1403removeAppShareOptions(intention: Intention): void 1404 1405清除[setAppShareOptions](#unifieddatachannelsetappshareoptions14)设置的管控信息。 1406 1407**需要权限:** ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION 1408 1409**模型约束：** 此接口仅可在Stage模型下使用。 1410 1411**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1412 1413**参数：** 1414 1415| 参数名 | 类型 | 必填 | 说明 | 1416| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 1417| intention | [Intention](#intention) | 是 | 表示数据操作相关的数据通路类型，目前仅支持DRAG类型数据通道。 | 1418 1419**错误码：** 1420 1421以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1422 1423| **错误码ID** | **错误信息** | 1424| ------------ | ------------------------------------------------------------ | 1425| 201 | Permission denied. Interface caller does not have permission "ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION". | 1426| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1427 1428**示例：** 1429 1430```ts 1431import { BusinessError } from '@kit.BasicServicesKit'; 1432try { 1433 unifiedDataChannel.removeAppShareOptions(unifiedDataChannel.Intention.DRAG); 1434 console.info(`[UDMF]removeAppShareOptions success. `); 1435}catch (e){ 1436 let error: BusinessError = e as BusinessError; 1437 console.error(`[UDMF]removeAppShareOptions throws an exception. code is ${error.code},message is ${error.message} `); 1438} 1439``` 1440
