1# @ohos.data.unifiedDataChannel (标准化数据通路) 2 3本模块为统一数据管理框架（Unified Data Management Framework，UDMF）的组成部分，针对多对多跨应用数据共享的不同业务场景提供了标准化的数据通路，提供了标准化的数据接入与读取接口。同时对文本、图片等数据类型提供了标准化定义，方便不同应用间进行数据交互，减少数据类型适配的工作量。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 { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 54 55let getDelayData: unifiedDataChannel.GetDelayData = ((type: string) => { 56 if (type == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 57 let plainTextDetails : Record<string, string> = { 58 'attr1': 'value1', 59 'attr2': 'value2', 60 } 61 let plainText : uniformDataStruct.PlainText = { 62 uniformDataType: 'general.plain-text', 63 textContent : 'This is a plain text example', 64 abstract : 'This is abstract', 65 details : plainTextDetails, 66 } 67 let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 68 let textData = new unifiedDataChannel.UnifiedData(text); 69 return textData; 70 } 71 return new unifiedDataChannel.UnifiedData(); 72}); 73``` 74 75## ValueType<sup>12+</sup> 76 77type ValueType = number | string | boolean | image.PixelMap | Want | ArrayBuffer | object | null | undefined 78 79用于表示统一数据记录允许的数据字段类型。 80 81**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 82 83**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 84 85| 类型 | 说明 | 86| -------- | -------- | 87| number | 表示number的类型。 | 88| string | 表示string的类型。 | 89| boolean | 表示boolean的类型。 | 90| image.PixelMap | 表示[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)的类型。 | 91| Want | 表示[Want](../apis-ability-kit/js-apis-app-ability-want.md)的类型。 | 92| ArrayBuffer | 表示ArrayBuffer的类型。 | 93| object | 表示object的类型。 | 94| null | 表示null。 | 95| undefined | 表示undefined。 | 96 97## UnifiedDataProperties<sup>12+</sup> 98 99定义统一数据对象中所有数据记录的属性，包含时间戳、标签、粘贴范围以及一些附加数据等。 100 101**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 102 103**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 104 105| 名称 | 类型 | 只读 | 可选 | 说明 | 106| -------- | -------- | -------- | -------- | -------- | 107| extras<sup>12+</sup> | Record<string, object> | 否 | 是 | 是一个字典类型对象，用于设置其他附加属性数据。非必填字段，默认值为空字典对象。 | 108| tag<sup>12+</sup> | string | 否 | 是 | 用户自定义标签。非必填字段，默认值为空字符串。 | 109| timestamp<sup>12+</sup> | Date | 是 | 是 | [UnifiedData](#unifieddata)的生成时间戳。默认值为1970年1月1日（UTC）。 | 110| shareOptions<sup>12+</sup> | [ShareOptions](#shareoptions12) | 否 | 是 | 指示[UnifiedData](#unifieddata)支持的设备内使用范围，非必填字段，默认值为CROSS_APP。 | 111| getDelayData<sup>12+</sup> | [GetDelayData](#getdelaydata12) | 否 | 是 | 延迟获取数据回调。当前只支持同设备剪贴板场景，后续场景待开发。非必填字段，默认值为undefined。 | 112 113**示例：** 114 115```ts 116import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 117 118let properties = new unifiedDataChannel.UnifiedDataProperties(); 119properties.extras = { 120 key: { 121 title: 'MyTitle', 122 content: 'MyContent' 123 } 124}; 125properties.tag = "This is a tag of properties"; 126properties.shareOptions = unifiedDataChannel.ShareOptions.CROSS_APP; 127properties.getDelayData = ((type: string) => { 128 if (type == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 129 let plainTextDetails : Record<string, string> = { 130 'attr1': 'value1', 131 'attr2': 'value2', 132 } 133 let plainText : uniformDataStruct.PlainText = { 134 uniformDataType: 'general.plain-text', 135 textContent : 'This is a plain text example', 136 abstract : 'This is abstract', 137 details : plainTextDetails, 138 } 139 let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 140 let textData = new unifiedDataChannel.UnifiedData(text); 141 return textData; 142 } 143 return new unifiedDataChannel.UnifiedData(); 144}); 145``` 146 147## UnifiedData 148 149表示UDMF统一数据对象，提供封装一组数据记录的方法。 150 151**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 152 153### 属性 154 155| 名称 | 类型 | 只读 | 可选 | 说明 | 156| -------- | -------- | -------- | -------- |-------------------------------------------------------------------------------------------------| 157| properties<sup>12+</sup> | [UnifiedDataProperties](#unifieddataproperties12) | 否 | 否 | 当前统一数据对象中所有数据记录的属性，包含时间戳、标签、粘贴范围以及一些附加数据等。<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 158 159### constructor<sup>12+</sup> 160 161constructor() 162 163用于创建统一数据对象。 164 165**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 166 167**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 168 169**示例：** 170 171```ts 172let unifiedData = new unifiedDataChannel.UnifiedData(); 173``` 174 175### constructor 176 177constructor(record: UnifiedRecord) 178 179用于创建带有一条数据记录的统一数据对象。 180 181**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 182 183**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 184 185**参数：** 186 187| 参数名 | 类型 | 必填 | 说明 | 188| ------ | ------------------------------- | ---- |-----------------------------------------| 189| record | [UnifiedRecord](#unifiedrecord) | 是 | 要添加到统一数据对象中的数据记录，该记录为UnifiedRecord或其子类对象。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 194 195| **错误码ID** | **错误信息** | 196| ------------ | ------------------------------------------- | 197| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 198 199**示例：** 200 201```ts 202import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 203let plainText : uniformDataStruct.PlainText = { 204 uniformDataType: 'general.plain-text', 205 textContent : 'This is a plain text example', 206 abstract : 'This is abstract', 207} 208let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 209let unifiedData = new unifiedDataChannel.UnifiedData(text); 210``` 211 212### addRecord 213 214addRecord(record: UnifiedRecord): void 215 216在当前统一数据对象中添加一条数据记录。 217 218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 219 220**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| ------ | ------------------------------- | ---- |---------------------------------------------| 226| record | [UnifiedRecord](#unifiedrecord) | 是 | 要添加到统一数据对象中的数据记录，该记录为UnifiedRecord子类对象。| 227 228**错误码：** 229 230以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 231 232| **错误码ID** | **错误信息** | 233| ------------ | ------------------------------------------- | 234| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 235 236**示例：** 237 238```ts 239import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 240let plainText : uniformDataStruct.PlainText = { 241 uniformDataType: 'general.plain-text', 242 textContent : 'This is a plain text example', 243 abstract : 'This is abstract', 244} 245let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 246let unifiedData = new unifiedDataChannel.UnifiedData(text); 247 248let hyperlink : uniformDataStruct.Hyperlink = { 249 uniformDataType:'general.hyperlink', 250 url : 'www.XXX.com', 251 description : 'This is the description of the hyperlink', 252} 253let link = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 254unifiedData.addRecord(link); 255``` 256 257### getRecords 258 259getRecords(): Array\<UnifiedRecord\> 260 261将当前统一数据对象中的所有数据记录取出。通过本接口取出的数据为UnifiedRecord类型，需通过[getType](#gettype)获取数据类型后转为子类再使用。 262 263**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 264 265**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 266 267**返回值：** 268 269| 类型 | 说明 | 270| ---------------------------------------- |-------------------------| 271| Array\<[UnifiedRecord](#unifiedrecord)\> | 当前统一数据对象内所添加的记录。 | 272 273**示例：** 274 275```ts 276import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 277 278let plainText : uniformDataStruct.PlainText = { 279 uniformDataType: 'general.plain-text', 280 textContent : 'This is a plain text example', 281 abstract : 'This is abstract', 282} 283let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 284let unifiedData = new unifiedDataChannel.UnifiedData(text); 285 286let hyperlink : uniformDataStruct.Hyperlink = { 287 uniformDataType:'general.hyperlink', 288 url : 'www.XXX.com', 289 description : 'This is the description of the hyperlink', 290} 291let link = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 292unifiedData.addRecord(link); 293 294let records = unifiedData.getRecords(); 295for (let i = 0; i < records.length; i++) { 296 let record = records[i]; 297 let types = record.getTypes(); 298 if (types.includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)) { 299 let plainText = record.getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as unifiedDataChannel.PlainText; 300 console.info(`textContent: ${plainText.textContent}`); 301 } else if (types.includes(uniformTypeDescriptor.UniformDataType.HYPERLINK)) { 302 let hyperlink = record.getEntry(uniformTypeDescriptor.UniformDataType.HYPERLINK) as unifiedDataChannel.Hyperlink; 303 console.info(`linkUrl: ${hyperlink.url}`); 304 } 305} 306``` 307 308### hasType<sup>12+</sup> 309 310hasType(type: string): boolean 311 312检查当前统一数据对象中是否有指定的数据类型，检查范围包括使用[addEntry](#addentry15)函数添加的数据类型。 313 314针对文件类型，若UnifiedData的类型集合中包含"general.jpeg"，在调用hasType接口判断是否包括"general.image"类型时，结果返回true（类型"general.jpeg"归属于类型"general.image"）。 315 316**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 317 318**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 319 320| 参数名 | 类型 | 必填 | 说明 | 321| ------ | ------------------------------- | ---- |---------------------------------------------| 322| type | string | 是 | 要查询的数据类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。| 323 324**返回值：** 325 326| 类型 | 说明 | 327| ---------------------------------------- |-------------------------| 328| boolean | 有指定的数据类型返回true，否则返回false。 | 329 330**错误码：** 331 332以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 333 334| **错误码ID** | **错误信息** | 335| ------------ | ------------------------------------------- | 336| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 337 338**示例：** 339 340```ts 341import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 342 343let plainText : uniformDataStruct.PlainText = { 344 uniformDataType: 'general.plain-text', 345 textContent : 'This is a plain text example', 346 abstract : 'This is abstract', 347} 348let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 349let unifiedData = new unifiedDataChannel.UnifiedData(text); 350 351let hyperlink : uniformDataStruct.Hyperlink = { 352 uniformDataType:'general.hyperlink', 353 url : 'www.XXX.com', 354 description : 'This is the description of the hyperlink', 355} 356let link = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 357unifiedData.addRecord(link); 358 359let hasPlainText = unifiedData.hasType(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT); 360let hasLink = unifiedData.hasType(uniformTypeDescriptor.UniformDataType.HYPERLINK); 361``` 362 363### getTypes<sup>12+</sup> 364 365getTypes(): Array\<string\> 366 367获取当前统一数据对象所有数据记录的类型。 368 369**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 370 371**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 372 373**返回值：** 374 375| 类型 | 说明 | 376| ---------------------------------------- |-------------------------| 377| Array\<string\> | [UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)类型的数组，表示当前统一数据对象所有数据记录对应的数据类型。 | 378 379**示例：** 380 381```ts 382import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 383 384let plainText : uniformDataStruct.PlainText = { 385 uniformDataType: 'general.plain-text', 386 textContent : 'This is a plain text example', 387 abstract : 'This is abstract', 388} 389let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 390let unifiedData = new unifiedDataChannel.UnifiedData(text); 391 392let hyperlink : uniformDataStruct.Hyperlink = { 393 uniformDataType:'general.hyperlink', 394 url : 'www.XXX.com', 395 description : 'This is the description of the hyperlink', 396} 397let link = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 398unifiedData.addRecord(link); 399 400let types = unifiedData.getTypes(); 401``` 402 403## Summary 404 405描述某一统一数据对象的数据摘要，包括所含数据类型及大小。 406 407**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 408 409**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 410 411| 名称 | 类型 | 只读 | 可选 | 说明 | 412| -------- | -------- | -------- | -------- | -------- | 413| summary | Record<string, number> | 否 | 否 | 是一个字典类型对象，key表示数据类型（见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)），value为统一数据对象中该类型记录大小总和（单位：Byte）。 | 414| totalSize | number | 否 | 否 | 统一数据对象内记录总大小（单位：Byte）。 | 415 416## UnifiedRecord 417 418对UDMF支持的数据内容的抽象定义，称为数据记录。一个统一数据对象内包含一条或多条数据记录，例如一条文本记录、一条图片记录、一条HTML记录等。从API version 15开始，支持往数据记录中增加同一内容的不同表现样式，数据使用方根据业务需要获取对应的样式。 419 420### constructor<sup>12+</sup> 421 422constructor() 423 424用于创建数据记录。 425 426**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 427 428**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 429 430**示例：** 431 432```ts 433let unifiedRecord = new unifiedDataChannel.UnifiedRecord(); 434``` 435 436### constructor<sup>12+</sup> 437 438constructor(type: string, value: ValueType) 439 440用于创建指定类型和值的数据记录。<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的值。 441 442**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 443 444**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 445 446**参数：** 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ------ | ------------------------------- | ---- |-----------------------------------------| 450| type | string | 是 | 要创建的数据记录的类型。 | 451| value | [ValueType](#valuetype12) | 是 | 要创建的数据记录的值。 | 452 453**错误码：** 454 455以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 456 457| **错误码ID** | **错误信息** | 458| ------------ | ------------------------------------------- | 459| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 460 461**示例：** 462 463```ts 464import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 465import { image } from '@kit.ImageKit'; 466 467let hyperlink : uniformDataStruct.Hyperlink = { 468 uniformDataType:'general.hyperlink', 469 url : 'www.XXX.com', 470 description : 'This is the description of the hyperlink', 471} 472let hyperlinkRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 473 474let plainText : uniformDataStruct.PlainText = { 475 uniformDataType: 'general.plain-text', 476 textContent : 'This is a plain text example', 477 abstract : 'This is abstract', 478} 479let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 480 481let arrayBuffer = new ArrayBuffer(4 * 200 * 200); 482let opt : image.InitializationOptions = { editable: true, pixelFormat: 3, size: { height: 200, width: 200 }, alphaType: 3 }; 483let pixelMap : uniformDataStruct.PixelMap = { 484 uniformDataType : 'openharmony.pixel-map', 485 pixelMap : image.createPixelMapSync(arrayBuffer, opt), 486} 487let pixelMapRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP, pixelMap); 488``` 489 490### getType 491 492getType(): string 493 494获取当前数据记录的类型。由于从统一数据对象中调用[getRecords](#getrecords)所取出的数据是UnifiedRecord对象，因此需要通过本接口查询此记录的具体类型，再将该UnifiedRecord对象转换为其子类，调用子类接口。 495 496**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 497 498**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 499 500**返回值：** 501 502| 类型 | 说明 | 503| ------ |------------------------------------------------------| 504| string | 当前数据记录对应的具体数据类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。| 505 506**示例：** 507 508```ts 509import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 510 511let plainText : uniformDataStruct.PlainText = { 512 uniformDataType: 'general.plain-text', 513 textContent : 'This is a plain text example', 514 abstract : 'This is abstract', 515} 516let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 517let unifiedData = new unifiedDataChannel.UnifiedData(text); 518 519let records = unifiedData.getRecords(); 520if (records[0].getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 521 let plainText = records[0] as unifiedDataChannel.PlainText; 522 console.info(`textContent: ${plainText.textContent}`); 523} 524``` 525 526### getValue<sup>12+</sup> 527 528getValue(): ValueType 529 530获取当前数据记录的值。 531 532**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 533 534**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 535 536**返回值：** 537 538| 类型 | 说明 | 539| ------ |------------------------------------------------------| 540| [ValueType](#valuetype12) | 当前数据记录对应的值。 | 541 542**示例：** 543 544```ts 545import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 546 547let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, 'this is value of text'); 548let value = text.getValue(); 549 550let hyperlinkDetails : Record<string, string> = { 551 'attr1': 'value1', 552 'attr2': 'value2', 553} 554let hyperlink : uniformDataStruct.Hyperlink = { 555 uniformDataType:'general.hyperlink', 556 url : 'www.XXX.com', 557 description : 'This is the description of the hyperlink', 558 details : hyperlinkDetails, 559} 560let hyperlinkRecord = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 561let hyperlinkValue = hyperlinkRecord.getValue(); 562``` 563 564### addEntry<sup>15+</sup> 565 566addEntry(type: string, value: ValueType): void 567 568在当前数据记录中添加一条指定数据类型和内容的数据，通过该方法增加的数据类型和内容为同一内容的不同表现样式. 569 570**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 571 572**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 573 574**参数：** 575 576| 参数名 | 类型 | 必填 | 说明 | 577| ------ | ------------------------------- | ---- |-----------------------------------------| 578| type | string | 是 | 要创建的数据类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。 | 579| value | [ValueType](#valuetype12) | 是 | 要创建的数据的值。 | 580 581**错误码：** 582 583以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 584 585| **错误码ID** | **错误信息** | 586| ------------ | ------------------------------------------- | 587| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 588 589**示例：** 590 591```ts 592import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 593 594let fileUriDetails : Record<string, string> = { 595 'attr1': 'value1', 596 'attr2': 'value2', 597} 598let fileUri : uniformDataStruct.FileUri = { 599 uniformDataType : 'general.file-uri', 600 oriUri : 'file://data/image/1.png', 601 fileType : 'general.image', 602 details : fileUriDetails, 603} 604let hyperlink : uniformDataStruct.Hyperlink = { 605 uniformDataType:'general.hyperlink', 606 url : 'file://data/image/1.png', 607 description : 'This is the description of the hyperlink', 608} 609 610let unifiedData = new unifiedDataChannel.UnifiedData(); 611let record = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HYPERLINK, hyperlink); 612record.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, fileUri); 613unifiedData.addRecord(record); 614``` 615 616### getEntry<sup>15+</sup> 617 618getEntry(type: string): ValueType 619 620通过数据类型获取当前数据记录中的数据内容。 621 622**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 623 624**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 625 626**参数：** 627 628| 参数名 | 类型 | 必填 | 说明 | 629| ------ | ------------------------------- | ---- |-----------------------------------------| 630| type | string | 是 | 要获取数据的类型，见[UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)。 | 631 632**返回值：** 633 634| 类型 | 说明 | 635| ------ |------------------------------------------------------| 636| [ValueType](#valuetype12) | 当前数据记录对应的值。 | 637 638**错误码：** 639 640以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 641 642| **错误码ID** | **错误信息** | 643| ------------ | ------------------------------------------- | 644| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 645 646**示例：** 647 648```ts 649import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 650 651let fileUriDetails : Record<string, string> = { 652 'attr1': 'value1', 653 'attr2': 'value2', 654} 655let fileUri : uniformDataStruct.FileUri = { 656 uniformDataType : 'general.file-uri', 657 oriUri : 'file://data/image/1.png', 658 fileType : 'general.image', 659 details : fileUriDetails, 660} 661let formDetails : Record<string, string> = { 662 'attr1': 'value1', 663 'attr2': 'value2', 664} 665let form : uniformDataStruct.Form = { 666 uniformDataType : 'openharmony.form', 667 formId : 1, 668 formName : 'form', 669 bundleName : 'com.xx.app', 670 abilityName : 'ability', 671 module : 'module', 672 details : formDetails, 673} 674 675let unifiedData = new unifiedDataChannel.UnifiedData(); 676let record = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM, form); 677record.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, fileUri); 678unifiedData.addRecord(record); 679 680let records = unifiedData.getRecords(); 681for (let i = 0; i < records.length; i++) { 682 let unifiedDataRecord = records[i] as unifiedDataChannel.UnifiedRecord; 683 let fileUriRead : uniformDataStruct.FileUri = unifiedDataRecord.getEntry(uniformTypeDescriptor.UniformDataType.FILE_URI) as uniformDataStruct.FileUri; 684 if (fileUriRead != undefined) { 685 console.info(`oriUri: ${fileUriRead.oriUri}`); 686 } 687 let formRead = unifiedDataRecord.getEntry(uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM) as uniformDataStruct.Form; 688 if (formRead != undefined) { 689 console.info(`formName: ${formRead.formName}`); 690 } 691} 692``` 693 694### getEntries<sup>15+</sup> 695 696getEntries(): Record<string, ValueType> 697 698获取当前数据记录中所有数据的类型和内容。 699 700**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 701 702**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 703 704**返回值：** 705 706| 类型 | 说明 | 707| ------ |------------------------------------------------------| 708| Record<string, [ValueType](#valuetype12)> | 当前数据记录对应的类型和内容。 | 709 710**示例：** 711 712```ts 713import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 714 715let fileUriDetails : Record<string, string> = { 716 'attr1': 'value1', 717 'attr2': 'value2', 718} 719let fileUri : uniformDataStruct.FileUri = { 720 uniformDataType : 'general.file-uri', 721 oriUri : 'file://data/image/1.png', 722 fileType : 'general.image', 723 details : fileUriDetails, 724} 725let formDetails : Record<string, string> = { 726 'attr1': 'value1', 727 'attr2': 'value2', 728} 729let form : uniformDataStruct.Form = { 730 uniformDataType : 'openharmony.form', 731 formId : 1, 732 formName : 'form', 733 bundleName : 'com.xx.app', 734 abilityName : 'ability', 735 module : 'module', 736 details : formDetails, 737} 738 739let unifiedData = new unifiedDataChannel.UnifiedData(); 740let record = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM, form); 741record.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, fileUri); 742unifiedData.addRecord(record); 743 744let records = unifiedData.getRecords(); 745for (let i = 0; i < records.length; i++) { 746 let unifiedDataRecord = records[i] as unifiedDataChannel.UnifiedRecord; 747 let entries : Record<string, unifiedDataChannel.ValueType> = unifiedDataRecord.getEntries(); 748 let formRead : uniformDataStruct.Form = entries[uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM] as uniformDataStruct.Form; 749 if (formRead != undefined) { 750 console.info(`formName: ${formRead.formName}`); 751 } 752 let fileUriRead : uniformDataStruct.FileUri = entries[uniformTypeDescriptor.UniformDataType.FILE_URI] as uniformDataStruct.FileUri; 753 if (fileUriRead != undefined) { 754 console.info(`oriUri: ${fileUriRead.oriUri}`); 755 } 756} 757``` 758 759### getTypes<sup>15+</sup> 760 761getTypes(): Array\<string\> 762 763获取当前数据记录中数据的所有类型集合。可通过UnifiedRecord数据记录对象调用本接口，能查询出此记录中数据的所有类型集合，包括使用[addEntry](#addentry15)函数添加的数据类型。 764 765**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 766 767**系统能力** ：SystemCapability.DistributedDataManager.UDMF.Core 768 769**返回值：** 770 771| 类型 | 说明 | 772| ---------------------------------------- |-------------------------| 773| Array\<string\> | [UniformDataType](js-apis-data-uniformTypeDescriptor.md#uniformdatatype)类型的数组，表示当前记录的数据类型集合。 | 774 775**示例：** 776 777```ts 778import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 779 780let fileUriDetails : Record<string, string> = { 781 'attr1': 'value1', 782 'attr2': 'value2', 783} 784let fileUri : uniformDataStruct.FileUri = { 785 uniformDataType : 'general.file-uri', 786 oriUri : 'file://data/image/1.png', 787 fileType : 'general.image', 788 details : fileUriDetails, 789} 790let formDetails : Record<string, string> = { 791 'attr1': 'value1', 792 'attr2': 'value2', 793} 794let form : uniformDataStruct.Form = { 795 uniformDataType : 'openharmony.form', 796 formId : 1, 797 formName : 'form', 798 bundleName : 'com.xx.app', 799 abilityName : 'ability', 800 module : 'module', 801 details : formDetails, 802} 803 804let unifiedData = new unifiedDataChannel.UnifiedData(); 805let record = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM, form); 806record.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, fileUri); 807unifiedData.addRecord(record); 808 809let records = unifiedData.getRecords(); 810for (let i = 0; i < records.length; i++) { 811 let unifiedDataRecord = records[i] as unifiedDataChannel.UnifiedRecord; 812 let types : Array<string> = unifiedDataRecord.getTypes(); 813 if (types.includes(uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM)) { 814 console.info(`Types include: ${uniformTypeDescriptor.UniformDataType.OPENHARMONY_FORM}`); 815 } 816} 817``` 818 819## Text 820 821文本类型数据，是[UnifiedRecord](#unifiedrecord)的子类，也是文本类型数据的基类，用于描述文本类数据，推荐开发者优先使用Text的子类描述数据，如[PlainText](#plaintext)、[Hyperlink](#hyperlink)、[HTML](#html)等具体子类。 822 823**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 824 825**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 826 827| 名称 | 类型 | 只读 | 可选 | 说明 | 828| -------- | -------- | -------- | -------- | -------- | 829| details | Record<string, string> | 否 | 是 | 是一个字典类型对象，key和value都是string类型，用于描述文本内容。例如，可生成一个details内容为<br/>{<br/>"title":"标题",<br/>"content":"内容"<br/>}<br/>的数据对象，用于描述一篇文章。非必填字段，默认值为空字典对象。 | 830 831**示例：** 832 833```ts 834let text = new unifiedDataChannel.Text(); 835text.details = { 836 title: 'MyTitle', 837 content: 'This is content', 838}; 839let unifiedData = new unifiedDataChannel.UnifiedData(text); 840``` 841 842## PlainText 843 844纯文本类型数据，是[Text](#text)的子类，用于描述纯文本类数据。 845 846**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 847 848**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 849 850| 名称 | 类型 | 只读 | 可选 | 说明 | 851| -------- | -------- | -------- | -------- | -------- | 852| textContent | string | 否 | 否 | 纯文本内容。 | 853| abstract | string | 否 | 是 | 纯文本摘要，非必填字段，默认值为空字符串。 | 854 855**示例：** 856 857```ts 858let text = new unifiedDataChannel.PlainText(); 859text.textContent = 'this is textContent'; 860text.abstract = 'This is abstract'; 861``` 862 863## Hyperlink 864 865超链接类型数据，是[Text](#text)的子类，用于描述超链接类型数据。 866 867**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 868 869**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 870 871| 名称 | 类型 | 只读 | 可选 | 说明 | 872| -------- | -------- | -------- | -------- | -------- | 873| url | string | 否 | 否 | 链接url。 | 874| description | string | 否 | 是 | 链接内容描述，非必填字段，默认值为空字符串。 | 875 876**示例：** 877 878```ts 879let link = new unifiedDataChannel.Hyperlink(); 880link.url = 'www.XXX.com'; 881link.description = 'This is description'; 882``` 883 884## HTML 885 886HTML类型数据，是[Text](#text)的子类，用于描述超文本标记语言数据。 887 888**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 889 890**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 891 892| 名称 | 类型 | 只读 | 可选 | 说明 | 893| -------- | -------- | -------- | -------- | -------- | 894| htmlContent | string | 否 | 否 | html格式内容。 | 895| plainContent | string | 否 | 是 | 去除html标签后的纯文本内容，非必填字段，默认值为空字符串。 | 896 897**示例：** 898 899```ts 900let html = new unifiedDataChannel.HTML(); 901html.htmlContent = '<div><p>标题</p></div>'; 902html.plainContent = 'This is plainContent'; 903``` 904 905## File 906 907File类型数据，是[UnifiedRecord](#unifiedrecord)的子类，也是文件类型数据的基类，用于描述文件类型数据，推荐开发者优先使用File的子类描述数据，如[Image](#image)、[Video](#video)、[Folder](#folder)等具体子类。 908 909**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 910 911**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 912 913| 名称 | 类型 | 只读 | 可选 | 说明 | 914| -------- | -------- | -------- | -------- | -------- | 915| details | Record<string, string> | 否 | 是 | 是一个字典类型对象，key和value都是string类型，用于描述文件相关信息。例如，可生成一个details内容为<br/>{<br/>"name":"文件名",<br/>"type":"文件类型"<br/>}<br/>的数据对象，用于描述一个文件。非必填字段，默认值为空字典对象。 | 916| uri | string | 否 | 否 | 本地文件数据uri或网络文件uri，本地文件数据uri可通过[getUriFromPath](../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)函数获取。 | 917 918**示例：** 919 920```ts 921import { unifiedDataChannel } from '@kit.ArkData'; 922import { fileUri } from '@kit.CoreFileKit' 923import { UIAbility } from '@kit.AbilityKit'; 924import { window } from '@kit.ArkUI'; 925 926export default class EntryAbility extends UIAbility { 927 onWindowStageCreate(windowStage: window.WindowStage) { 928 let context = this.context; 929 let pathDir = context.filesDir; 930 let file = new unifiedDataChannel.File(); 931 file.details = { 932 name: 'test', 933 type: 'txt', 934 }; 935 let filePath = pathDir + '/test.txt'; 936 file.uri = fileUri.getUriFromPath(filePath); 937 } 938} 939``` 940 941## Image 942 943图片类型数据，是[File](#file)的子类，用于描述图片文件。 944 945**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 946 947**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 948 949| 名称 | 类型 | 只读 | 可选 | 说明 | 950| -------- | -------- | -------- | -------- | -------- | 951| imageUri | string | 否 | 否 | 本地图片数据uri或网络图片uri，本地图片数据uri可通过[getUriFromPath](../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)函数获取。 | 952 953**示例：** 954 955```ts 956import { unifiedDataChannel } from '@kit.ArkData'; 957import { fileUri } from '@kit.CoreFileKit' 958import { UIAbility } from '@kit.AbilityKit'; 959import { window } from '@kit.ArkUI'; 960 961export default class EntryAbility extends UIAbility { 962 onWindowStageCreate(windowStage: window.WindowStage) { 963 let context = this.context; 964 let pathDir = context.filesDir; 965 let image = new unifiedDataChannel.Image(); 966 let filePath = pathDir + '/test.jpg'; 967 image.imageUri = fileUri.getUriFromPath(filePath); 968 } 969} 970``` 971 972## Video 973 974视频类型数据，是[File](#file)的子类，用于描述视频文件。 975 976**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 977 978**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 979 980| 名称 | 类型 | 只读 | 可选 | 说明 | 981| -------- | -------- | -------- | -------- | -------- | 982| videoUri | string | 否 | 否 | 本地视频数据uri或网络视频uri，本地视频数据uri可通过[getUriFromPath](../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)函数获取。 | 983 984**示例：** 985 986```ts 987import { unifiedDataChannel } from '@kit.ArkData'; 988import { fileUri } from '@kit.CoreFileKit' 989import { UIAbility } from '@kit.AbilityKit'; 990import { window } from '@kit.ArkUI'; 991 992export default class EntryAbility extends UIAbility { 993 onWindowStageCreate(windowStage: window.WindowStage) { 994 let context = this.context; 995 let pathDir = context.filesDir; 996 let video = new unifiedDataChannel.Video(); 997 let filePath = pathDir + '/test.mp4'; 998 video.videoUri =fileUri.getUriFromPath(filePath); 999 } 1000} 1001``` 1002 1003## Audio 1004 1005音频类型数据，是[File](#file)的子类，用于描述音频文件。 1006 1007**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1008 1009**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1010 1011| 名称 | 类型 | 只读 | 可选 | 说明 | 1012| -------- | -------- | -------- | -------- | -------- | 1013| audioUri | string | 否 | 否 | 本地音频数据uri或网络音频uri，本地音频数据uri可通过[getUriFromPath](../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)函数获取。 | 1014 1015**示例：** 1016 1017```ts 1018import { unifiedDataChannel } from '@kit.ArkData'; 1019import { fileUri } from '@kit.CoreFileKit' 1020import { UIAbility } from '@kit.AbilityKit'; 1021import { window } from '@kit.ArkUI'; 1022 1023export default class EntryAbility extends UIAbility { 1024 onWindowStageCreate(windowStage: window.WindowStage) { 1025 let context = this.context; 1026 let pathDir = context.filesDir; 1027 let audio = new unifiedDataChannel.Audio(); 1028 let filePath = pathDir + '/test.mp3'; 1029 audio.audioUri = fileUri.getUriFromPath(filePath); 1030 } 1031} 1032``` 1033 1034## Folder 1035 1036文件夹类型数据，是[File](#file)的子类，用于描述文件夹。 1037 1038**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1039 1040**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1041 1042| 名称 | 类型 | 只读 | 可选 | 说明 | 1043| -------- | -------- | -------- | -------- | -------- | 1044| folderUri | string | 否 | 否 | 本地文件夹数据uri或网络文件夹uri，本地文件夹数据uri可通过[getUriFromPath](../apis-core-file-kit/js-apis-file-fileuri.md#fileurigeturifrompath)函数获取。 | 1045 1046**示例：** 1047 1048```ts 1049import { unifiedDataChannel } from '@kit.ArkData'; 1050import { fileUri } from '@kit.CoreFileKit' 1051import { UIAbility } from '@kit.AbilityKit'; 1052import { window } from '@kit.ArkUI'; 1053 1054export default class EntryAbility extends UIAbility { 1055 onWindowStageCreate(windowStage: window.WindowStage) { 1056 let context = this.context; 1057 let pathDir = context.filesDir; 1058 let folder = new unifiedDataChannel.Folder(); 1059 let filePath = pathDir + '/folder'; 1060 folder.folderUri = fileUri.getUriFromPath(filePath); 1061 } 1062} 1063``` 1064 1065## SystemDefinedRecord 1066 1067SystemDefinedRecord是[UnifiedRecord](#unifiedrecord)的子类，也是OpenHarmony系统特有数据类型的基类，用于描述仅在OpenHarmony系统范围内流通的特有数据类型，推荐开发者优先使用SystemDefinedRecord的子类描述数据，如[SystemDefinedForm](#systemdefinedform)、[SystemDefinedAppItem](#systemdefinedappitem)、[SystemDefinedPixelMap](#systemdefinedpixelmap)等具体子类。 1068 1069**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1070 1071**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1072 1073| 名称 | 类型 | 只读 | 可选 | 说明 | 1074| -------- | -------- | -------- | -------- | -------- | 1075| details | Record<string, number \| string \| Uint8Array> | 否 | 是 | 是一个字典类型对象，key是string类型，value可以写入number（数值类型）、string（字符串类型）、Uint8Array（二进制字节数组）类型数据。非必填字段，默认值为空字典对象。| 1076 1077**示例：** 1078 1079```ts 1080let sdr = new unifiedDataChannel.SystemDefinedRecord(); 1081let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 1082sdr.details = { 1083 title: 'recordTitle', 1084 version: 1, 1085 content: u8Array, 1086}; 1087let unifiedData = new unifiedDataChannel.UnifiedData(sdr); 1088``` 1089 1090## SystemDefinedForm 1091 1092系统定义的桌面卡片类型数据，是[SystemDefinedRecord](#systemdefinedrecord)的子类。 1093 1094**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1095 1096**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1097 1098| 名称 | 类型 | 只读 | 可选 | 说明 | 1099| -------- | -------- | -------- | -------- | -------- | 1100| formId | number | 否 | 否 | 卡片id。 | 1101| formName | string | 否 | 否 | 卡片名称。 | 1102| bundleName | string | 否 | 否 | 卡片所属的bundle名。 | 1103| abilityName | string | 否 | 否 | 卡片对应的ability名。 | 1104| module | string | 否 | 否 | 卡片所属的module名。 | 1105 1106**示例：** 1107 1108```ts 1109let form = new unifiedDataChannel.SystemDefinedForm(); 1110form.formId = 123456; 1111form.formName = 'MyFormName'; 1112form.bundleName = 'MyBundleName'; 1113form.abilityName = 'MyAbilityName'; 1114form.module = 'MyModule'; 1115let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 1116form.details = { 1117 formKey1: 123, 1118 formKey2: 'formValue', 1119 formKey3: u8Array, 1120}; 1121let unifiedData = new unifiedDataChannel.UnifiedData(form); 1122``` 1123 1124## SystemDefinedAppItem 1125 1126系统定义的桌面图标类型数据，是[SystemDefinedRecord](#systemdefinedrecord)的子类。 1127 1128**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1129 1130**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1131 1132| 名称 | 类型 | 只读 | 可选 | 说明 | 1133| -------- | -------- | -------- | -------- | -------- | 1134| appId | string | 否 | 否 | 图标对应的应用id。 | 1135| appName | string | 否 | 否 | 图标对应的应用名。 | 1136| appIconId | string | 否 | 否 | 图标的图片id。 | 1137| appLabelId | string | 否 | 否 | 图标名称对应的标签id。 | 1138| bundleName | string | 否 | 否 | 图标对应的应用bundle名。 | 1139| abilityName | string | 否 | 否 | 图标对应的应用ability名。 | 1140 1141**示例：** 1142 1143```ts 1144let appItem = new unifiedDataChannel.SystemDefinedAppItem(); 1145appItem.appId = 'MyAppId'; 1146appItem.appName = 'MyAppName'; 1147appItem.appIconId = 'MyAppIconId'; 1148appItem.appLabelId = 'MyAppLabelId'; 1149appItem.bundleName = 'MyBundleName'; 1150appItem.abilityName = 'MyAbilityName'; 1151let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 1152appItem.details = { 1153 appItemKey1: 123, 1154 appItemKey2: 'appItemValue', 1155 appItemKey3: u8Array, 1156}; 1157let unifiedData = new unifiedDataChannel.UnifiedData(appItem); 1158``` 1159 1160## SystemDefinedPixelMap 1161 1162与系统侧定义的[PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)数据类型对应的图片数据类型，是[SystemDefinedRecord](#systemdefinedrecord)的子类，仅保存PixelMap的二进制数据。 1163 1164**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1165 1166**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1167 1168| 名称 | 类型 | 只读 | 可选 | 说明 | 1169| -------- | -------- | -------- | -------- | -------- | 1170| rawData | Uint8Array | 否 | 否 | PixelMap对象的二进制数据。 | 1171 1172**示例：** 1173 1174```ts 1175import { image } from '@kit.ImageKit'; // PixelMap类定义所在模块 1176import { unifiedDataChannel, uniformTypeDescriptor } from '@kit.ArkData'; 1177import { BusinessError } from '@kit.BasicServicesKit'; 1178 1179const color = new ArrayBuffer(96); // 创建pixelmap对象 1180let opts: image.InitializationOptions = { 1181 editable: true, pixelFormat: 3, size: { 1182 height: 4, width: 6 1183 } 1184} 1185image.createPixelMap(color, opts, (error, pixelmap) => { 1186 if (error) { 1187 console.error('Failed to create pixelmap.'); 1188 } else { 1189 console.info('Succeeded in creating pixelmap.'); 1190 let arrayBuf = new ArrayBuffer(pixelmap.getPixelBytesNumber()); 1191 pixelmap.readPixelsToBuffer(arrayBuf); 1192 let u8Array = new Uint8Array(arrayBuf); 1193 let sdpixel = new unifiedDataChannel.SystemDefinedPixelMap(); 1194 sdpixel.rawData = u8Array; 1195 let unifiedData = new unifiedDataChannel.UnifiedData(sdpixel); 1196 1197 // 从unifiedData中读取pixelMap类型的record 1198 let records = unifiedData.getRecords(); 1199 for (let i = 0; i < records.length; i++) { 1200 if (records[i].getType() === uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP) { 1201 let pixelmapRecord = records[i] as unifiedDataChannel.SystemDefinedPixelMap; 1202 let newArraybuf = pixelmapRecord.rawData.buffer; 1203 pixelmap.writeBufferToPixels(newArraybuf).then(() => { 1204 console.info('Succeeded in writing data from buffer to a pixelMap'); 1205 }).catch((error: BusinessError) => { 1206 console.error(`Failed to write data from a buffer to a PixelMap. code is ${error.code}, message is ${error.message}`); 1207 }) 1208 } 1209 } 1210 } 1211}) 1212``` 1213 1214## ApplicationDefinedRecord 1215 1216ApplicationDefinedRecord是[UnifiedRecord](#unifiedrecord)的子类，也是应用自定义数据类型的基类，用于描述仅在应用生态内部流通的自定义数据类型，应用可基于此类进行自定义数据类型的扩展。 1217 1218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1219 1220**系统能力**：SystemCapability.DistributedDataManager.UDMF.Core 1221 1222| 名称 | 类型 | 只读 | 可选 | 说明 | 1223| -------- | -------- | -------- | -------- | -------- | 1224| applicationDefinedType | string | 否 | 否 | 应用自定义类型标识符，必须以'ApplicationDefined'开头。 | 1225| rawData | Uint8Array | 否 | 否 | 应用自定义数据类型的二进制数据。 | 1226 1227**示例：** 1228 1229```ts 1230let record = new unifiedDataChannel.ApplicationDefinedRecord(); 1231let u8Array = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); 1232record.applicationDefinedType = 'ApplicationDefinedType'; 1233record.rawData = u8Array; 1234let unifiedData = new unifiedDataChannel.UnifiedData(record); 1235``` 1236 1237## Intention 1238 1239UDMF已经支持的数据通路枚举类型。其主要用途是标识各种UDMF数据通路所面向的不同业务场景。 1240 1241**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1242 1243| 名称 | 值 | 说明 | 1244|----------|-----------|---------| 1245| DATA_HUB | 'DataHub' | 公共数据通路。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 1246| DRAG<sup>14+</sup> | 'Drag' | 拖拽类型数据通道。<br/>**模型约束：** 此接口仅可在Stage模型下使用。 | 1247 1248## Options 1249 1250type Options = { intention?: Intention; key?: string; } 1251 1252UDMF提供的数据操作接口可选项，包含intention和key两个可选参数。当对应接口不需要此参数时可不填，具体要求参照方法接口的参数说明。 1253 1254**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1255 1256**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1257 1258| 名称 | 类型 | 必填 | 说明 | 1259| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 1260| intention | [Intention](#intention) | 否 | 表示数据操作相关的数据通路类型。 | 1261| key | string | 否 | UDMF中数据对象的唯一标识符，可通过[insertData](#unifieddatachannelinsertdata)接口的返回值获取。<br>由udmf:/、intention、bundleName和groupId四部分组成，以'/'连接，比如：udmf://DataHub/com.ohos.test/0123456789。<br>其中udmf:/固定，DataHub为对应枚举的取值，com.ohos.test为包名，0123456789为随机生成的groupId。 | 1262 1263## FileConflictOptions<sup>15+</sup> 1264 1265表示文件拷贝冲突时的可选策略的枚举。 1266 1267**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1268 1269**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1270 1271| 名称 | 值 | 说明 | 1272| --------- | ---- |----------------| 1273| OVERWRITE | 0 | 目标路径存在同文件名时覆盖。 | 1274| SKIP | 1 | 目标路径存在同文件名时跳过。 | 1275 1276## ProgressIndicator<sup>15+</sup> 1277 1278表示进度条指示选项的枚举，可选择是否采用系统默认进度显示。 1279 1280**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1281 1282**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1283 1284| 名称 | 值 | 说明 | 1285| ------- | ---- |------------------------------------| 1286| NONE | 0 | 不采用系统默认进度显示。 | 1287| DEFAULT | 1 | 采用系统默认进度显示，500ms内获取数据完成将不会拉起默认进度条。 | 1288 1289## ListenerStatus<sup>15+</sup> 1290 1291表示从UDMF获取数据时的状态码的枚举。 1292 1293**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1294 1295**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1296 1297| 名称 | 值 | 说明 | 1298| ------- |-----|----------------------------------------------| 1299| FINISHED | 0 | 表示已完成。 | 1300| PROCESSING | 1 | 表示正在处理中。 | 1301| CANCELED | 2 | 表明本次处理已被取消。 | 1302| INNER_ERROR | 200 | 表明发生了内部错误。 | 1303| INVALID_PARAMETERS | 201 | 表示 [GetDataParams](#getdataparams15) 包含无效参数。 | 1304| DATA_NOT_FOUND | 202 | 表示没有获取到数据。 | 1305| SYNC_FAILED | 203 | 表示同步过程中出现错误。 | 1306| COPY_FILE_FAILED | 204 | 表示文件拷贝过程中出现错误。 | 1307 1308## ProgressInfo<sup>15+</sup> 1309 1310定义进度上报的数据。 1311 1312**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1313 1314**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1315 1316| 名称 | 类型 | 可读 | 可写 | 说明 | 1317| -------- |-------------------------------------| ---- | ---- |----------------------------------------------------------------| 1318| progress | number | 是 | 否 | 系统上报拖拽任务进度百分比。取值范围为[-1-100]的整数，其中-1时代表本次获取数据失败，100时表示本次获取数据完成。 | 1319| status | [ListenerStatus](#listenerstatus15) | 是 | 否 | 系统上报拖拽任务的状态码。 | 1320 1321## DataProgressListener<sup>15+</sup> 1322 1323type DataProgressListener = (progressInfo: ProgressInfo, data: UnifiedData | null) => void 1324 1325定义获取进度信息和数据的监听回调函数。 1326 1327**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1328 1329**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1330 1331**参数：** 1332 1333| 参数名 | 类型 | 必填 | 说明 | 1334|----------|-------------------------------|-------|--------------| 1335| progressInfo| [ProgressInfo](#progressinfo15) | 是 | 定义进度上报的进度信息。 | 1336| data | [UnifiedData](#unifieddata) \| null | 是 | 进度达到100时获取的数据，进度未到100时返回null。 | 1337 1338## GetDataParams<sup>15+</sup> 1339 1340表示从UDMF获取数据时的参数，包含目标路径、文件冲突选项、进度条类型等。 1341 1342具体使用示例可见[拖拽异步获取数据](../apis-arkui/arkui-ts/ts-universal-events-drag-drop.md#示例3拖拽异步获取数据)。 1343 1344**原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 1345 1346**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1347 1348**参数：** 1349 1350| 名称 | 类型 | 必填 | 说明 | 1351|----------------------|-------------------------------------------------| ---- |----------------------------------------------------------------------------------------------------------------------------------------------------| 1352| progressIndicator | [ProgressIndicator](#progressindicator15) | 是 | 定义进度条指示选项，可选择是否采用系统默认进度显示。 | 1353| dataProgressListener | [DataProgressListener](#dataprogresslistener15) | 是 | 表示获取统一数据时的进度和数据监听器。 | 1354| destUri | string | 否 | 拷贝文件的目标路径。若不支持文件处理，则不需要设置此参数,默认为空；若支持文件处理，须设置一个已经存在的目录。若应用涉及复杂文件处理策略或需要区分文件多路径存储，建议不设置此参数，由应用自行完成文件copy处理。不填写时获取到到的uri为源端路径URI，填写后获取到的uri为目标路径uri。| 1355| fileConflictOptions | [FileConflictOptions](#fileconflictoptions15) | 否 | 定义文件拷贝冲突时的选项，默认为OVERWRITE。 | 1356 1357## unifiedDataChannel.insertData 1358 1359insertData(options: Options, data: UnifiedData, callback: AsyncCallback<string>): void 1360 1361将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用callback异步回调。 1362 1363**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1364 1365**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1366 1367**参数：** 1368 1369| 参数名 | 类型 | 必填 | 说明 | 1370|----------|----------------------------|----|------------------------------| 1371| options | [Options](#options) | 是 | 配置项参数，参数中intention字段必填，不填时会返回401错误码；其他字段是否填写均不影响接口的使用。 | 1372| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1373| callback | AsyncCallback<string> | 是 | 回调函数，返回写入UDMF的数据的唯一标识符key的值。 | 1374 1375**错误码：** 1376 1377以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1378 1379| **错误码ID** | **错误信息** | 1380| ------------ | ------------------------------------------- | 1381| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1382 1383**示例：** 1384 1385```ts 1386import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1387import { BusinessError } from '@kit.BasicServicesKit'; 1388 1389let plainText : uniformDataStruct.PlainText = { 1390 uniformDataType: 'general.plain-text', 1391 textContent : 'This is a plain text example', 1392 abstract : 'This is abstract', 1393} 1394let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 1395let unifiedData = new unifiedDataChannel.UnifiedData(text); 1396 1397let options: unifiedDataChannel.Options = { 1398 intention: unifiedDataChannel.Intention.DATA_HUB 1399} 1400try { 1401 unifiedDataChannel.insertData(options, unifiedData, (err, key) => { 1402 if (err === undefined) { 1403 console.info(`Succeeded in inserting data. key = ${key}`); 1404 } else { 1405 console.error(`Failed to insert data. code is ${err.code}, message is ${err.message} `); 1406 } 1407 }); 1408} catch (e) { 1409 let error: BusinessError = e as BusinessError; 1410 console.error(`Insert data throws an exception. code is ${error.code}, message is ${error.message} `); 1411} 1412``` 1413 1414## unifiedDataChannel.insertData 1415 1416insertData(options: Options, data: UnifiedData): Promise<string> 1417 1418将数据写入UDMF的公共数据通路中，并生成数据的唯一标识符，使用Promise异步回调。 1419 1420**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1421 1422**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1423 1424**参数：** 1425 1426| 参数名 | 类型 | 必填 | 说明 | 1427|---------|-----------------------------|----|-----------------------| 1428| options | [Options](#options) | 是 | 配置项参数，参数中intention字段必填，不填时会返回401错误码；其他字段是否填写均不影响接口的使用。 | 1429| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1430 1431**返回值：** 1432 1433| 类型 | 说明 | 1434|-----------------------|-----------------------------------| 1435| Promise<string> | Promise对象，返回写入UDMF的数据的唯一标识符key的值。 | 1436 1437**错误码：** 1438 1439以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1440 1441| **错误码ID** | **错误信息** | 1442| ------------ | ------------------------------------------- | 1443| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1444 1445**示例：** 1446 1447```ts 1448import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1449import { BusinessError } from '@kit.BasicServicesKit'; 1450 1451let plainText : uniformDataStruct.PlainText = { 1452 uniformDataType: 'general.plain-text', 1453 textContent : 'This is a plain text example', 1454 abstract : 'This is abstract', 1455} 1456let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 1457let unifiedData = new unifiedDataChannel.UnifiedData(text); 1458 1459let options: unifiedDataChannel.Options = { 1460 intention: unifiedDataChannel.Intention.DATA_HUB 1461} 1462try { 1463 unifiedDataChannel.insertData(options, unifiedData).then((key) => { 1464 console.info(`Succeeded in inserting data. key = ${key}`); 1465 }).catch((err: BusinessError) => { 1466 console.error(`Failed to insert data. code is ${err.code}, message is ${err.message} `); 1467 }); 1468} catch (e) { 1469 let error: BusinessError = e as BusinessError; 1470 console.error(`Insert data throws an exception. code is ${error.code}, message is ${error.message} `); 1471} 1472``` 1473 1474## unifiedDataChannel.updateData 1475 1476updateData(options: Options, data: UnifiedData, callback: AsyncCallback<void>): void 1477 1478更新已写入UDMF的公共数据通路的数据，使用callback异步回调。 1479 1480**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1481 1482**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1483 1484**参数：** 1485 1486| 参数名 | 类型 | 必填 | 说明 | 1487|----------|-----------------------------|----|-------------------------------------| 1488| options | [Options](#options) | 是 | 配置项参数，参数中key字段必填，不填时会返回401错误码；其他字段是否填写均不影响接口的使用。 | 1489| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1490| callback | AsyncCallback<void> | 是 | 回调函数。当更新数据成功，err为undefined，否则为错误对象。 | 1491 1492**错误码：** 1493 1494以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1495 1496| **错误码ID** | **错误信息** | 1497| ------------ | ------------------------------------------- | 1498| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1499 1500**示例：** 1501 1502```ts 1503import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1504import { BusinessError } from '@kit.BasicServicesKit'; 1505 1506let plainText : uniformDataStruct.PlainText = { 1507 uniformDataType: 'general.plain-text', 1508 textContent : 'This is a plain text example', 1509 abstract : 'This is abstract', 1510} 1511let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 1512let unifiedData = new unifiedDataChannel.UnifiedData(text); 1513let options: unifiedDataChannel.Options = { 1514 intention: unifiedDataChannel.Intention.DATA_HUB 1515} 1516try { 1517 unifiedDataChannel.insertData(options, unifiedData).then((key) => { 1518 console.info(`Succeeded in inserting data. key = ${key}`); 1519 let updateOptions: unifiedDataChannel.Options = { 1520 intention: unifiedDataChannel.Intention.DATA_HUB, 1521 key: key 1522 } 1523 let plainTextUpdate : uniformDataStruct.PlainText = { 1524 uniformDataType: 'general.plain-text', 1525 textContent : 'This is plainText textContent for update', 1526 abstract : 'This is abstract for update', 1527 } 1528 let textUpdate = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainTextUpdate); 1529 let unifiedDataUpdate = new unifiedDataChannel.UnifiedData(textUpdate); 1530 try { 1531 unifiedDataChannel.updateData(updateOptions, unifiedDataUpdate, (err) => { 1532 if (err === undefined) { 1533 console.info('Succeeded in updating data.'); 1534 } else { 1535 console.error(`Failed to update data. code is ${err.code}, message is ${err.message} `); 1536 } 1537 }); 1538 } catch (e) { 1539 let error: BusinessError = e as BusinessError; 1540 console.error(`Update data throws an exception. code is ${error.code}, message is ${error.message} `); 1541 } 1542 }).catch((err: BusinessError) => { 1543 console.error(`Failed to insert data. code is ${err.code}, message is ${err.message} `); 1544 }); 1545} catch (e) { 1546 let error: BusinessError = e as BusinessError; 1547 console.error(`Insert data throws an exception. code is ${error.code}, message is ${error.message} `); 1548} 1549``` 1550 1551## unifiedDataChannel.updateData 1552 1553updateData(options: Options, data: UnifiedData): Promise<void> 1554 1555更新已写入UDMF的公共数据通路的数据，使用Promise异步回调。 1556 1557**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1558 1559**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1560 1561**参数：** 1562 1563| 参数名 | 类型 | 必填 | 说明 | 1564|---------|-----------------------------|----|-----------------| 1565| options | [Options](#options) | 是 | 配置项参数，参数中key字段必填，不填时会返回401错误码；其他字段是否填写均不影响接口的使用。 | 1566| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1567 1568**返回值：** 1569 1570| 类型 | 说明 | 1571|---------------------|----------------------------| 1572| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1573 1574**错误码：** 1575 1576以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1577 1578| **错误码ID** | **错误信息** | 1579| ------------ | ------------------------------------------- | 1580| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1581 1582**示例：** 1583 1584```ts 1585import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1586import { BusinessError } from '@kit.BasicServicesKit'; 1587 1588let plainText : uniformDataStruct.PlainText = { 1589 uniformDataType: 'general.plain-text', 1590 textContent : 'This is a plain text example', 1591 abstract : 'This is abstract', 1592} 1593let text = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 1594let unifiedData = new unifiedDataChannel.UnifiedData(text); 1595let options: unifiedDataChannel.Options = { 1596 intention: unifiedDataChannel.Intention.DATA_HUB 1597} 1598try { 1599 unifiedDataChannel.insertData(options, unifiedData).then((key) => { 1600 console.info(`Succeeded in inserting data. key = ${key}`); 1601 let updateOptions: unifiedDataChannel.Options = { 1602 intention: unifiedDataChannel.Intention.DATA_HUB, 1603 key: key 1604 } 1605 let plainTextUpdate : uniformDataStruct.PlainText = { 1606 uniformDataType: 'general.plain-text', 1607 textContent : 'This is plainText textContent for update', 1608 abstract : 'This is abstract for update', 1609 } 1610 let textUpdate = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainTextUpdate); 1611 let unifiedDataUpdate = new unifiedDataChannel.UnifiedData(textUpdate); 1612 try { 1613 unifiedDataChannel.updateData(updateOptions, unifiedDataUpdate).then(() => { 1614 console.info('Succeeded in updating data.'); 1615 }).catch((err: BusinessError) => { 1616 console.error(`Failed to update data. code is ${err.code}, message is ${err.message} `); 1617 }); 1618 } catch (e) { 1619 let error: BusinessError = e as BusinessError; 1620 console.error(`Update data throws an exception. code is ${error.code}, message is ${error.message} `); 1621 } 1622 }).catch((err: BusinessError) => { 1623 console.error(`Failed to insert data. code is ${err.code}, message is ${err.message} `); 1624 }); 1625} catch (e) { 1626 let error: BusinessError = e as BusinessError; 1627 console.error(`Insert data throws an exception. code is ${error.code}, message is ${error.message} `); 1628} 1629``` 1630 1631## unifiedDataChannel.queryData 1632 1633queryData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void 1634 1635查询UDMF公共数据通路的数据，使用callback异步回调。 1636 1637**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1638 1639**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1640 1641**参数：** 1642 1643| 参数名 | 类型 | 必填 | 说明 | 1644|----------|---------------------------------------------------------------|----|------------------------------------------------------------------------------------------------------------------------------------------------------------------| 1645| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1646| callback | AsyncCallback<Array<[UnifiedData](#unifieddata)>> | 是 | 回调函数，返回查询到的所有数据。<br>如果options中填入的是key，则返回key对应的数据。<br>如果options中填入的是intention，则返回intention下所有数据。<br>如intention和key均填写了，取两者查询数据的交集，与options只填入key的获取结果一致；如没有交集报错。 | 1647 1648**错误码：** 1649 1650以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1651 1652| **错误码ID** | **错误信息** | 1653| ------------ | ------------------------------------------- | 1654| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1655 1656**示例：** 1657 1658```ts 1659import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1660import { BusinessError } from '@kit.BasicServicesKit'; 1661 1662let options: unifiedDataChannel.Options = { 1663 intention: unifiedDataChannel.Intention.DATA_HUB 1664}; 1665 1666try { 1667 unifiedDataChannel.queryData(options, (err, data) => { 1668 if (err === undefined) { 1669 console.info(`Succeeded in querying data. size = ${data.length}`); 1670 for (let i = 0; i < data.length; i++) { 1671 let records = data[i].getRecords(); 1672 for (let j = 0; j < records.length; j++) { 1673 if (records[j].getTypes().includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)) { 1674 let text = records[j].getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as uniformDataStruct.PlainText; 1675 console.info(`${i + 1}.${text.textContent}`); 1676 } 1677 } 1678 } 1679 } else { 1680 console.error(`Failed to query data. code is ${err.code}, message is ${err.message} `); 1681 } 1682 }); 1683} catch (e) { 1684 let error: BusinessError = e as BusinessError; 1685 console.error(`Query data throws an exception. code is ${error.code}, message is ${error.message} `); 1686} 1687``` 1688 1689## unifiedDataChannel.queryData 1690 1691queryData(options: Options): Promise<Array<UnifiedData>> 1692 1693查询UDMF公共数据通路的数据，使用Promise异步回调。 1694 1695**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1696 1697**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1698 1699**参数：** 1700 1701| 参数名 | 类型 | 必填 | 说明 | 1702|---------|---------------------|----|-----------------------------------------------| 1703| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1704 1705**返回值：** 1706 1707| 类型 | 说明 | 1708|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| 1709| Promise<Array<[UnifiedData](#unifieddata)>> | Promise对象，返回查询到的所有数据。<br>如果options中填入的是key，则返回key对应的数据。<br>如果options中填入的是intention，则返回intention下所有数据。<br>如intention和key均填写了，取两者查询数据的交集，与options只填入key的获取结果一致；如没有交集报错。 | 1710 1711**错误码：** 1712 1713以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1714 1715| **错误码ID** | **错误信息** | 1716| ------------ | ------------------------------------------- | 1717| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1718 1719**示例：** 1720 1721```ts 1722import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1723import { BusinessError } from '@kit.BasicServicesKit'; 1724 1725let options: unifiedDataChannel.Options = { 1726 key: 'udmf://DataHub/com.ohos.test/0123456789' 1727}; 1728 1729try { 1730 unifiedDataChannel.queryData(options).then((data) => { 1731 console.info(`Succeeded in querying data. size = ${data.length}`); 1732 for (let i = 0; i < data.length; i++) { 1733 let records = data[i].getRecords(); 1734 for (let j = 0; j < records.length; j++) { 1735 if (records[j].getTypes().includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)) { 1736 let text = records[j].getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as uniformDataStruct.PlainText; 1737 console.info(`${i + 1}.${text.textContent}`); 1738 } 1739 } 1740 } 1741 }).catch((err: BusinessError) => { 1742 console.error(`Failed to query data. code is ${err.code}, message is ${err.message} `); 1743 }); 1744} catch (e) { 1745 let error: BusinessError = e as BusinessError; 1746 console.error(`Query data throws an exception. code is ${error.code}, message is ${error.message} `); 1747} 1748``` 1749 1750## unifiedDataChannel.deleteData 1751 1752deleteData(options: Options, callback: AsyncCallback<Array<UnifiedData>>): void 1753 1754删除UDMF公共数据通路的数据，返回删除的数据集，使用callback异步回调。 1755 1756**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1757 1758**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1759 1760**参数：** 1761 1762| 参数名 | 类型 | 必填 | 说明 | 1763|----------|---------------------------------------------------------------|----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 1764| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1765| callback | AsyncCallback<Array<[UnifiedData](#unifieddata)>> | 是 | 回调函数，返回删除的所有数据。<br>如果options中填入的是key，则删除key对应的数据并返回该数据。<br>如果options中填入的是intention，则删除intention下所有数据并返回删除的数据。<br>如intention和key均填写了，取两者数据的交集进行删除，并返回删除的数据，与options只填入key的结果一致；如没有交集报错。 | 1766 1767**错误码：** 1768 1769以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1770 1771| **错误码ID** | **错误信息** | 1772| ------------ | ------------------------------------------- | 1773| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1774 1775**示例：** 1776 1777```ts 1778import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1779import { BusinessError } from '@kit.BasicServicesKit'; 1780 1781let options: unifiedDataChannel.Options = { 1782 intention: unifiedDataChannel.Intention.DATA_HUB 1783}; 1784 1785try { 1786 unifiedDataChannel.deleteData(options, (err, data) => { 1787 if (err === undefined) { 1788 console.info(`Succeeded in deleting data. size = ${data.length}`); 1789 for (let i = 0; i < data.length; i++) { 1790 let records = data[i].getRecords(); 1791 for (let j = 0; j < records.length; j++) { 1792 if (records[j].getTypes().includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)) { 1793 let text = records[j].getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as uniformDataStruct.PlainText; 1794 console.info(`${i + 1}.${text.textContent}`); 1795 } 1796 } 1797 } 1798 } else { 1799 console.error(`Failed to delete data. code is ${err.code}, message is ${err.message} `); 1800 } 1801 }); 1802} catch (e) { 1803 let error: BusinessError = e as BusinessError; 1804 console.error(`Delete data throws an exception. code is ${error.code}, message is ${error.message} `); 1805} 1806``` 1807 1808## unifiedDataChannel.deleteData 1809 1810deleteData(options: Options): Promise<Array<UnifiedData>> 1811 1812删除UDMF公共数据通路的数据，返回删除的数据集，使用Promise异步回调。 1813 1814**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 1815 1816**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1817 1818**参数：** 1819 1820| 参数名 | 类型 | 必填 | 说明 | 1821|---------|---------------------|----|--------| 1822| options | [Options](#options) | 是 | 配置项参数，key和intention均为可选，根据传入的参数做相应的校验以返回不同的值。 | 1823 1824**返回值：** 1825 1826| 类型 | 说明 | 1827|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| 1828| Promise<Array<[UnifiedData](#unifieddata)>> | Promise对象，返回删除的所有数据。<br>如果options中填入的是key，则删除key对应的数据并返回该数据。<br>如果options中填入的是intention，则删除intention下所有数据并返回删除的数据。<br>如intention和key均填写了，取两者数据的交集进行删除，并返回删除的数据，与options只填入key的结果一致；如没有交集报错。 | 1829 1830**错误码：** 1831 1832以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1833 1834| **错误码ID** | **错误信息** | 1835| ------------ | ------------------------------------------- | 1836| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1837 1838**示例：** 1839 1840```ts 1841import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1842import { BusinessError } from '@kit.BasicServicesKit'; 1843 1844let options: unifiedDataChannel.Options = { 1845 key: 'udmf://DataHub/com.ohos.test/0123456789' 1846}; 1847 1848try { 1849 unifiedDataChannel.deleteData(options).then((data) => { 1850 console.info(`Succeeded in deleting data. size = ${data.length}`); 1851 for (let i = 0; i < data.length; i++) { 1852 let records = data[i].getRecords(); 1853 for (let j = 0; j < records.length; j++) { 1854 if (records[j].getTypes().includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)) { 1855 let text = records[j].getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as uniformDataStruct.PlainText; 1856 console.info(`${i + 1}.${text.textContent}`); 1857 } 1858 } 1859 } 1860 }).catch((err: BusinessError) => { 1861 console.error(`Failed to delete data. code is ${err.code}, message is ${err.message} `); 1862 }); 1863} catch (e) { 1864 let error: BusinessError = e as BusinessError; 1865 console.error(`Query data throws an exception. code is ${error.code}, message is ${error.message} `); 1866} 1867``` 1868 1869## unifiedDataChannel.setAppShareOptions<sup>14+</sup> 1870 1871setAppShareOptions(intention: Intention, shareOptions: ShareOptions): void 1872 1873设置应用内拖拽通道数据可使用的范围[ShareOptions](#shareoptions12)，目前仅支持DRAG类型数据通道的管控设置。 1874 1875**需要权限:** ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION 1876 1877**模型约束：** 此接口仅可在Stage模型下使用。 1878 1879**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1880 1881**参数：** 1882 1883| 参数名 | 类型 | 必填 | 说明 | 1884|----------|----------------------------|----|------------------------------| 1885| intention | [Intention](#intention) | 是 | 表示数据操作相关的数据通路类型，目前仅支持DRAG类型数据通道。 | 1886| shareOptions | [ShareOptions](#shareoptions12) | 是 | 指示[UnifiedData](#unifieddata)支持的设备内使用范围。 | 1887 1888**错误码：** 1889 1890以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[统一数据管理框架错误码](errorcode-udmf.md)。 1891 1892| **错误码ID** | **错误信息** | 1893| ------------ | ------------------------------------------------------------ | 1894| 201 | Permission denied. Interface caller does not have permission "ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION". | 1895| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1896| 20400001 | Settings already exist. | 1897 1898**示例：** 1899 1900```ts 1901import { BusinessError } from '@kit.BasicServicesKit'; 1902try { 1903 unifiedDataChannel.setAppShareOptions(unifiedDataChannel.Intention.DRAG, unifiedDataChannel.ShareOptions.IN_APP); 1904 console.info(`[UDMF]setAppShareOptions success. `); 1905}catch (e){ 1906 let error: BusinessError = e as BusinessError; 1907 console.error(`[UDMF]setAppShareOptions throws an exception. code is ${error.code}, message is ${error.message} `); 1908} 1909``` 1910 1911## unifiedDataChannel.removeAppShareOptions<sup>14+</sup> 1912 1913removeAppShareOptions(intention: Intention): void 1914 1915清除[setAppShareOptions](#unifieddatachannelsetappshareoptions14)设置的管控信息。 1916 1917**需要权限:** ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION 1918 1919**模型约束：** 此接口仅可在Stage模型下使用。 1920 1921**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1922 1923**参数：** 1924 1925| 参数名 | 类型 | 必填 | 说明 | 1926| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 1927| intention | [Intention](#intention) | 是 | 表示数据操作相关的数据通路类型，目前仅支持DRAG类型数据通道。 | 1928 1929**错误码：** 1930 1931以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1932 1933| **错误码ID** | **错误信息** | 1934| ------------ | ------------------------------------------------------------ | 1935| 201 | Permission denied. Interface caller does not have permission "ohos.permission.MANAGE_UDMF_APP_SHARE_OPTION". | 1936| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1937 1938**示例：** 1939 1940```ts 1941import { BusinessError } from '@kit.BasicServicesKit'; 1942try { 1943 unifiedDataChannel.removeAppShareOptions(unifiedDataChannel.Intention.DRAG); 1944 console.info(`[UDMF]removeAppShareOptions success. `); 1945}catch (e){ 1946 let error: BusinessError = e as BusinessError; 1947 console.error(`[UDMF]removeAppShareOptions throws an exception. code is ${error.code}, message is ${error.message} `); 1948} 1949``` 1950 1951## unifiedDataChannel.convertRecordsToEntries<sup>17+</sup> 1952 1953convertRecordsToEntries(data: UnifiedData): void 1954 1955本接口用于将传入的data转换成多样式数据结构。若原data使用多个record去承载同一份数据的不同样式，则可以使用此接口将原data转换为多样式数据结构。 1956 1957当满足以下规则时进行转换，传入的data经转换后变为多样式数据结构： 19581. data中的record数量大于1; 19592. data中的properties中的tag值为"records_to_entries_data_format"。 1960 1961否则不会产生任何行为。 1962 1963**原子化服务API：** 从API version 17开始，该接口支持在原子化服务中使用。 1964 1965**模型约束：** 此接口仅可在Stage模型下使用。 1966 1967**系统能力：** SystemCapability.DistributedDataManager.UDMF.Core 1968 1969**参数：** 1970 1971| 参数名 | 类型 | 必填 | 说明 | 1972| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 1973| data | [UnifiedData](#unifieddata) | 是 | 目标数据。 | 1974 1975**错误码：** 1976 1977以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1978 1979| **错误码ID** | **错误信息** | 1980| ------------ | ------------------------------------------------------------ | 1981| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1982 1983**示例：** 1984 1985```ts 1986import { unifiedDataChannel } from '@kit.ArkData'; 1987import { uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 1988import { BusinessError } from '@kit.BasicServicesKit'; 1989 1990let details : Record<string, string> = { 1991 'attr1': 'value1', 1992 'attr2': 'value2', 1993} 1994let plainTextObj : uniformDataStruct.PlainText = { 1995 uniformDataType: 'general.plain-text', 1996 textContent : 'The weather is very good today', 1997 abstract : 'The weather is very good today', 1998 details : details, 1999} 2000let htmlObj : uniformDataStruct.HTML = { 2001 uniformDataType :'general.html', 2002 htmlContent : '<div><p>The weather is very good today</p></div>', 2003 plainContent : 'The weather is very good today', 2004 details : details, 2005} 2006let plainText = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainTextObj); 2007let html = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.HTML, htmlObj); 2008let unifiedData = new unifiedDataChannel.UnifiedData(plainText); 2009unifiedData.addRecord(html); 2010unifiedData.properties.tag = 'records_to_entries_data_format'; 2011 2012try { 2013 unifiedDataChannel.convertRecordsToEntries(unifiedData); 2014 let records: Array<unifiedDataChannel.UnifiedRecord> = unifiedData.getRecords(); 2015 console.info(`Records size is ${records.length}`); // After conversion, its length must be less than 1 2016 if (records.length == 1) { 2017 let plainTextObjRead: uniformDataStruct.PlainText = records[0].getEntry(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) as uniformDataStruct.PlainText; 2018 console.info(`TextContent is ${plainTextObjRead.textContent}`); 2019 let htmlObjRead: uniformDataStruct.HTML = records[0].getEntry(uniformTypeDescriptor.UniformDataType.HTML) as uniformDataStruct.HTML; 2020 console.info(`HtmlContent is ${htmlObjRead.htmlContent}`); 2021 } 2022} catch (e) { 2023 let error: BusinessError = e as BusinessError; 2024 console.error(`Convert data throws an exception. code is ${error.code}, message is ${error.message} `); 2025} 2026```
