1# @ohos.pasteboard (Pasteboard) 2 3The **Pasteboard** module provides the copy and paste support for the system pasteboard. You can use the APIs of this module to operate pasteboard content of the plain text, HTML, URI, Want, pixel map, and other types. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8 9## Modules to Import 10 11```ts 12import { pasteboard } from '@kit.BasicServicesKit'; 13``` 14 15## Constants 16 17**Atomic service API**: This API can be used in atomic services since API version 11. 18 19**System capability**: SystemCapability.MiscServices.Pasteboard 20 21| Name| Type| Value | Description | 22| -------- | -------- |--------------|-------------------------------------------------------------------------------------------------------------------------------------------| 23| MAX_RECORD_NUM<sup>7+</sup> | number | - | Maximum number of records in a **PasteData** object. In versions earlier than API version 10, the value is 512, indicating that no more records can be added once the number of records reaches 512.<br>Since API version 10, no limit is placed on the number of records in a **PasteData** object.| 24| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | 'text/html' | MIME type of the HTML content. | 25| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | 'text/want' | MIME type of the Want content. | 26| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | 'text/plain' | MIME type of the plain text content. | 27| MIMETYPE_TEXT_URI<sup>7+</sup> | string | 'text/uri' | MIME type of the URI content. | 28| MIMETYPE_PIXELMAP<sup>9+</sup> | string | 'pixelMap' | MIME type of the pixel map. | 29 30## ValueType<sup>9+</sup> 31 32type ValueType = string | image.PixelMap | Want | ArrayBuffer 33 34Enumerates the value types. 35 36**Atomic service API**: This API can be used in atomic services since API version 11. 37 38**System capability**: SystemCapability.MiscServices.Pasteboard 39 40| Type| Description| 41| -------- | -------- | 42| string | The value is a string.| 43| image.PixelMap | The value is of the [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) type.| 44| Want | The value is of the [Want](../apis-ability-kit/js-apis-app-ability-want.md) type.| 45| ArrayBuffer | The value is of the **ArrayBuffer** type.| 46 47## pasteboard.createData<sup>9+</sup> 48 49createData(mimeType: string, value: ValueType): PasteData 50 51Creates a **PasteData** object of a custom type. 52 53**Atomic service API**: This API can be used in atomic services since API version 11. 54 55**System capability**: SystemCapability.MiscServices.Pasteboard 56 57**Parameters** 58 59| Name| Type| Mandatory| Description | 60| -------- | -------- | -------- |--------------------------------------------------------------------------------------------------------| 61| mimeType | string | Yes| MIME type of custom data. The value can a predefined MIME type listed in [Constants](#constants), including HTML, WANT, plain text, URI, and pixel map, or a custom MIME type. The value of **mimeType** cannot exceed 1024 bytes.| 62| value | [ValueType](#valuetype9) | Yes| Content of custom data. | 63 64**Return value** 65 66| Type| Description| 67| -------- | -------- | 68| [PasteData](#pastedata) | **PasteData** object.| 69 70**Error codes** 71 72For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 73 74| Error Code ID| Error Message| 75| -------- | -------- | 76| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 77 78**Example 1** 79 80 ```ts 81 let dataXml = new ArrayBuffer(256); 82 let pasteData: pasteboard.PasteData = pasteboard.createData('app/xml', dataXml); 83 ``` 84 85**Example 2** 86 87 ```ts 88 let dataText = 'hello'; 89 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, dataText); 90 ``` 91 92## pasteboard.createData<sup>14+</sup> 93 94createData(data: Record<string, ValueType>): PasteData 95 96Creates a **PasteData** object that contains multiple types of data. 97 98**System capability**: SystemCapability.MiscServices.Pasteboard 99 100**Parameters** 101 102| Name| Type | Mandatory| Description | 103| -------- |------------------------------------------------| -------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 104| data | Record<string, [ValueType](#valuetype9)> | Yes| The key of **Record** can be the MIME type corresponding to the pasteboard data, including HTML, WANT, plain text, URI, and PixelMap defined in [Constants](#constants). Alternatively, the key could be a custom MIME type, whose parameter, the length of **mimeType**, cannot exceed 1024 bytes.<br>The value of **Record** is the custom data corresponding to the MIME type specified in the key.<br>The first MIME type specified by the key-value in **Record** is used as the default MIME type of the first **PasteDataRecord** in the **PasteData** object. Data of non-default types can be read only by using the [getData](#getdata14) API.| 105 106**Return value** 107 108| Type| Description| 109| -------- | -------- | 110| [PasteData](#pastedata) | **PasteData** object.| 111 112**Error codes** 113 114For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 115 116| Error Code ID| Error Message| 117| -------- | -------- | 118| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 119 120**Example 1** 121 122```ts 123let pasteData: pasteboard.PasteData = pasteboard.createData({ 124 'text/plain': 'hello', 125 'app/xml': new ArrayBuffer(256), 126}); 127``` 128 129**Example 2** 130 131```ts 132let record: Record<string, pasteboard.ValueType> = {}; 133record[pasteboard.MIMETYPE_TEXT_PLAIN] = 'hello'; 134record[pasteboard.MIMETYPE_TEXT_URI] = 'dataability:///com.example.myapplication1/user.txt'; 135let pasteData: pasteboard.PasteData = pasteboard.createData(record); 136``` 137 138## pasteboard.createRecord<sup>9+</sup> 139 140createRecord(mimeType: string, value: ValueType):PasteDataRecord 141 142Creates a **PasteDataRecord** object of the custom type. 143 144**Atomic service API**: This API can be used in atomic services since API version 11. 145 146**System capability**: SystemCapability.MiscServices.Pasteboard 147 148**Parameters** 149 150| Name| Type| Mandatory| Description | 151| -------- | -------- | -------- |-------------------| 152| mimeType | string | Yes| MIME type of custom data. The value can a predefined MIME type listed in [Constants](#constants), including HTML, WANT, plain text, URI, and pixel map, or a custom MIME type. The value of **mimeType** cannot exceed 1024 bytes. | 153| value | [ValueType](#valuetype9) | Yes| Content of custom data. | 154 155**Return value** 156 157| Type| Description| 158| -------- | -------- | 159| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the custom type.| 160 161**Error codes** 162 163For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 164 165| Error Code ID| Error Message| 166| -------- | -------- | 167| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 168 169**Example 1** 170 171 ```ts 172let dataXml = new ArrayBuffer(256); 173let pasteDataRecord: pasteboard.PasteDataRecord = pasteboard.createRecord('app/xml', dataXml); 174 ``` 175 176**Example 2** 177 178 ```ts 179let dataUri = 'dataability:///com.example.myapplication1/user.txt'; 180let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, dataUri); 181 ``` 182 183## pasteboard.getSystemPasteboard 184 185getSystemPasteboard(): SystemPasteboard 186 187Obtains this **SystemPasteboard** object. 188 189**Atomic service API**: This API can be used in atomic services since API version 11. 190 191**System capability**: SystemCapability.MiscServices.Pasteboard 192 193**Return value** 194 195| Type| Description| 196| -------- | -------- | 197| [SystemPasteboard](#systempasteboard) | **SystemPasteboard** object.| 198 199**Example** 200 201```ts 202let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 203``` 204 205## ShareOption<sup>9+</sup> 206 207Enumerates the pasteable ranges of pasteboard data. 208 209**Atomic service API**: This API can be used in atomic services since API version 11. 210 211**System capability**: SystemCapability.MiscServices.Pasteboard 212 213| Name | Value | Description | 214| ---------------------------------- | --- | ------------------------------------------------------------------------------------- | 215| INAPP | 0 | Only intra-application pasting is allowed. | 216| LOCALDEVICE | 1 | Paste is allowed in any application on the local device. | 217| CROSSDEVICE<sup>(deprecated)</sup> | 2 | Paste is allowed in any application across devices.<br>This API has been deprecated since API Version 12. No alternative API or method is available. You can choose **Settings** > **Multi-Device Collaboration** > **Cross-Device Clipboard Switch** to set whether to allow cross-device pasting.| 218 219## pasteboard.createHtmlData<sup>(deprecated)</sup> 220 221createHtmlData(htmlText: string): PasteData 222 223Creates a **PasteData** object of the HTML type. 224> **NOTE** 225> 226> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 227 228**System capability**: SystemCapability.MiscServices.Pasteboard 229 230**Parameters** 231 232| Name| Type| Mandatory| Description| 233| -------- | -------- | -------- | -------- | 234| htmlText | string | Yes| HTML content.| 235 236**Return value** 237 238| Type| Description| 239| -------- | -------- | 240| [PasteData](#pastedata) | **PasteData** object.| 241 242**Example** 243 244```ts 245let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 246let pasteData: pasteboard.PasteData = pasteboard.createHtmlData(html); 247``` 248 249## pasteboard.createWantData<sup>(deprecated)</sup> 250 251createWantData(want: Want): PasteData 252 253Creates a **PasteData** object of the Want type. 254> **NOTE** 255> 256> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 257 258**System capability**: SystemCapability.MiscServices.Pasteboard 259 260**Parameters** 261 262| Name| Type| Mandatory| Description| 263| -------- | -------- | -------- | -------- | 264| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want content.| 265 266**Return value** 267 268| Type| Description| 269| -------- | -------- | 270| [PasteData](#pastedata) | **PasteData** object.| 271 272**Example** 273 274```ts 275import { Want } from '@kit.AbilityKit'; 276 277let object: Want = { 278 bundleName: "com.example.aafwk.test", 279 abilityName: "com.example.aafwk.test.TwoAbility" 280}; 281let pasteData: pasteboard.PasteData = pasteboard.createWantData(object); 282``` 283 284## pasteboard.createPlainTextData<sup>(deprecated)</sup> 285 286createPlainTextData(text: string): PasteData 287 288Creates a **PasteData** object of the plain text type. 289> **NOTE** 290> 291> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 292 293**System capability**: SystemCapability.MiscServices.Pasteboard 294 295**Parameters** 296 297| Name| Type| Mandatory| Description| 298| -------- | -------- | -------- | -------- | 299| text | string | Yes| Plain text.| 300 301**Return value** 302 303| Type| Description| 304| -------- | -------- | 305| [PasteData](#pastedata) | **PasteData** object.| 306 307**Example** 308 309```ts 310let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 311``` 312 313## pasteboard.createUriData<sup>(deprecated)</sup> 314 315createUriData(uri: string): PasteData 316 317Creates a **PasteData** object of the URI type. 318> **NOTE** 319> 320> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 321 322**System capability**: SystemCapability.MiscServices.Pasteboard 323 324**Parameters** 325 326| Name| Type| Mandatory| Description| 327| -------- | -------- | -------- | -------- | 328| uri | string | Yes| URI content.| 329 330**Return value** 331 332| Type| Description| 333| -------- | -------- | 334| [PasteData](#pastedata) | **PasteData** object.| 335 336**Example** 337 338```ts 339let pasteData: pasteboard.PasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); 340``` 341## pasteboard.createHtmlTextRecord<sup>(deprecated)</sup> 342 343createHtmlTextRecord(htmlText: string): PasteDataRecord 344 345Creates a **PasteDataRecord** object of the HTML text type. 346> **NOTE** 347> 348> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 349 350**System capability**: SystemCapability.MiscServices.Pasteboard 351 352**Parameters** 353 354| Name| Type| Mandatory| Description| 355| -------- | -------- | -------- | -------- | 356| htmlText | string | Yes| HTML content.| 357 358**Return value** 359 360| Type| Description| 361| -------- | -------- | 362| [PasteDataRecord](#pastedatarecord7) | **PasteDataRecord** object of the HTML text type.| 363 364**Example** 365 366```ts 367let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 368let record: pasteboard.PasteDataRecord = pasteboard.createHtmlTextRecord(html); 369``` 370 371## pasteboard.createWantRecord<sup>(deprecated)</sup> 372 373createWantRecord(want: Want): PasteDataRecord 374 375Creates a **PasteDataRecord** object of the Want type. 376> **NOTE** 377> 378> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 379 380**System capability**: SystemCapability.MiscServices.Pasteboard 381 382**Parameters** 383 384| Name| Type| Mandatory| Description| 385| -------- | -------- | -------- | -------- | 386| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want content.| 387 388**Return value** 389 390| Type| Description| 391| -------- | -------- | 392| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the Want type.| 393 394**Example** 395 396```ts 397import { Want } from '@kit.AbilityKit'; 398 399let object: Want = { 400 bundleName: "com.example.aafwk.test", 401 abilityName: "com.example.aafwk.test.TwoAbility" 402}; 403let record: pasteboard.PasteDataRecord = pasteboard.createWantRecord(object); 404``` 405 406## pasteboard.createPlainTextRecord<sup>(deprecated)</sup> 407 408createPlainTextRecord(text: string): PasteDataRecord 409 410Creates a **PasteDataRecord** object of the plain text type. 411> **NOTE** 412> 413> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 414 415**System capability**: SystemCapability.MiscServices.Pasteboard 416 417**Parameters** 418 419| Name| Type| Mandatory| Description| 420| -------- | -------- | -------- | -------- | 421| text | string | Yes| Plain text.| 422 423**Return value** 424 425| Type| Description| 426| -------- | -------- | 427| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the plain text type.| 428 429**Example** 430 431```ts 432let record: pasteboard.PasteDataRecord = pasteboard.createPlainTextRecord('hello'); 433``` 434 435## pasteboard.createUriRecord<sup>(deprecated)</sup> 436 437createUriRecord(uri: string): PasteDataRecord 438 439Creates a **PasteDataRecord** object of the URI type. 440> **NOTE** 441> 442> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 443 444**System capability**: SystemCapability.MiscServices.Pasteboard 445 446**Parameters** 447 448| Name| Type| Mandatory| Description| 449| -------- | -------- | -------- | -------- | 450| uri | string | Yes| URI content.| 451 452**Return value** 453 454| Type| Description| 455| -------- | -------- | 456| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the URI type.| 457 458**Example** 459 460```ts 461let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 462``` 463 464 465## PasteDataProperty<sup>7+</sup> 466 467Defines the properties of all data records on the pasteboard, including the timestamp, data type, and additional data. 468The defined properties can be applied to the pasteboard only with the [setProperty](#setproperty9) API. 469 470**Atomic service API**: This API can be used in atomic services since API version 11. 471 472**System capability**: SystemCapability.MiscServices.Pasteboard 473 474| Name| Type| Readable| Writable| Description | 475| -------- | -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 476| additions<sup>7+</sup> | {[key:string]:object} | Yes| Yes| Additional data. It does not allow for dynamic adding of attributes. Attributes can be added only by re-assigning values. For details, see the example of **setProperty**. | 477| mimeTypes<sup>7+</sup> | Array<string> | Yes| No| Non-repeating data types of the data records on the pasteboard. | 478| tag<sup>7+</sup> | string | Yes| Yes| Custom tag. | 479| timestamp<sup>7+</sup> | number | Yes| No| Timestamp when data is written to the pasteboard (unit: ms). | 480| localOnly<sup>7+</sup> | boolean | Yes| Yes| Whether the pasteboard content is for local access only. The default value is **false**. The value will be overwritten by the value of the **shareOption** attribute. You are advised to use the **shareOption** attribute instead. **ShareOption.INAPP** and **ShareOption.LOCALDEVICE** set **localOnly** to **true**, and **ShareOption.CROSSDEVICE** sets **localOnly** to false.<br>- **true**: The pasteboard content is set for local access only.<br>- **false**: The pasteboard content can be shared between devices.| 481| shareOption<sup>9+</sup> | [ShareOption](#shareoption9) | Yes| Yes| Where the pasteboard content can be pasted. If this attribute is set incorrectly or not set, the default value **CROSSDEVICE** is used. | 482 483## FileConflictOptions<sup>15+</sup> 484 485Defines options for file copy conflicts. 486 487**Atomic service API**: This API can be used in atomic services since API version 15. 488 489**System capability**: SystemCapability.MiscServices.Pasteboard 490 491| Name | Value | Description | 492| --------- | ---- | ------------------------------------------------------------ | 493| OVERWRITE | 0 | Overwrites the file with the same name in the destination path. | 494| SKIP | 1 | Skips the file with the same name in the destination path. If **SKIP** is set, the copied data of the skipped file is not pasted to the application.| 495 496## ProgressIndicator<sup>15+</sup> 497 498Defines options for the progress indicator. You can choose whether to use the default progress indicator. 499 500**Atomic service API**: This API can be used in atomic services since API version 15. 501 502**System capability**: SystemCapability.MiscServices.Pasteboard 503 504| Name | Value | Description | 505| ------- | ---- | ------------------------ | 506| NONE | 0 | The default progress indicator is not used.| 507| DEFAULT | 1 | The default progress indicator is used. | 508 509## ProgressInfo<sup>15+</sup> 510 511Defines the progress information. This information is reported only when [ProgressIndicator](#progressindicator15) is set to **NONE**. 512 513**Atomic service API**: This API can be used in atomic services since API version 15. 514 515**System capability**: SystemCapability.MiscServices.Pasteboard 516 517| Name | Type | Readable| Writable| Description | 518| -------- | ------ | ---- | ---- | ---------------------------------------------------------- | 519| progress | number | Yes | No | If the progress indicator provided by the system is not used, the system reports the progress percentage of the copy-and-paste task.| 520 521## ProgressListener<sup>15+</sup> 522 523type ProgressListener = (progress: ProgressInfo) => void 524 525Defines a listener for progress data changes. If the default progress indicator is not used, you can set this API to obtain the paste progress. 526 527**Atomic service API**: This API can be used in atomic services since API version 15. 528 529**System capability**: SystemCapability.MiscServices.Pasteboard 530 531| Name | Type | Mandatory| Description | 532| -------- | ------------------------------- | ---- | ------------------------------------------------------------ | 533| progress | [ProgressInfo](#progressinfo15) | Yes | Defines the progress information. This information is reported only when [ProgressIndicator](#progressindicator15) is set to **NONE**.| 534 535## ProgressSignal<sup>15+</sup> 536 537Defines a function for canceling the paste task. This parameter is valid only when [ProgressIndicator](#progressindicator15) is set to **NONE**. 538 539**System capability**: SystemCapability.MiscServices.Pasteboard 540 541### cancel 542 543cancel(): void 544 545Cancels an ongoing copy-and-paste task. 546 547**Atomic service API**: This API can be used in atomic services since API version 15. 548 549**System capability**: SystemCapability.MiscServices.Pasteboard 550 551**Example** 552 553```ts 554import { BusinessError, pasteboard } from '@kit.BasicServicesKit'; 555@Entry 556@Component 557struct PasteboardTest { 558 build() { 559 RelativeContainer() { 560 Column() { 561 Column() { 562 Button("Copy txt") 563 .onClick(async ()=>{ 564 let text = "test"; 565 let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, text); 566 let systemPasteboard = pasteboard.getSystemPasteboard(); 567 await systemPasteboard.setData(pasteData); 568 let signal = new pasteboard.ProgressSignal; 569 let ProgressListener = (progress: pasteboard.ProgressInfo) => { 570 console.log('progressListener success, progress:' + progress.progress); 571 signal.cancel(); 572 } 573 let params: pasteboard.GetDataParams = { 574 destUri: '/data/storage/el2/base/haps/entry/files/dstFile.txt', 575 fileConflictOptions: pasteboard.FileConflictOptions.OVERWRITE, 576 progressIndicator: pasteboard.ProgressIndicator.DEFAULT, 577 progressListener: ProgressListener 578 }; 579 systemPasteboard.getDataWithProgress(params).then((pasteData: pasteboard.PasteData) => { 580 console.error('getDataWithProgress succ'); 581 }).catch((err: BusinessError) => { 582 console.error('Failed to get PasteData. Cause: ' + err.message); 583 }) 584 }) 585 } 586 } 587 } 588 } 589} 590``` 591 592## GetDataParams<sup>15+</sup> 593 594Obtains parameters when an application uses the file copy capability provided by the pasteboard, including the destination path, file conflict options, and progress indicator types. 595 596**Atomic service API**: This API can be used in atomic services since API version 15. 597 598**System capability**: SystemCapability.MiscServices.Pasteboard 599 600| Name | Type | Mandatory| Description | 601| ------------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 602| destUri | string | No | Destination path for copying files. If file processing is not supported, this parameter is not required. If the application involves complex file processing policies or needs to distinguish file multipathing storage, you are advised not to set this parameter but let the application copies files by itself.| 603| fileConflictOptions | [FileConflictOptions](#fileconflictoptions15) | No | File conflict options for a copy-and-paste task. The default value is **OVERWRITE**. | 604| progressIndicator | [ProgressIndicator](#progressindicator15) | Yes | Progress indicator options. You can choose whether to use the default progress indicator. | 605| progressListener | [ProgressListener](#progresslistener15) | No | Listener for progress data changes. If the default progress indicator is not used, you can set this parameter to obtain the paste progress.| 606| progressSignal | [ProgressSignal](#progresssignal15) | No | Function for canceling the paste task. This parameter is valid only when [ProgressIndicator](#progressindicator15) is set to **NONE**.| 607 608## PasteDataRecord<sup>7+</sup> 609 610Provides **PasteDataRecord** APIs. A **PasteDataRecord** is an abstract definition of the content on the pasteboard. The pasteboard content consists of one or more plain text, HTML, URI, or Want records. 611 612### Attributes 613 614**Atomic service API**: This API can be used in atomic services since API version 11. 615 616**System capability**: SystemCapability.MiscServices.Pasteboard 617 618| Name| Type| Readable| Writable| Description| 619| -------- | -------- | -------- | -------- | -------- | 620| htmlText<sup>7+</sup> | string | Yes| No| HTML content.| 621| want<sup>7+</sup> | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| No| Want content.| 622| mimeType<sup>7+</sup> | string | Yes| No| Data type.| 623| plainText<sup>7+</sup> | string | Yes| No| Plain text.| 624| uri<sup>7+</sup> | string | Yes| No| URI content.| 625| pixelMap<sup>9+</sup> | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes| No| Pixel map.| 626| data<sup>9+</sup> | {[mimeType: string]: ArrayBuffer} | Yes| No| Content of custom data.| 627 628### toPlainText<sup>9+</sup> 629 630toPlainText(): string 631 632Forcibly converts HTML, plain, and URI content in a **PasteDataRecord** to the plain text. 633 634**Atomic service API**: This API can be used in atomic services since API version 11. 635 636**System capability**: SystemCapability.MiscServices.Pasteboard 637 638**Return value** 639 640| Type| Description| 641| -------- | -------- | 642| string | Plain text.| 643 644**Example** 645 646```ts 647let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 648let data: string = record.toPlainText(); 649console.info(`Succeeded in converting to text. Data: ${data}`); 650``` 651 652### addEntry<sup>14+</sup> 653 654addEntry(type: string, value: ValueType): void 655 656Adds custom data of an extra type to **PasteDataRecord**. The MIME type added using this method is not the default type of **Record**. You can only use the [getData](#getdata14) API to read the corresponding data. 657 658**System capability**: SystemCapability.MiscServices.Pasteboard 659 660**Parameters** 661 662| Name | Type| Mandatory| Description | 663|-------| -------- | -------- |-------------------| 664| type | string | Yes| MIME type of custom data. The value can a predefined MIME type listed in [Constants](#constants), including HTML, WANT, plain text, URI, and pixel map, or a custom MIME type. The value of **mimeType** cannot exceed 1024 bytes. | 665| value | [ValueType](#valuetype9) | Yes| Content of custom data. | 666 667**Error codes** 668 669For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 670 671| Error Code ID| Error Message| 672| -------- | -------- | 673| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 674 675**Example** 676 677```ts 678let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 679let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 680record.addEntry(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 681record.addEntry(pasteboard.MIMETYPE_TEXT_HTML, html); 682``` 683 684### getValidTypes<sup>14+</sup> 685 686getValidTypes(types: Array<string>): Array<string> 687 688Obtains the intersection of the input MIME type and the MIME type of the pasteboard data. 689 690**System capability**: SystemCapability.MiscServices.Pasteboard 691 692**Parameters** 693 694| Name | Type| Mandatory| Description | 695|-------| -------- | -------- |----------------| 696| types | Array<string> | Yes| List of the MIME types.| 697 698**Return value** 699 700| Type| Description | 701| -------- |--------------------------------------| 702| Array<string> | Intersection of the input MIME type and the MIME type of the pasteboard data obtained.| 703 704**Error codes** 705 706For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 707 708| Error Code ID| Error Message| 709| -------- | -------- | 710| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 711 712**Example** 713 714```ts 715let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 716let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 717record.addEntry(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 718record.addEntry(pasteboard.MIMETYPE_TEXT_HTML, html); 719let types: string[] = record.getValidTypes([ 720 pasteboard.MIMETYPE_TEXT_PLAIN, 721 pasteboard.MIMETYPE_TEXT_HTML, 722 pasteboard.MIMETYPE_TEXT_URI, 723 pasteboard.MIMETYPE_TEXT_WANT, 724 pasteboard.MIMETYPE_PIXELMAP 725]); 726``` 727 728### getData<sup>14+</sup> 729 730getData(type: string): Promise<ValueType> 731 732Obtains custom data of the specified MIME type from **PasteDataRecord**. 733 734**System capability**: SystemCapability.MiscServices.Pasteboard 735 736**Parameters** 737 738| Name | Type |Mandatory| Description | 739|------|--------|-------- |----------| 740| type | string |Yes| MIME type.| 741 742**Return value** 743 744| Type | Description | 745|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------| 746| Promise<[ValueType](#valuetype9)> | Promise used to return the custom data of the specified MIME type.<br>If **PasteDataRecord** contains data of multiple MIME types, the non-**PasteDataRecord** data of the default MIME type can be obtained only through this API.| 747 748**Error codes** 749 750For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 751 752| Error Code ID| Error Message| 753| -------- | -------- | 754| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 755 756**Example** 757 758```ts 759import { BusinessError } from '@kit.BasicServicesKit'; 760 761let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 762let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 763record.addEntry(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 764record.addEntry(pasteboard.MIMETYPE_TEXT_HTML, html); 765record.getData(pasteboard.MIMETYPE_TEXT_PLAIN).then((value: pasteboard.ValueType) => { 766 let textPlainContent = value as string; 767 console.info('Success to get text/plain value. value is: ' + textPlainContent); 768}).catch((err: BusinessError) => { 769 console.error('Failed to get text/plain value. Cause: ' + err.message); 770}); 771record.getData(pasteboard.MIMETYPE_TEXT_URI).then((value: pasteboard.ValueType) => { 772 let uri = value as string; 773 console.info('Success to get text/uri value. value is: ' + uri); 774}).catch((err: BusinessError) => { 775 console.error('Failed to get text/uri value. Cause: ' + err.message); 776}); 777``` 778 779### convertToText<sup>(deprecated)</sup> 780 781convertToText(callback: AsyncCallback<string>): void 782 783Forcibly converts the content in a **PasteData** object to text. This API uses an asynchronous callback to return the result. 784> **NOTE** 785> 786> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). 787 788**System capability**: SystemCapability.MiscServices.Pasteboard 789 790**Parameters** 791 792| Name| Type| Mandatory| Description| 793| -------- | -------- | -------- | -------- | 794| callback | AsyncCallback<string> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the text obtained from the conversion. Otherwise, **err** is error information.| 795 796**Error codes** 797 798For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 799 800| Error Code ID| Error Message| 801| -------- | -------- | 802| 401 | Possible causes: Incorrect parameters types. | 803 804**Example** 805 806```ts 807import { BusinessError } from '@kit.BasicServicesKit'; 808 809let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 810record.convertToText((err: BusinessError, data: string) => { 811 if (err) { 812 console.error(`Failed to convert to text. Cause: ${err.message}`); 813 return; 814 } 815 console.info(`Succeeded in converting to text. Data: ${data}`); 816}); 817``` 818 819### convertToText<sup>(deprecated)</sup> 820 821convertToText(): Promise<string> 822 823Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result. 824> **NOTE** 825> 826> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). 827 828**System capability**: SystemCapability.MiscServices.Pasteboard 829 830**Return value** 831 832| Type| Description| 833| -------- | -------- | 834| Promise<string> | Promise used to return the text obtained from the conversion.| 835 836**Example** 837 838```ts 839import { BusinessError } from '@kit.BasicServicesKit'; 840 841let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 842record.convertToText().then((data: string) => { 843 console.info(`Succeeded in converting to text. Data: ${data}`); 844}).catch((err: BusinessError) => { 845 console.error(`Failed to convert to text. Cause: ${err.message}`); 846}); 847``` 848 849## PasteData 850 851Implements a **PasteData** object. Paste data contains one or more data records ([PasteDataRecord](#pastedatarecord7)) and property description objects ([PasteDataProperty](#pastedataproperty7)). 852 853Before calling any API in **PasteData**, you must use **[createData()](#pasteboardcreatedata9)** or **[getData()](#getdata9)** to create a **PasteData** object. 854 855**System capability**: SystemCapability.MiscServices.Pasteboard 856 857### getPrimaryText 858 859getPrimaryText(): string 860 861Obtains the plain text of the primary record. 862 863**Atomic service API**: This API can be used in atomic services since API version 11. 864 865**System capability**: SystemCapability.MiscServices.Pasteboard 866 867**Return value** 868 869| Type| Description| 870| -------- | -------- | 871| string | Plain text.| 872 873**Example** 874 875```ts 876let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 877let plainText: string = pasteData.getPrimaryText(); 878``` 879 880### getPrimaryHtml<sup>7+</sup> 881 882getPrimaryHtml(): string 883 884Obtains the HTML content of the primary record. 885 886**Atomic service API**: This API can be used in atomic services since API version 11. 887 888**System capability**: SystemCapability.MiscServices.Pasteboard 889 890**Return value** 891 892| Type| Description| 893| -------- | -------- | 894| string | HTML content.| 895 896**Example** 897 898```ts 899let html = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 900let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, html); 901let htmlText: string = pasteData.getPrimaryHtml(); 902``` 903 904### getPrimaryWant<sup>7+</sup> 905 906getPrimaryWant(): Want 907 908Obtains the Want object of the primary record. 909 910**Atomic service API**: This API can be used in atomic services since API version 11. 911 912**System capability**: SystemCapability.MiscServices.Pasteboard 913 914**Return value** 915 916| Type| Description| 917| -------- | -------- | 918| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Want object.| 919 920**Example** 921 922```ts 923import { Want } from '@kit.AbilityKit'; 924 925let object: Want = { 926 bundleName: "com.example.aafwk.test", 927 abilityName: "com.example.aafwk.test.TwoAbility" 928}; 929let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_WANT, object); 930let want: Want = pasteData.getPrimaryWant(); 931``` 932 933### getPrimaryUri<sup>7+</sup> 934 935getPrimaryUri(): string 936 937Obtains the URI of the primary record. 938 939**Atomic service API**: This API can be used in atomic services since API version 11. 940 941**System capability**: SystemCapability.MiscServices.Pasteboard 942 943**Return value** 944 945| Type| Description| 946| -------- | -------- | 947| string | URI content.| 948 949**Example** 950 951```ts 952let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 953let uri: string = pasteData.getPrimaryUri(); 954``` 955 956### getPrimaryPixelMap<sup>9+</sup> 957 958getPrimaryPixelMap(): image.PixelMap 959 960Obtains the pixel map of the primary record. 961 962**Atomic service API**: This API can be used in atomic services since API version 11. 963 964**System capability**: SystemCapability.MiscServices.Pasteboard 965 966**Return value** 967 968| Type| Description| 969| -------- | -------- | 970| [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Pixel map.| 971 972**Example** 973 974```ts 975import { image } from '@kit.ImageKit'; 976 977let buffer = new ArrayBuffer(128); 978let realSize: image.Size = { height: 3, width: 5 }; 979let opt: image.InitializationOptions = { 980 size: realSize, 981 pixelFormat: 3, 982 editable: true, 983 alphaType: 1, 984 scaleMode: 1 985}; 986image.createPixelMap(buffer, opt).then((pixelMap: image.PixelMap) => { 987 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP, pixelMap); 988 let PixelMap: image.PixelMap = pasteData.getPrimaryPixelMap(); 989}); 990``` 991 992### addRecord<sup>7+</sup> 993 994addRecord(record: PasteDataRecord): void 995 996Adds a data record to this pasteboard, and adds its type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 997 998**Atomic service API**: This API can be used in atomic services since API version 11. 999 1000**System capability**: SystemCapability.MiscServices.Pasteboard 1001 1002**Parameters** 1003 1004| Name| Type| Mandatory| Description| 1005| -------- | -------- | -------- | -------- | 1006| record | [PasteDataRecord](#pastedatarecord7) | Yes| Record to add.| 1007 1008**Example** 1009 1010```ts 1011let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 1012let textRecord: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1013let html: string = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 1014let htmlRecord: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_HTML, html); 1015pasteData.addRecord(textRecord); 1016pasteData.addRecord(htmlRecord); 1017``` 1018### addRecord<sup>9+</sup> 1019 1020addRecord(mimeType: string, value: ValueType): void 1021 1022Adds a custom-type record to this pasteboard, and adds the custom type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 1023 1024**Atomic service API**: This API can be used in atomic services since API version 11. 1025 1026**System capability**: SystemCapability.MiscServices.Pasteboard 1027 1028**Parameters** 1029 1030| Name| Type| Mandatory| Description| 1031| -------- | -------- | -------- | -------- | 1032| mimeType | string | Yes| MIME type of custom data. The length cannot exceed 1024 bytes.| 1033| value | [ValueType](#valuetype9) | Yes| Content of custom data.| 1034 1035**Error codes** 1036 1037For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1038 1039| Error Code ID| Error Message| 1040| -------- | -------- | 1041| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1042 1043**Example** 1044 1045 ```ts 1046 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 1047 let dataXml = new ArrayBuffer(256); 1048 pasteData.addRecord('app/xml', dataXml); 1049 ``` 1050 1051### getMimeTypes<sup>7+</sup> 1052 1053getMimeTypes(): Array<string> 1054 1055Obtains a list of **mimeTypes** objects in [PasteDataProperty](#pastedataproperty7) from this pasteboard. If the pasteboard is empty, the returned list is also empty. 1056 1057**Atomic service API**: This API can be used in atomic services since API version 11. 1058 1059**System capability**: SystemCapability.MiscServices.Pasteboard 1060 1061**Return value** 1062 1063| Type| Description| 1064| -------- | -------- | 1065| Array<string> | Non-repeating data types of the data records on the pasteboard.| 1066 1067**Example** 1068 1069```ts 1070let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1071let types: string[] = pasteData.getMimeTypes(); 1072``` 1073 1074### getPrimaryMimeType<sup>7+</sup> 1075 1076getPrimaryMimeType(): string 1077 1078Obtains the data type of the primary record in this pasteboard. 1079 1080**Atomic service API**: This API can be used in atomic services since API version 11. 1081 1082**System capability**: SystemCapability.MiscServices.Pasteboard 1083 1084**Return value** 1085 1086| Type| Description| 1087| -------- | -------- | 1088| string | Data type of the primary record.| 1089 1090**Example** 1091 1092```ts 1093let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1094let type: string = pasteData.getPrimaryMimeType(); 1095``` 1096 1097### getProperty<sup>7+</sup> 1098 1099getProperty(): PasteDataProperty 1100 1101Obtains the property of the pasteboard data. 1102 1103**Atomic service API**: This API can be used in atomic services since API version 11. 1104 1105**System capability**: SystemCapability.MiscServices.Pasteboard 1106 1107**Return value** 1108 1109| Type| Description| 1110| -------- | -------- | 1111| [PasteDataProperty](#pastedataproperty7) | Property of the pasteboard data.| 1112 1113**Example** 1114 1115```ts 1116let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1117let property: pasteboard.PasteDataProperty = pasteData.getProperty(); 1118``` 1119 1120### setProperty<sup>9+</sup> 1121 1122setProperty(property: PasteDataProperty): void 1123 1124Sets a [PasteDataProperty](#pastedataproperty7) object. 1125 1126**Atomic service API**: This API can be used in atomic services since API version 11. 1127 1128**System capability**: SystemCapability.MiscServices.Pasteboard 1129 1130**Parameters** 1131 1132| Name| Type| Mandatory| Description| 1133| -------- | -------- | -------- | -------- | 1134| property | [PasteDataProperty](#pastedataproperty7) | Yes| Property of the pasteboard data.| 1135 1136**Error codes** 1137 1138For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1139 1140| Error Code ID| Error Message| 1141| -------- | -------- | 1142| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1143 1144**Example** 1145 1146```ts 1147type AdditionType = Record<string, Record<string, Object>>; 1148 1149let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml'); 1150let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 1151prop.shareOption = pasteboard.ShareOption.INAPP; 1152// Note that attributes cannot be added to additions. Attributes can be added only by re-assigning values. 1153prop.additions = { 'TestOne': { 'Test': 123 }, 'TestTwo': { 'Test': 'additions' } } as AdditionType; 1154prop.tag = 'TestTag'; 1155pasteData.setProperty(prop); 1156``` 1157The **localOnly** and **shareOption** attributes of [PasteDataProperty](#pastedataproperty7) are mutually exclusive. The **shareOption** attribute is prioritized, and its value affects the value of **localOnly**. 1158```ts 1159(async () => { 1160 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1161 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 1162 prop.shareOption = pasteboard.ShareOption.INAPP; 1163 prop.localOnly = false; 1164 pasteData.setProperty(prop); 1165 let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1166 1167 await systemPasteboard.setData(pasteData).then(async () => { 1168 console.info('Succeeded in setting PasteData.'); 1169 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 1170 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 1171 prop.localOnly; // true 1172 }); 1173 }); 1174 1175 prop.shareOption = pasteboard.ShareOption.LOCALDEVICE; 1176 prop.localOnly = false; 1177 pasteData.setProperty(prop); 1178 1179 await systemPasteboard.setData(pasteData).then(async () => { 1180 console.info('Succeeded in setting PasteData.'); 1181 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 1182 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 1183 prop.localOnly; // true 1184 }); 1185 }); 1186 1187 prop.shareOption = pasteboard.ShareOption.CROSSDEVICE; 1188 prop.localOnly = true; 1189 pasteData.setProperty(prop); 1190 1191 await systemPasteboard.setData(pasteData).then(async () => { 1192 console.info('Succeeded in setting PasteData.'); 1193 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 1194 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 1195 prop.localOnly; // false 1196 }); 1197 }); 1198})() 1199``` 1200 1201### getRecord<sup>9+</sup> 1202 1203getRecord(index: number): PasteDataRecord 1204 1205Obtains the record with a specific index from the pasteboard. 1206 1207**Atomic service API**: This API can be used in atomic services since API version 11. 1208 1209**System capability**: SystemCapability.MiscServices.Pasteboard 1210 1211**Parameters** 1212 1213| Name| Type| Mandatory| Description| 1214| -------- | -------- | -------- | -------- | 1215| index | number | Yes| Index of the target record.| 1216 1217**Return value** 1218 1219| Type| Description| 1220| -------- | -------- | 1221| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| 1222 1223**Error codes** 1224 1225For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1226 1227| Error Code ID| Error Message| 1228| -------- | -------- | 1229| 12900001 | The index is out of the record. | 1230| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1231 1232**Example** 1233 1234```ts 1235let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1236let record: pasteboard.PasteDataRecord = pasteData.getRecord(0); 1237``` 1238 1239### getRecordCount<sup>7+</sup> 1240 1241getRecordCount(): number 1242 1243Obtains the number of records in the pasteboard. 1244 1245**Atomic service API**: This API can be used in atomic services since API version 11. 1246 1247**System capability**: SystemCapability.MiscServices.Pasteboard 1248 1249**Return value** 1250 1251| Type| Description| 1252| -------- | -------- | 1253| number | Number of records.| 1254 1255**Example** 1256 1257```ts 1258let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1259let count: number = pasteData.getRecordCount(); 1260``` 1261 1262### getTag<sup>7+</sup> 1263 1264getTag(): string 1265 1266Obtains the custom tag from the pasteboard. If no custom tag is set, null is returned. 1267 1268**Atomic service API**: This API can be used in atomic services since API version 11. 1269 1270**System capability**: SystemCapability.MiscServices.Pasteboard 1271 1272**Return value** 1273 1274| Type| Description| 1275| -------- | -------- | 1276| string | Custom tag. If no custom tag is set, null is returned.| 1277 1278**Example** 1279 1280```ts 1281let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1282let tag: string = pasteData.getTag(); 1283``` 1284 1285### hasType<sup>9+</sup> 1286 1287hasType(mimeType: string): boolean 1288 1289Checks whether the pasteboard contains data of the specified type. 1290 1291**Atomic service API**: This API can be used in atomic services since API version 11. 1292 1293**System capability**: SystemCapability.MiscServices.Pasteboard 1294 1295**Parameters** 1296 1297| Name| Type| Mandatory| Description| 1298| -------- | -------- | -------- | -------- | 1299| mimeType | string | Yes| Type of the data to query.| 1300 1301**Return value** 1302 1303| Type| Description| 1304| -------- | -------- | 1305| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.| 1306 1307**Error codes** 1308 1309For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1310 1311| Error Code ID| Error Message| 1312| -------- | -------- | 1313| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1314 1315**Example** 1316 1317```ts 1318let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1319let hasType: boolean = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); 1320``` 1321 1322### removeRecord<sup>9+</sup> 1323 1324removeRecord(index: number): void 1325 1326Removes the record with a specific index from the pasteboard. 1327 1328**Atomic service API**: This API can be used in atomic services since API version 11. 1329 1330**System capability**: SystemCapability.MiscServices.Pasteboard 1331 1332**Parameters** 1333 1334| Name| Type| Mandatory| Description| 1335| -------- | -------- | -------- | -------- | 1336| index | number | Yes| Specified index.| 1337 1338**Error codes** 1339 1340For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1341 1342| Error Code ID| Error Message| 1343| -------- | -------- | 1344| 12900001 | The index is out of the record. | 1345| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1346 1347**Example** 1348 1349```ts 1350let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1351pasteData.removeRecord(0); 1352``` 1353 1354### replaceRecord<sup>9+</sup> 1355 1356replaceRecord(index: number, record: PasteDataRecord): void 1357 1358Replaces the record with a specific index from the pasteboard. 1359 1360**Atomic service API**: This API can be used in atomic services since API version 11. 1361 1362**System capability**: SystemCapability.MiscServices.Pasteboard 1363 1364**Parameters** 1365 1366| Name| Type| Mandatory| Description| 1367| -------- | -------- | -------- | -------- | 1368| index | number | Yes| Specified index.| 1369| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| 1370 1371**Error codes** 1372 1373For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1374 1375| Error Code ID| Error Message| 1376| -------- | -------- | 1377| 12900001 | The index is out of the record. | 1378| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1379 1380**Example** 1381 1382```ts 1383let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1384let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 1385pasteData.replaceRecord(0, record); 1386``` 1387 1388### pasteStart<sup>12+</sup> 1389 1390pasteStart(): void 1391 1392Notifies the clipboard service to retain the cross-device channel before reading data from the clipboard. 1393 1394**System capability**: SystemCapability.MiscServices.Pasteboard 1395 1396**Example** 1397 1398```ts 1399import { BusinessError } from '@kit.BasicServicesKit'; 1400 1401let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1402systemPasteboard.getData((err: BusinessError, pasteData: pasteboard.PasteData) => { 1403 if (err) { 1404 console.error('Failed to get PasteData. Cause: ' + err.message); 1405 return; 1406 } 1407 pasteData.pasteStart(); 1408 console.log(`using data: ${pasteData.getPrimaryText()}`); 1409 pasteData.pasteComplete(); 1410}); 1411``` 1412 1413### pasteComplete<sup>12+</sup> 1414 1415pasteComplete(): void 1416 1417Notifies the clipboard service that the paste is complete. 1418 1419**System capability**: SystemCapability.MiscServices.Pasteboard 1420 1421**Example** 1422 1423```ts 1424import { BusinessError } from '@kit.BasicServicesKit'; 1425 1426let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1427systemPasteboard.getData((err: BusinessError, pasteData: pasteboard.PasteData) => { 1428 if (err) { 1429 console.error('Failed to get PasteData. Cause: ' + err.message); 1430 return; 1431 } 1432 pasteData.pasteStart(); 1433 console.log(`using data: ${pasteData.getPrimaryText()}`); 1434 pasteData.pasteComplete(); 1435}); 1436``` 1437 1438### addHtmlRecord<sup>(deprecated)</sup> 1439 1440addHtmlRecord(htmlText: string): void 1441 1442Adds an HTML record to this pasteboard, and adds **MIMETYPE_TEXT_HTML** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 1443 1444> **NOTE** 1445> 1446> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1447 1448**System capability**: SystemCapability.MiscServices.Pasteboard 1449 1450**Parameters** 1451 1452| Name| Type| Mandatory| Description| 1453| -------- | -------- | -------- | -------- | 1454| htmlText | string | Yes| HTML content.| 1455 1456**Example** 1457 1458```ts 1459let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1460let html: string = "<!DOCTYPE html>\n" + "<html>\n" + "<head>\n" + "<meta charset=\"utf-8\">\n" + "<title>HTML-PASTEBOARD_HTML</title>\n" + "</head>\n" + "<body>\n" + " <h1>HEAD</h1>\n" + " <p></p>\n" + "</body>\n" + "</html>"; 1461pasteData.addHtmlRecord(html); 1462``` 1463 1464### addWantRecord<sup>(deprecated)</sup> 1465 1466addWantRecord(want: Want): void 1467 1468Adds a Want record to this pasteboard, and adds **MIMETYPE_TEXT_WANT** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 1469 1470> **NOTE** 1471> 1472> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1473 1474**System capability**: SystemCapability.MiscServices.Pasteboard 1475 1476**Parameters** 1477 1478| Name| Type| Mandatory| Description| 1479| -------- | -------- | -------- | -------- | 1480| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want object.| 1481 1482**Example** 1483 1484```ts 1485import { Want } from '@kit.AbilityKit'; 1486 1487let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1488let object: Want = { 1489 bundleName: "com.example.aafwk.test", 1490 abilityName: "com.example.aafwk.test.TwoAbility" 1491}; 1492pasteData.addWantRecord(object); 1493``` 1494 1495### addTextRecord<sup>(deprecated)</sup> 1496 1497addTextRecord(text: string): void 1498 1499Adds a plain text record to this pasteboard, and adds **MIME_TEXT_PLAIN** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 1500 1501> **NOTE** 1502> 1503> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1504 1505**System capability**: SystemCapability.MiscServices.Pasteboard 1506 1507**Parameters** 1508 1509| Name| Type| Mandatory| Description| 1510| -------- | -------- | -------- | -------- | 1511| text | string | Yes| Plain text.| 1512 1513**Example** 1514 1515```ts 1516let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1517pasteData.addTextRecord('good'); 1518``` 1519 1520### addUriRecord<sup>(deprecated)</sup> 1521 1522addUriRecord(uri: string): void 1523 1524Adds a URI record to this pasteboard, and adds **MIMETYPE_TEXT_URI** to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 1525 1526> **NOTE** 1527> 1528> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1529 1530**System capability**: SystemCapability.MiscServices.Pasteboard 1531 1532**Parameters** 1533 1534| Name| Type| Mandatory| Description| 1535| -------- | -------- | -------- | -------- | 1536| uri | string | Yes| URI content.| 1537 1538**Example** 1539 1540```ts 1541let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1542pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt'); 1543``` 1544### getRecordAt<sup>(deprecated)</sup> 1545 1546getRecordAt(index: number): PasteDataRecord 1547 1548Obtains the record with a specific index from the pasteboard. 1549> **NOTE** 1550> 1551> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRecord](#getrecord9). 1552 1553**System capability**: SystemCapability.MiscServices.Pasteboard 1554 1555**Parameters** 1556 1557| Name| Type| Mandatory| Description| 1558| -------- | -------- | -------- | -------- | 1559| index | number | Yes| Index of the target record.| 1560 1561**Return value** 1562 1563| Type| Description| 1564| -------- | -------- | 1565| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| 1566 1567**Error codes** 1568 1569For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1570 1571| Error Code ID| Error Message| 1572| -------- | -------- | 1573| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1574 1575**Example** 1576 1577```ts 1578let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1579let record: pasteboard.PasteDataRecord = pasteData.getRecordAt(0); 1580``` 1581 1582### hasMimeType<sup>(deprecated)</sup> 1583 1584hasMimeType(mimeType: string): boolean 1585 1586Checks whether the pasteboard contains data of the specified type. 1587> **NOTE** 1588> 1589> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasType](#hastype9). 1590 1591**System capability**: SystemCapability.MiscServices.Pasteboard 1592 1593**Parameters** 1594 1595| Name| Type| Mandatory| Description| 1596| -------- | -------- | -------- | -------- | 1597| mimeType | string | Yes| Type of the data to query.| 1598 1599**Return value** 1600 1601| Type| Description| 1602| -------- | -------- | 1603| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.| 1604 1605**Error codes** 1606 1607For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1608 1609| Error Code ID| Error Message| 1610| -------- | -------- | 1611| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1612 1613**Example** 1614 1615```ts 1616let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1617let hasType: boolean = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); 1618``` 1619### removeRecordAt<sup>(deprecated)</sup> 1620 1621removeRecordAt(index: number): boolean 1622 1623Removes the record with a specific index from the pasteboard. 1624> **NOTE** 1625> 1626> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [removeRecord](#removerecord9). 1627 1628**System capability**: SystemCapability.MiscServices.Pasteboard 1629 1630**Parameters** 1631 1632| Name| Type| Mandatory| Description| 1633| -------- | -------- | -------- | -------- | 1634| index | number | Yes| Specified index.| 1635 1636**Return value** 1637 1638| Type| Description| 1639| -------- | -------- | 1640| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1641 1642**Error codes** 1643 1644For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1645 1646| Error Code ID| Error Message| 1647| -------- | -------- | 1648| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1649 1650**Example** 1651 1652```ts 1653let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1654let isRemove: boolean = pasteData.removeRecordAt(0); 1655``` 1656### replaceRecordAt<sup>(deprecated)</sup> 1657 1658replaceRecordAt(index: number, record: PasteDataRecord): boolean 1659 1660Replaces the record with a specific index from the pasteboard. 1661> **NOTE** 1662> 1663> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [replaceRecord](#replacerecord9). 1664 1665**System capability**: SystemCapability.MiscServices.Pasteboard 1666 1667**Parameters** 1668 1669| Name| Type| Mandatory| Description| 1670| -------- | -------- | -------- | -------- | 1671| index | number | Yes| Specified index.| 1672| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| 1673 1674**Return value** 1675 1676| Type| Description| 1677| -------- | -------- | 1678| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1679 1680**Example** 1681 1682```ts 1683let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1684let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 1685let isReplace: boolean = pasteData.replaceRecordAt(0, record); 1686``` 1687 1688## SystemPasteboard 1689 1690Provides **SystemPasteboard** APIs. 1691 1692Before calling any **SystemPasteboard** API, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard). 1693 1694```ts 1695let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1696``` 1697 1698### on('update')<sup>7+</sup> 1699 1700on(type: 'update', callback: () =>void ): void 1701 1702Subscribes to the content change event of the system pasteboard. 1703 1704**System capability**: SystemCapability.MiscServices.Pasteboard 1705 1706**Parameters** 1707 1708| Name| Type| Mandatory| Description| 1709| -------- | -------- | -------- | -------- | 1710| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.| 1711| callback | function | Yes| Callback invoked when the pasteboard content changes.| 1712 1713**Error codes** 1714 1715For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1716 1717| Error Code ID| Error Message| 1718| -------- | -------- | 1719| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1720 1721**Example** 1722 1723```ts 1724let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1725let listener = () => { 1726 console.info('The system pasteboard has changed.'); 1727}; 1728systemPasteboard.on('update', listener); 1729``` 1730 1731### off('update')<sup>7+</sup> 1732 1733off(type: 'update', callback?: () =>void ): void 1734 1735Unsubscribes from the system pasteboard content change event. 1736 1737**System capability**: SystemCapability.MiscServices.Pasteboard 1738 1739**Parameters** 1740 1741| Name| Type| Mandatory| Description | 1742| -------- | -------- | -------- |---------------------------------------------------------| 1743| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content. | 1744| callback | function | No| Callback invoked when the pasteboard content changes. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.| 1745 1746**Error codes** 1747 1748For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1749 1750| Error Code ID| Error Message| 1751| -------- | -------- | 1752| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1753 1754**Example** 1755 1756```ts 1757let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1758let listener = () => { 1759 console.info('The system pasteboard has changed.'); 1760}; 1761systemPasteboard.off('update', listener); 1762``` 1763 1764### clearData<sup>9+</sup> 1765 1766clearData(callback: AsyncCallback<void>): void 1767 1768Clears the system pasteboard. This API uses an asynchronous callback to return the result. 1769 1770**Atomic service API**: This API can be used in atomic services since API version 11. 1771 1772**System capability**: SystemCapability.MiscServices.Pasteboard 1773 1774**Parameters** 1775 1776| Name| Type| Mandatory| Description| 1777| -------- | -------- | -------- | -------- | 1778| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1779 1780**Error codes** 1781 1782For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1783 1784| Error Code ID| Error Message| 1785| -------- | -------- | 1786| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1787 1788**Example** 1789 1790```ts 1791let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1792systemPasteboard.clearData((err, data) => { 1793 if (err) { 1794 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1795 return; 1796 } 1797 console.info('Succeeded in clearing the pasteboard.'); 1798}); 1799``` 1800 1801### clearData<sup>9+</sup> 1802 1803clearData(): Promise<void> 1804 1805Clears the system pasteboard. This API uses a promise to return the result. 1806 1807**Atomic service API**: This API can be used in atomic services since API version 11. 1808 1809**System capability**: SystemCapability.MiscServices.Pasteboard 1810 1811**Return value** 1812 1813| Type| Description| 1814| -------- | -------- | 1815| Promise<void> | Promise that returns no value.| 1816 1817**Example** 1818 1819```ts 1820import { BusinessError } from '@kit.BasicServicesKit'; 1821 1822let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1823systemPasteboard.clearData().then((data: void) => { 1824 console.info('Succeeded in clearing the pasteboard.'); 1825}).catch((err: BusinessError) => { 1826 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1827}); 1828``` 1829 1830### setData<sup>9+</sup> 1831 1832setData(data: PasteData, callback: AsyncCallback<void>): void 1833 1834Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. 1835 1836**Atomic service API**: This API can be used in atomic services since API version 11. 1837 1838**System capability**: SystemCapability.MiscServices.Pasteboard 1839 1840**Parameters** 1841 1842| Name| Type| Mandatory| Description| 1843| -------- | -------- | -------- | -------- | 1844| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1845| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1846 1847**Error codes** 1848 1849For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1850 1851| Error Code ID| Error Message| 1852| -------- | -------- | 1853| 27787277 | Another copy or paste operation is in progress. | 1854| 27787278 | Replication is prohibited. | 1855| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1856 1857**Example** 1858 1859```ts 1860let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1861let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1862systemPasteboard.setData(pasteData, (err, data) => { 1863 if (err) { 1864 console.error('Failed to set PasteData. Cause: ' + err.message); 1865 return; 1866 } 1867 console.info('Succeeded in setting PasteData.'); 1868}); 1869``` 1870 1871### setData<sup>9+</sup> 1872 1873setData(data: PasteData): Promise<void> 1874 1875Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 1876 1877**Atomic service API**: This API can be used in atomic services since API version 11. 1878 1879**System capability**: SystemCapability.MiscServices.Pasteboard 1880 1881**Parameters** 1882 1883| Name| Type| Mandatory| Description| 1884| -------- | -------- | -------- | -------- | 1885| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1886 1887**Return value** 1888 1889| Type| Description| 1890| -------- | -------- | 1891| Promise<void> | Promise that returns no value.| 1892 1893**Error codes** 1894 1895For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1896 1897| Error Code ID| Error Message| 1898| -------- | -------- | 1899| 27787277 | Another copy or paste operation is in progress. | 1900| 27787278 | Replication is prohibited. | 1901| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1902 1903**Example** 1904 1905```ts 1906import { BusinessError } from '@kit.BasicServicesKit'; 1907 1908let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1909let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1910systemPasteboard.setData(pasteData).then((data: void) => { 1911 console.info('Succeeded in setting PasteData.'); 1912}).catch((err: BusinessError) => { 1913 console.error('Failed to set PasteData. Cause: ' + err.message); 1914}); 1915``` 1916 1917### getData<sup>9+</sup> 1918 1919getData( callback: AsyncCallback<PasteData>): void 1920 1921Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. 1922 1923**Required permissions**: ohos.permission.READ_PASTEBOARD 1924 1925**Atomic service API**: This API can be used in atomic services since API version 11. 1926 1927**System capability**: SystemCapability.MiscServices.Pasteboard 1928 1929**Parameters** 1930 1931| Name| Type| Mandatory| Description| 1932| -------- | -------- | -------- | -------- | 1933| callback | AsyncCallback<[PasteData](#pastedata)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.| 1934 1935**Error codes** 1936 1937For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1938 1939| Error Code ID| Error Message| 1940| -------- | -------- | 1941| 27787277 | Another copy or paste operation is in progress. | 1942| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1943| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1944 1945**Example** 1946 1947```ts 1948import { BusinessError } from '@kit.BasicServicesKit'; 1949 1950let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1951systemPasteboard.getData((err: BusinessError, pasteData: pasteboard.PasteData) => { 1952 if (err) { 1953 console.error('Failed to get PasteData. Cause: ' + err.message); 1954 return; 1955 } 1956 let text: string = pasteData.getPrimaryText(); 1957}); 1958``` 1959 1960### getData<sup>9+</sup> 1961 1962getData(): Promise<PasteData> 1963 1964Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 1965 1966**Required permissions**: ohos.permission.READ_PASTEBOARD 1967 1968**Atomic service API**: This API can be used in atomic services since API version 11. 1969 1970**System capability**: SystemCapability.MiscServices.Pasteboard 1971 1972**Return value** 1973 1974| Type| Description| 1975| -------- | -------- | 1976| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| 1977 1978**Error codes** 1979 1980For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1981 1982| Error Code ID| Error Message| 1983| -------- | -------- | 1984| 27787277 | Another copy or paste operation is in progress. | 1985| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1986 1987**Example** 1988 1989```ts 1990import { BusinessError } from '@kit.BasicServicesKit'; 1991 1992let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1993systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 1994 let text: string = pasteData.getPrimaryText(); 1995}).catch((err: BusinessError) => { 1996 console.error('Failed to get PasteData. Cause: ' + err.message); 1997}); 1998``` 1999 2000### hasData<sup>9+</sup> 2001 2002hasData(callback: AsyncCallback<boolean>): void 2003 2004Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. 2005 2006**Atomic service API**: This API can be used in atomic services since API version 11. 2007 2008**System capability**: SystemCapability.MiscServices.Pasteboard 2009 2010**Parameters** 2011 2012| Name| Type| Mandatory| Description| 2013| -------- | -------- | -------- | -------- | 2014| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2015 2016**Error codes** 2017 2018For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2019 2020| Error Code ID| Error Message| 2021| -------- | -------- | 2022| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2023 2024**Example** 2025 2026```ts 2027import { BusinessError } from '@kit.BasicServicesKit'; 2028 2029let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2030systemPasteboard.hasData((err: BusinessError, data: boolean) => { 2031 if (err) { 2032 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 2033 return; 2034 } 2035 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 2036}); 2037``` 2038 2039### hasData<sup>9+</sup> 2040 2041hasData(): Promise<boolean> 2042 2043Checks whether the system pasteboard contains data. This API uses a promise to return the result. 2044 2045**Atomic service API**: This API can be used in atomic services since API version 11. 2046 2047**System capability**: SystemCapability.MiscServices.Pasteboard 2048 2049**Return value** 2050 2051| Type| Description| 2052| -------- | -------- | 2053| Promise<boolean> | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2054 2055**Example** 2056 2057```ts 2058import { BusinessError } from '@kit.BasicServicesKit'; 2059 2060let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2061systemPasteboard.hasData().then((data: boolean) => { 2062 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 2063}).catch((err: BusinessError) => { 2064 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 2065}); 2066``` 2067 2068### clear<sup>(deprecated)</sup> 2069 2070clear(callback: AsyncCallback<void>): void 2071 2072Clears the system pasteboard. This API uses an asynchronous callback to return the result. 2073> **NOTE** 2074> 2075> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9). 2076 2077**System capability**: SystemCapability.MiscServices.Pasteboard 2078 2079**Parameters** 2080 2081| Name| Type| Mandatory| Description| 2082| -------- | -------- | -------- | -------- | 2083| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2084 2085**Error codes** 2086 2087For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2088 2089| Error Code ID| Error Message| 2090| -------- | -------- | 2091| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2092 2093**Example** 2094 2095```ts 2096let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2097systemPasteboard.clear((err, data) => { 2098 if (err) { 2099 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 2100 return; 2101 } 2102 console.info('Succeeded in clearing the PasteData.'); 2103}); 2104``` 2105 2106### clear<sup>(deprecated)</sup> 2107 2108clear(): Promise<void> 2109 2110Clears the system pasteboard. This API uses a promise to return the result. 2111> **NOTE** 2112> 2113> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9-1). 2114 2115**System capability**: SystemCapability.MiscServices.Pasteboard 2116 2117**Return value** 2118 2119| Type| Description| 2120| -------- | -------- | 2121| Promise<void> | Promise that returns no value.| 2122 2123**Example** 2124 2125```ts 2126import { BusinessError } from '@kit.BasicServicesKit'; 2127 2128let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2129systemPasteboard.clear().then((data) => { 2130 console.info('Succeeded in clearing the PasteData.'); 2131}).catch((err: BusinessError) => { 2132 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 2133}); 2134``` 2135 2136### getPasteData<sup>(deprecated)</sup> 2137 2138getPasteData( callback: AsyncCallback<PasteData>): void 2139 2140Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. 2141> **NOTE** 2142> 2143> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9). 2144 2145**System capability**: SystemCapability.MiscServices.Pasteboard 2146 2147**Parameters** 2148 2149| Name| Type| Mandatory| Description| 2150| -------- | -------- | -------- | -------- | 2151| callback | AsyncCallback<[PasteData](#pastedata)> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the system pasteboard data. Otherwise, **err** is an error object.| 2152 2153**Error codes** 2154 2155For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2156 2157| Error Code ID| Error Message| 2158| -------- | -------- | 2159| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2160 2161**Example** 2162 2163```ts 2164import { BusinessError } from '@kit.BasicServicesKit'; 2165 2166let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2167systemPasteboard.getPasteData((err: BusinessError, pasteData: pasteboard.PasteData) => { 2168 if (err) { 2169 console.error('Failed to get PasteData. Cause: ' + err.message); 2170 return; 2171 } 2172 let text: string = pasteData.getPrimaryText(); 2173}); 2174``` 2175 2176### getPasteData<sup>(deprecated)</sup> 2177 2178getPasteData(): Promise<PasteData> 2179 2180Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 2181> **NOTE** 2182> 2183> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9-1). 2184 2185**System capability**: SystemCapability.MiscServices.Pasteboard 2186 2187**Return value** 2188 2189| Type| Description| 2190| -------- | -------- | 2191| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| 2192 2193**Example** 2194 2195```ts 2196import { BusinessError } from '@kit.BasicServicesKit'; 2197 2198let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2199systemPasteboard.getPasteData().then((pasteData: pasteboard.PasteData) => { 2200 let text: string = pasteData.getPrimaryText(); 2201}).catch((err: BusinessError) => { 2202 console.error('Failed to get PasteData. Cause: ' + err.message); 2203}); 2204``` 2205 2206### hasPasteData<sup>(deprecated)</sup> 2207 2208hasPasteData(callback: AsyncCallback<boolean>): void 2209 2210Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. 2211> **NOTE** 2212> 2213> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9). 2214 2215**System capability**: SystemCapability.MiscServices.Pasteboard 2216 2217**Parameters** 2218 2219| Name| Type| Mandatory| Description| 2220| -------- | -------- | -------- | -------- | 2221| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2222 2223**Error codes** 2224 2225For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2226 2227| Error Code ID| Error Message| 2228| -------- | -------- | 2229| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2230 2231**Example** 2232 2233```ts 2234import { BusinessError } from '@kit.BasicServicesKit'; 2235 2236let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2237systemPasteboard.hasPasteData((err: BusinessError, data: boolean) => { 2238 if (err) { 2239 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 2240 return; 2241 } 2242 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 2243}); 2244``` 2245 2246### hasPasteData<sup>(deprecated)</sup> 2247 2248hasPasteData(): Promise<boolean> 2249 2250Checks whether the system pasteboard contains data. This API uses a promise to return the result. 2251> **NOTE** 2252> 2253> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9-1). 2254 2255**System capability**: SystemCapability.MiscServices.Pasteboard 2256 2257**Return value** 2258 2259| Type| Description| 2260| -------- | -------- | 2261| Promise<boolean> | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2262 2263**Example** 2264 2265```ts 2266import { BusinessError } from '@kit.BasicServicesKit'; 2267 2268let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2269systemPasteboard.hasPasteData().then((data: boolean) => { 2270 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 2271}).catch((err: BusinessError) => { 2272 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 2273}); 2274``` 2275 2276### setPasteData<sup>(deprecated)</sup> 2277 2278setPasteData(data: PasteData, callback: AsyncCallback<void>): void 2279 2280Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. 2281> **NOTE** 2282> 2283> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setData](#setdata9). 2284 2285**System capability**: SystemCapability.MiscServices.Pasteboard 2286 2287**Parameters** 2288 2289| Name| Type| Mandatory| Description| 2290| -------- | -------- | -------- | -------- | 2291| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 2292| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2293 2294**Error codes** 2295 2296For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2297 2298| Error Code ID| Error Message| 2299| -------- | -------- | 2300| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2301 2302**Example** 2303 2304```ts 2305let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 2306let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2307systemPasteboard.setPasteData(pasteData, (err, data) => { 2308 if (err) { 2309 console.error('Failed to set PasteData. Cause: ' + err.message); 2310 return; 2311 } 2312 console.info('Succeeded in setting PasteData.'); 2313}); 2314``` 2315### setPasteData<sup>(deprecated)</sup> 2316 2317setPasteData(data: PasteData): Promise<void> 2318 2319Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 2320> **NOTE** 2321> 2322> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setData](#setdata9-1). 2323 2324**System capability**: SystemCapability.MiscServices.Pasteboard 2325 2326**Parameters** 2327 2328| Name| Type| Mandatory| Description| 2329| -------- | -------- | -------- | -------- | 2330| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 2331 2332**Return value** 2333 2334| Type| Description| 2335| -------- | -------- | 2336| Promise<void> | Promise that returns no value.| 2337 2338**Example** 2339 2340```ts 2341import { BusinessError } from '@kit.BasicServicesKit'; 2342 2343let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 2344let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2345systemPasteboard.setPasteData(pasteData).then((data: void) => { 2346 console.info('Succeeded in setting PasteData.'); 2347}).catch((err: BusinessError) => { 2348 console.error('Failed to set PasteData. Cause: ' + err.message); 2349}); 2350``` 2351### isRemoteData<sup>11+</sup> 2352 2353isRemoteData(): boolean 2354 2355Checks whether the data in the pasteboard is from another device. 2356 2357**Atomic service API**: This API can be used in atomic services since API version 11. 2358 2359**System capability**: SystemCapability.MiscServices.Pasteboard 2360 2361**Return value** 2362 2363| Type | Description | 2364| ------- | ------------------------------------- | 2365| boolean | Returns **true** if the data in the pasteboard is from another device; returns **false** otherwise.| 2366 2367**Error codes** 2368 2369For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2370 2371| Error Code ID| Error Message| 2372| -------- | -------- | 2373| 12900005 | Request timed out. | 2374 2375**Example** 2376 2377```ts 2378let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2379try { 2380 let result: boolean = systemPasteboard.isRemoteData(); 2381 console.info(`Succeeded in checking the RemoteData. Result: ${result}`); 2382} catch (err) { 2383 console.error('Failed to check the RemoteData. Cause:' + err.message); 2384}; 2385``` 2386 2387### getDataSource<sup>11+</sup> 2388 2389getDataSource(): string 2390 2391Obtains the data source. 2392 2393**Atomic service API**: This API can be used in atomic services since API version 11. 2394 2395**System capability**: SystemCapability.MiscServices.Pasteboard 2396 2397**Return value** 2398 2399| Type | Description | 2400| ------ | ------ | 2401| string | Data source.| 2402 2403**Error codes** 2404 2405For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2406 2407| Error Code ID| Error Message| 2408| -------- | -------- | 2409| 12900005 | Request timed out. | 2410 2411**Example** 2412 2413```ts 2414let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2415try { 2416 let result: string = systemPasteboard.getDataSource(); 2417 console.info(`Succeeded in getting DataSource. Result: ${result}`); 2418} catch (err) { 2419 console.error('Failed to get DataSource. Cause:' + err.message); 2420}; 2421``` 2422 2423### hasDataType<sup>11+</sup> 2424 2425hasDataType(mimeType: string): boolean 2426 2427Checks whether the pasteboard contains data of the specified type. 2428 2429**Atomic service API**: This API can be used in atomic services since API version 11. 2430 2431**System capability**: SystemCapability.MiscServices.Pasteboard 2432 2433**Parameters** 2434 2435| Name | Type | Mandatory| Description | 2436| -------- | ------ | ---- | ------------------ | 2437| mimeType | string | Yes | Data type.| 2438 2439**Return value** 2440 2441| Type | Description | 2442| ------- | ------------------------------------------- | 2443| boolean | Returns **true** if the pasteboard contains data of the specified type; returns **false** otherwise.| 2444 2445**Error codes** 2446 2447For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2448 2449| Error Code ID| Error Message| 2450| -------- | -------- | 2451| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2452| 12900005 | Request timed out. | 2453 2454**Example** 2455 2456```ts 2457let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2458try { 2459 let result: boolean = systemPasteboard.hasDataType(pasteboard.MIMETYPE_TEXT_PLAIN); 2460 console.info(`Succeeded in checking the DataType. Result: ${result}`); 2461} catch (err) { 2462 console.error('Failed to check the DataType. Cause:' + err.message); 2463}; 2464``` 2465 2466### clearDataSync<sup>11+</sup> 2467 2468clearDataSync(): void 2469 2470Clears the system pasteboard. This API returns the result synchronously. 2471 2472**Atomic service API**: This API can be used in atomic services since API version 11. 2473 2474**System capability**: SystemCapability.MiscServices.Pasteboard 2475 2476**Error codes** 2477 2478For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2479 2480| Error Code ID| Error Message| 2481| -------- | -------- | 2482| 12900005 | Request timed out. | 2483 2484**Example** 2485 2486```ts 2487let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2488try { 2489 systemPasteboard.clearDataSync(); 2490 console.info('Succeeded in clearing the pasteboard.'); 2491} catch (err) { 2492 console.error('Failed to clear the pasteboard. Cause:' + err.message); 2493}; 2494``` 2495 2496### getDataSync<sup>11+</sup> 2497 2498getDataSync(): PasteData 2499 2500Reads data in the system pasteboard. This API returns the result synchronously. 2501 2502**Required permissions**: ohos.permission.READ_PASTEBOARD 2503 2504**Atomic service API**: This API can be used in atomic services since API version 11. 2505 2506**System capability**: SystemCapability.MiscServices.Pasteboard 2507 2508**Return value** 2509 2510| Type | Description | 2511| ----------------------- | -------------------- | 2512| [PasteData](#pastedata) | Data in the system pasteboard.| 2513 2514**Error codes** 2515 2516For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2517 2518| Error Code ID| Error Message| 2519| -------- | -------- | 2520| 12900005 | Request timed out. | 2521| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2522 2523**Example** 2524 2525```ts 2526let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2527try { 2528 let result: pasteboard.PasteData = systemPasteboard.getDataSync(); 2529 console.info('Succeeded in getting PasteData.'); 2530} catch (err) { 2531 console.error('Failed to get PasteData. Cause:' + err.message); 2532}; 2533``` 2534 2535### setDataSync<sup>11+</sup> 2536 2537setDataSync(data: PasteData): void 2538 2539Writes data to the system pasteboard. This API returns the result synchronously. 2540 2541**Atomic service API**: This API can be used in atomic services since API version 11. 2542 2543**System capability**: SystemCapability.MiscServices.Pasteboard 2544 2545**Parameters** 2546 2547| Name| Type | Mandatory| Description | 2548| ------ | ----------------------- | ---- | ---------------- | 2549| data | [PasteData](#pastedata) | Yes | Data to be written to the pasteboard.| 2550 2551**Error codes** 2552 2553For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2554 2555| Error Code ID| Error Message| 2556| -------- | -------- | 2557| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2558| 12900005 | Request timed out. | 2559 2560**Example** 2561 2562```ts 2563let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 2564let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2565try { 2566 systemPasteboard.setDataSync(pasteData); 2567 console.info('Succeeded in setting PasteData.'); 2568} catch (err) { 2569 console.error('Failed to set PasteData. Cause:' + err.message); 2570}; 2571``` 2572 2573### hasDataSync<sup>11+</sup> 2574 2575hasDataSync(): boolean 2576 2577Checks whether the system pasteboard contains data. This API returns the result synchronously. 2578 2579**Atomic service API**: This API can be used in atomic services since API version 11. 2580 2581**System capability**: SystemCapability.MiscServices.Pasteboard 2582 2583**Return value** 2584 2585| Type | Description | 2586| ------- | ----------------------------------------------------------------------- | 2587| boolean | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2588 2589**Error codes** 2590 2591For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2592 2593| Error Code ID| Error Message| 2594| -------- | -------- | 2595| 12900005 | Request timed out. | 2596 2597**Example** 2598 2599```ts 2600let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2601try { 2602 let result: boolean = systemPasteboard.hasDataSync(); 2603 console.info(`Succeeded in checking the PasteData. Result: ${result}`); 2604} catch (err) { 2605 console.error('Failed to check the PasteData. Cause:' + err.message); 2606}; 2607``` 2608 2609### getUnifiedData<sup>12+</sup> 2610 2611getUnifiedData(): Promise<unifiedDataChannel.UnifiedData> 2612 2613Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 2614 2615**Required permissions**: ohos.permission.READ_PASTEBOARD 2616 2617**Atomic service API**: This API can be used in atomic services since API version 12. 2618 2619**System capability**: SystemCapability.MiscServices.Pasteboard 2620 2621**Return value** 2622 2623| Type| Description| 2624| -------- | -------- | 2625| Promise<[unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata)> | Promise used to return the system pasteboard data.| 2626 2627**Error codes** 2628 2629For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2630 2631| Error Code ID| Error Message| 2632| -------- | -------- | 2633| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2634| 27787277 | Another copy or paste operation is in progress. | 2635 2636**Example** 2637 2638```ts 2639import { BusinessError } from '@kit.BasicServicesKit'; 2640import { unifiedDataChannel } from '@kit.ArkData'; 2641import { uniformTypeDescriptor } from '@kit.ArkData'; 2642 2643let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2644systemPasteboard.getUnifiedData().then((data) => { 2645 let records: Array<unifiedDataChannel.UnifiedRecord> = data.getRecords(); 2646 for (let j = 0; j < records.length; j++) { 2647 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 2648 let text = records[j] as unifiedDataChannel.PlainText; 2649 console.info(`${j + 1}.${text.textContent}`); 2650 } 2651 } 2652}).catch((err: BusinessError) => { 2653 console.error('Failed to get UnifiedData. Cause: ' + err.message); 2654}); 2655``` 2656 2657### getUnifiedDataSync<sup>12+</sup> 2658 2659getUnifiedDataSync(): unifiedDataChannel.UnifiedData 2660 2661Reads data in the system pasteboard. This API returns the result synchronously. 2662 2663**Required permissions**: ohos.permission.READ_PASTEBOARD 2664 2665**Atomic service API**: This API can be used in atomic services since API version 12. 2666 2667**System capability**: SystemCapability.MiscServices.Pasteboard 2668 2669**Return value** 2670 2671| Type | Description | 2672| -------------------- | -------------------- | 2673| [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Data in the system pasteboard.| 2674 2675**Error codes** 2676 2677For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2678 2679| Error Code ID| Error Message| 2680| -------- | -------- | 2681| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2682| 12900005 | Request timed out. | 2683 2684**Example** 2685 2686```ts 2687import { unifiedDataChannel } from '@kit.ArkData'; 2688 2689let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2690try { 2691 let result: unifiedDataChannel.UnifiedData = systemPasteboard.getUnifiedDataSync(); 2692 console.info('Succeeded in getting UnifiedData.'); 2693} catch (err) { 2694 console.error('Failed to get UnifiedData. Cause:' + err.message); 2695}; 2696``` 2697 2698### setUnifiedData<sup>12+</sup> 2699 2700setUnifiedData(data: unifiedDataChannel.UnifiedData): Promise<void> 2701 2702Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 2703 2704**System capability**: SystemCapability.MiscServices.Pasteboard 2705 2706**Atomic service API**: This API can be used in atomic services since API version 12. 2707 2708**Parameters** 2709 2710| Name| Type| Mandatory| Description| 2711| -------- | -------- | -------- | -------- | 2712| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Yes| Data to be written to the pasteboard.| 2713 2714**Return value** 2715 2716| Type| Description| 2717| -------- | -------- | 2718| Promise<void> | Promise that returns no value.| 2719 2720**Error codes** 2721 2722For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2723 2724| Error Code ID| Error Message| 2725| -------- | -------- | 2726| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2727| 27787277 | Another copy or paste operation is in progress. | 2728| 27787278 | Replication is prohibited. | 2729 2730**Example** 2731 2732```ts 2733import { BusinessError } from '@kit.BasicServicesKit'; 2734import { unifiedDataChannel } from '@kit.ArkData'; 2735 2736let plainTextData = new unifiedDataChannel.UnifiedData(); 2737let plainText = new unifiedDataChannel.PlainText(); 2738plainText.details = { 2739 Key: 'delayPlaintext', 2740 Value: 'delayPlaintext', 2741}; 2742plainText.textContent = 'delayTextContent'; 2743plainText.abstract = 'delayTextContent'; 2744plainTextData.addRecord(plainText); 2745 2746let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2747systemPasteboard.setUnifiedData(plainTextData).then((data: void) => { 2748 console.info('Succeeded in setting UnifiedData.'); 2749}).catch((err: BusinessError) => { 2750 console.error('Failed to set UnifiedData. Cause: ' + err.message); 2751}); 2752``` 2753 2754### setUnifiedDataSync<sup>12+</sup> 2755 2756setUnifiedDataSync(data: unifiedDataChannel.UnifiedData): void 2757 2758Writes data to the system pasteboard. This API returns the result synchronously. 2759 2760**System capability**: SystemCapability.MiscServices.Pasteboard 2761 2762**Atomic service API**: This API can be used in atomic services since API version 12. 2763 2764**Parameters** 2765 2766| Name| Type | Mandatory| Description | 2767| ------ | ----------- | ---- | ---------------- | 2768| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Yes | Data to be written to the pasteboard.| 2769 2770**Error codes** 2771 2772For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2773 2774| Error Code ID| Error Message| 2775| -------- | -------- | 2776| 401 | Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2777| 12900005 | Request timed out. | 2778 2779**Example** 2780 2781```ts 2782import { unifiedDataChannel } from '@kit.ArkData'; 2783 2784let plainTextData = new unifiedDataChannel.UnifiedData(); 2785let plainText = new unifiedDataChannel.PlainText(); 2786plainText.details = { 2787 Key: 'delayPlaintext', 2788 Value: 'delayPlaintext', 2789}; 2790plainText.textContent = 'delayTextContent'; 2791plainText.abstract = 'delayTextContent'; 2792plainTextData.addRecord(plainText); 2793 2794let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2795try { 2796 systemPasteboard.setUnifiedDataSync(plainTextData); 2797 console.info('Succeeded in setting UnifiedData.'); 2798} catch (err) { 2799 console.error('Failed to set UnifiedData. Cause:' + err.message); 2800}; 2801``` 2802 2803### setAppShareOptions<sup>14+</sup> 2804 2805setAppShareOptions(shareOptions: ShareOption): void 2806 2807Sets pasteable range of pasteboard data for applications. 2808 2809**Required permissions**: ohos.permission.MANAGE_PASTEBOARD_APP_SHARE_OPTION 2810 2811**System capability**: SystemCapability.MiscServices.Pasteboard 2812 2813**Parameters** 2814 2815| Name| Type| Mandatory| Description| 2816| -------- | -------- | -------- | -------- | 2817| shareOptions | [ShareOption](js-apis-pasteboard.md#shareoption9) | Yes| Pasteable range. Only **pasteboard.ShareOption.INAPP** is allowed.| 2818 2819**Error codes** 2820 2821For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2822 2823| Error Code ID| Error Message| 2824| -------- | -------- | 2825| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2826| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 2827| 12900006 | Settings already exist. | 2828 2829**Example** 2830 2831```ts 2832import { BusinessError } from '@kit.BasicServicesKit'; 2833 2834let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2835try { 2836 systemPasteboard.setAppShareOptions(pasteboard.ShareOption.INAPP); 2837 console.info('Set app share options success.'); 2838} catch (err) { 2839 let error: BusinessError = err as BusinessError; 2840 console.error(`Set app share options failed, errorCode: ${error.code}, errorMessage: ${error.message}.`); 2841} 2842``` 2843 2844### removeAppShareOptions<sup>14+</sup> 2845 2846removeAppShareOptions(): void 2847 2848Deletes the global pasteable range of the application. 2849 2850**Required permissions**: ohos.permission.MANAGE_PASTEBOARD_APP_SHARE_OPTION 2851 2852**System capability**: SystemCapability.MiscServices.Pasteboard 2853 2854**Error codes** 2855 2856For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2857 2858| Error Code ID| Error Message| 2859| -------- | -------- | 2860| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2861 2862**Example** 2863 2864```ts 2865import { BusinessError } from '@kit.BasicServicesKit'; 2866 2867let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2868try { 2869 systemPasteboard.removeAppShareOptions(); 2870 console.info('Remove app share options success.'); 2871} catch (err) { 2872 let error: BusinessError = err as BusinessError; 2873 console.error(`Remove app share options failed, errorCode: ${error.code}, errorMessage: ${error.message}.`); 2874} 2875``` 2876 2877### Pattern<sup>13+</sup> 2878Describes the modes supported by the pasteboard. 2879 2880**System capability**: SystemCapability.MiscServices.Pasteboard 2881 2882| Name | Value | Description | 2883| ---------------------------------- | --- | ------------------------------------------------------------------------------------- | 2884| URL | 0 | URL. | 2885| NUMBER | 1 | Number. | 2886| EMAIL_ADDRESS | 2 | Email address.| 2887 2888### detectPatterns<sup>13+</sup> 2889 2890detectPatterns(patterns: Array<Pattern>): Promise<Array<Pattern>> 2891 2892Detects patterns on the **local** pasteboard. This API uses a promise to return the result. 2893 2894**System capability**: SystemCapability.MiscServices.Pasteboard 2895 2896**Parameters** 2897 2898| Name| Type| Mandatory| Description| 2899| -------- | -------- | -------- | -------- | 2900| patterns | [Array<Pattern>](#pattern13) | Yes| Pattern to be detected in the pasteboard.| 2901 2902**Return value** 2903 2904| Type| Description| 2905| -------- | -------- | 2906| Promise<Array<Pattern>> | Promise used to return the detected pattern.| 2907 2908**Error codes** 2909 2910For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2911 2912| Error Code ID| Error Message| 2913| -------- | -------- | 2914| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. 3. Parameter verification failed. | 2915 2916**Example** 2917 2918```ts 2919import { pasteboard } from '@kit.BasicServicesKit' 2920 2921let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2922let patterns: Array<pasteboard.Pattern> = [pasteboard.Pattern.URL, pasteboard.Pattern.EMAIL_ADDRESS]; 2923 2924systemPasteboard.detectPatterns(patterns).then((data: Array<pasteboard.Pattern>) => { 2925 if (patterns.sort().join('')==data.sort().join('')) { 2926 console.info('All needed patterns detected, next get data'); 2927 try { 2928 let result: pasteboard.PasteData = systemPasteboard.getDataSync(); 2929 console.info('Succeeded in getting PasteData.'); 2930 } catch (err) { 2931 console.error('Failed to get PasteData. Cause:' + err.message); 2932 }; 2933 } else { 2934 console.info("Not all needed patterns detected, no need to get data."); 2935 } 2936}); 2937``` 2938 2939### getMimeTypes<sup>14+</sup> 2940 2941getMimeTypes(): Promise<Array<string>> 2942 2943Obtains the MIME type from the pasteboard. This API uses a promise to return the result. 2944 2945**Atomic service API**: This API can be used in atomic services since API version 14. 2946 2947**System capability**: SystemCapability.MiscServices.Pasteboard 2948 2949**Return value** 2950 2951| Type| Description| 2952| -------- | -------- | 2953| Promise<Array<string>> | Promise used to return the read MIME type.| 2954 2955**Example** 2956 2957```ts 2958import { pasteboard, BusinessError } from '@kit.BasicServicesKit' 2959 2960let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2961systemPasteboard.getMimeTypes().then((data: Array<String>) => { 2962 console.info('Succeeded in getting mimeTypes. mimeTypes: ' + data.sort().join(',')); 2963}).catch((err: BusinessError) => { 2964 console.error('Failed to get mimeTypes. Cause:' + err.message); 2965}); 2966``` 2967 2968### getDataWithProgress<sup>15+</sup> 2969 2970getDataWithProgress(params: GetDataParams): Promise<PasteData> 2971 2972Obtains the pasteboard data and progress. This API uses a promise to return the result. Folders cannot be copied. 2973 2974**Required permissions**: ohos.permission.READ_PASTEBOARD 2975 2976**Atomic service API**: This API can be used in atomic services since API version 15. 2977 2978**System capability**: SystemCapability.MiscServices.Pasteboard 2979 2980**Parameters** 2981 2982| Name| Type | Mandatory| Description | 2983| ------ | --------------------------------- | ---- | ------------------------------------------------------------ | 2984| params | [GetDataParams](#getdataparams15) | Yes | Parameters required when an application uses the file copy capability provided by the pasteboard, including the destination path, file conflict option, and progress bar type.| 2985 2986**Return value** 2987 2988| Type | Description | 2989| -------------------------------------- | --------------------------------- | 2990| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| 2991 2992**Error codes** 2993 2994For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2995 2996| Error Code ID| Error Message | 2997| -------- | ------------------------------------------------------------ | 2998| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2999| 401 | Parameter error. | 3000| 12900003 | Another copy or paste operation is in progress. | 3001| 12900007 | Copy file failed. | 3002| 12900008 | Failed to start progress. | 3003| 12900009 | Progress exits abnormally. | 3004| 12900010 | Get pasteData error. | 3005 3006**Example** 3007 3008```ts 3009import { BusinessError, pasteboard } from '@kit.BasicServicesKit'; 3010@Entry 3011@Component 3012struct PasteboardTest { 3013 build() { 3014 RelativeContainer() { 3015 Column() { 3016 Column() { 3017 Button("Copy txt") 3018 .onClick(async ()=>{ 3019 let text = "test"; 3020 let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, text); 3021 let systemPasteboard = pasteboard.getSystemPasteboard(); 3022 await systemPasteboard.setData(pasteData); 3023 let ProgressListener = (progress: pasteboard.ProgressInfo) => { 3024 console.log('progressListener success, progress:' + progress.progress); 3025 } 3026 let params: pasteboard.GetDataParams = { 3027 destUri: '/data/storage/el2/base/haps/entry/files/dstFile.txt', 3028 fileConflictOptions: pasteboard.FileConflictOptions.OVERWRITE, 3029 progressIndicator: pasteboard.ProgressIndicator.DEFAULT, 3030 progressListener: ProgressListener 3031 }; 3032 systemPasteboard.getDataWithProgress(params).then((pasteData: pasteboard.PasteData) => { 3033 console.error('getDataWithProgress succ'); 3034 }).catch((err: BusinessError) => { 3035 console.error('Failed to get PasteData. Cause: ' + err.message); 3036 }) 3037 }) 3038 } 3039 } 3040 } 3041 } 3042} 3043``` 3044 3045### getChangeCount<sup>18+</sup> 3046 3047getChangeCount(): number 3048 3049Obtains the number of times that the pasteboard data changes. 3050 3051Returns the result if this API is called successfully; otherwise, returns **0**. 3052 3053Even though the pasteboard data expires, or the data becomes empty because of the called [clearDataSync](#cleardatasync11) API, the number of data changes remains. 3054 3055When the system is restarted, or the pasteboard service is restarted due to an exception, the number of pasteboard data changes counts from 0. In addition, copying the same data repeatedly is considered to change the data for multiple times. Therefore, each time the data is copied, the number of data changes increases. 3056 3057**Atomic service API**: This API can be used in atomic services since API version 18. 3058 3059**System capability**: SystemCapability.MiscServices.Pasteboard 3060 3061**Return value** 3062 3063| Type| Description| 3064| -------- | -------- | 3065| number | Number of times that the pasteboard data changes.| 3066 3067**Example** 3068 3069```ts 3070import { BusinessError, pasteboard } from '@kit.BasicServicesKit'; 3071 3072let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 3073try { 3074 let result : number = systemPasteboard.getChangeCount(); 3075 console.info(`Succeeded in getting the ChangeCount. Result: ${result}`); 3076} catch (err) { 3077 console.error(`Failed to get the ChangeCount. Cause: ${err.message}`); 3078}; 3079``` 3080