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 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter 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 93## pasteboard.createRecord<sup>9+</sup> 94 95createRecord(mimeType: string, value: ValueType):PasteDataRecord; 96 97Creates a **PasteDataRecord** object of the custom type. 98 99**Atomic service API**: This API can be used in atomic services since API version 11. 100 101**System capability**: SystemCapability.MiscServices.Pasteboard 102 103**Parameters** 104 105| Name| Type| Mandatory| Description | 106| -------- | -------- | -------- |-------------------| 107| 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. | 108| value | [ValueType](#valuetype9) | Yes| Content of custom data. | 109 110**Return value** 111 112| Type| Description| 113| -------- | -------- | 114| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the custom type.| 115 116**Error codes** 117 118For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 119 120| Error Code ID| Error Message| 121| -------- | -------- | 122| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 123 124**Example 1** 125 126 ```ts 127let dataXml = new ArrayBuffer(256); 128let pasteDataRecord: pasteboard.PasteDataRecord = pasteboard.createRecord('app/xml', dataXml); 129 ``` 130 131**Example 2** 132 133 ```ts 134let dataUri = 'dataability:///com.example.myapplication1/user.txt'; 135let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, dataUri); 136 ``` 137 138## pasteboard.getSystemPasteboard 139 140getSystemPasteboard(): SystemPasteboard 141 142Obtains this **SystemPasteboard** object. 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**Return value** 149 150| Type| Description| 151| -------- | -------- | 152| [SystemPasteboard](#systempasteboard) | **SystemPasteboard** object.| 153 154**Example** 155 156```ts 157let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 158``` 159 160## ShareOption<sup>9+</sup> 161 162Enumerates the paste options of data. 163 164**Atomic service API**: This API can be used in atomic services since API version 11. 165 166**System capability**: SystemCapability.MiscServices.Pasteboard 167 168| Name | Value | Description | 169| ---------------------------------- | --- | ------------------------------------------------------------------------------------- | 170| INAPP | 0 | Only intra-application pasting is allowed. | 171| LOCALDEVICE | 1 | Paste is allowed in any application on the local device. | 172| 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.| 173 174## pasteboard.createHtmlData<sup>(deprecated)</sup> 175 176createHtmlData(htmlText: string): PasteData 177 178Creates a **PasteData** object of the HTML type. 179> **NOTE** 180> 181> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 182 183**System capability**: SystemCapability.MiscServices.Pasteboard 184 185**Parameters** 186 187| Name| Type| Mandatory| Description| 188| -------- | -------- | -------- | -------- | 189| htmlText | string | Yes| HTML content.| 190 191**Return value** 192 193| Type| Description| 194| -------- | -------- | 195| [PasteData](#pastedata) | **PasteData** object.| 196 197**Example** 198 199```ts 200let 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>"; 201let pasteData: pasteboard.PasteData = pasteboard.createHtmlData(html); 202``` 203 204## pasteboard.createWantData<sup>(deprecated)</sup> 205 206createWantData(want: Want): PasteData 207 208Creates a **PasteData** object of the Want type. 209> **NOTE** 210> 211> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 212 213**System capability**: SystemCapability.MiscServices.Pasteboard 214 215**Parameters** 216 217| Name| Type| Mandatory| Description| 218| -------- | -------- | -------- | -------- | 219| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want content.| 220 221**Return value** 222 223| Type| Description| 224| -------- | -------- | 225| [PasteData](#pastedata) | **PasteData** object.| 226 227**Example** 228 229```ts 230import { Want } from '@kit.AbilityKit'; 231 232let object: Want = { 233 bundleName: "com.example.aafwk.test", 234 abilityName: "com.example.aafwk.test.TwoAbility" 235}; 236let pasteData: pasteboard.PasteData = pasteboard.createWantData(object); 237``` 238 239## pasteboard.createPlainTextData<sup>(deprecated)</sup> 240 241createPlainTextData(text: string): PasteData 242 243Creates a **PasteData** object of the plain text type. 244> **NOTE** 245> 246> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 247 248**System capability**: SystemCapability.MiscServices.Pasteboard 249 250**Parameters** 251 252| Name| Type| Mandatory| Description| 253| -------- | -------- | -------- | -------- | 254| text | string | Yes| Plain text.| 255 256**Return value** 257 258| Type| Description| 259| -------- | -------- | 260| [PasteData](#pastedata) | **PasteData** object.| 261 262**Example** 263 264```ts 265let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 266``` 267 268## pasteboard.createUriData<sup>(deprecated)</sup> 269 270createUriData(uri: string): PasteData 271 272Creates a **PasteData** object of the URI type. 273> **NOTE** 274> 275> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createData](#pasteboardcreatedata9). 276 277**System capability**: SystemCapability.MiscServices.Pasteboard 278 279**Parameters** 280 281| Name| Type| Mandatory| Description| 282| -------- | -------- | -------- | -------- | 283| uri | string | Yes| URI content.| 284 285**Return value** 286 287| Type| Description| 288| -------- | -------- | 289| [PasteData](#pastedata) | **PasteData** object.| 290 291**Example** 292 293```ts 294let pasteData: pasteboard.PasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); 295``` 296## pasteboard.createHtmlTextRecord<sup>(deprecated)</sup> 297 298createHtmlTextRecord(htmlText: string): PasteDataRecord 299 300Creates a **PasteDataRecord** object of the HTML text type. 301> **NOTE** 302> 303> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 304 305**System capability**: SystemCapability.MiscServices.Pasteboard 306 307**Parameters** 308 309| Name| Type| Mandatory| Description| 310| -------- | -------- | -------- | -------- | 311| htmlText | string | Yes| HTML content.| 312 313**Return value** 314 315| Type| Description| 316| -------- | -------- | 317| [PasteDataRecord](#pastedatarecord7) | **PasteDataRecord** object of the HTML text type.| 318 319**Example** 320 321```ts 322let 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>"; 323let record: pasteboard.PasteDataRecord = pasteboard.createHtmlTextRecord(html); 324``` 325 326## pasteboard.createWantRecord<sup>(deprecated)</sup> 327 328createWantRecord(want: Want): PasteDataRecord 329 330Creates a **PasteDataRecord** object of the Want type. 331> **NOTE** 332> 333> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 334 335**System capability**: SystemCapability.MiscServices.Pasteboard 336 337**Parameters** 338 339| Name| Type| Mandatory| Description| 340| -------- | -------- | -------- | -------- | 341| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want content.| 342 343**Return value** 344 345| Type| Description| 346| -------- | -------- | 347| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the Want type.| 348 349**Example** 350 351```ts 352import { Want } from '@kit.AbilityKit'; 353 354let object: Want = { 355 bundleName: "com.example.aafwk.test", 356 abilityName: "com.example.aafwk.test.TwoAbility" 357}; 358let record: pasteboard.PasteDataRecord = pasteboard.createWantRecord(object); 359``` 360 361## pasteboard.createPlainTextRecord<sup>(deprecated)</sup> 362 363createPlainTextRecord(text: string): PasteDataRecord 364 365Creates a **PasteDataRecord** object of the plain text type. 366> **NOTE** 367> 368> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 369 370**System capability**: SystemCapability.MiscServices.Pasteboard 371 372**Parameters** 373 374| Name| Type| Mandatory| Description| 375| -------- | -------- | -------- | -------- | 376| text | string | Yes| Plain text.| 377 378**Return value** 379 380| Type| Description| 381| -------- | -------- | 382| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the plain text type.| 383 384**Example** 385 386```ts 387let record: pasteboard.PasteDataRecord = pasteboard.createPlainTextRecord('hello'); 388``` 389 390## pasteboard.createUriRecord<sup>(deprecated)</sup> 391 392createUriRecord(uri: string): PasteDataRecord 393 394Creates a **PasteDataRecord** object of the URI type. 395> **NOTE** 396> 397> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.createRecord](#pasteboardcreaterecord9). 398 399**System capability**: SystemCapability.MiscServices.Pasteboard 400 401**Parameters** 402 403| Name| Type| Mandatory| Description| 404| -------- | -------- | -------- | -------- | 405| uri | string | Yes| URI content.| 406 407**Return value** 408 409| Type| Description| 410| -------- | -------- | 411| [PasteDataRecord](#pastedatarecord7) | New **PasteDataRecord** object of the URI type.| 412 413**Example** 414 415```ts 416let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 417``` 418 419 420## PasteDataProperty<sup>7+</sup> 421 422Defines the properties of all data records on the pasteboard, including the timestamp, data type, and additional data. 423The defined properties can be applied to the pasteboard only with the [setProperty](#setproperty9) API. 424 425**Atomic service API**: This API can be used in atomic services since API version 11. 426 427**System capability**: SystemCapability.MiscServices.Pasteboard 428 429| Name| Type| Readable| Writable| Description | 430| -------- | -------- | -------- | -------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 431| 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**. | 432| mimeTypes<sup>7+</sup> | Array<string> | Yes| No| Non-repeating data types of the data records on the pasteboard. | 433| tag<sup>7+</sup> | string | Yes| Yes| Custom tag. | 434| timestamp<sup>7+</sup> | number | Yes| No| Timestamp when data is written to the pasteboard (unit: ms). | 435| 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.| 436| 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. | 437 438## PasteDataRecord<sup>7+</sup> 439 440Provides **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. 441 442### Attributes 443 444**Atomic service API**: This API can be used in atomic services since API version 11. 445 446**System capability**: SystemCapability.MiscServices.Pasteboard 447 448| Name| Type| Readable| Writable| Description| 449| -------- | -------- | -------- | -------- | -------- | 450| htmlText<sup>7+</sup> | string | Yes| No| HTML content.| 451| want<sup>7+</sup> | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| No| Want content.| 452| mimeType<sup>7+</sup> | string | Yes| No| Data type.| 453| plainText<sup>7+</sup> | string | Yes| No| Plain text.| 454| uri<sup>7+</sup> | string | Yes| No| URI content.| 455| pixelMap<sup>9+</sup> | [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Yes| No| Pixel map.| 456| data<sup>9+</sup> | {[mimeType: string]: ArrayBuffer} | Yes| No| Content of custom data.| 457 458### toPlainText<sup>9+</sup> 459 460toPlainText(): string 461 462Forcibly converts the content in a **PasteData** object to text. 463 464**Atomic service API**: This API can be used in atomic services since API version 11. 465 466**System capability**: SystemCapability.MiscServices.Pasteboard 467 468**Return value** 469 470| Type| Description| 471| -------- | -------- | 472| string | Plain text.| 473 474**Example** 475 476```ts 477let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 478let data: string = record.toPlainText(); 479console.info(`Succeeded in converting to text. Data: ${data}`); 480``` 481 482### convertToText<sup>(deprecated)</sup> 483 484convertToText(callback: AsyncCallback<string>): void 485 486Forcibly converts the content in a **PasteData** object to text. This API uses an asynchronous callback to return the result. 487> **NOTE** 488> 489> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). 490 491**System capability**: SystemCapability.MiscServices.Pasteboard 492 493**Parameters** 494 495| Name| Type| Mandatory| Description| 496| -------- | -------- | -------- | -------- | 497| 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.| 498 499**Error codes** 500 501For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 502 503| Error Code ID| Error Message| 504| -------- | -------- | 505| 401 | Parameter error. Possible causes: Incorrect parameter types. | 506 507**Example** 508 509```ts 510import { BusinessError } from '@kit.BasicServicesKit'; 511 512let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 513record.convertToText((err: BusinessError, data: string) => { 514 if (err) { 515 console.error(`Failed to convert to text. Cause: ${err.message}`); 516 return; 517 } 518 console.info(`Succeeded in converting to text. Data: ${data}`); 519}); 520``` 521 522### convertToText<sup>(deprecated)</sup> 523 524convertToText(): Promise<string> 525 526Forcibly converts the content in a **PasteData** object to text. This API uses a promise to return the result. 527> **NOTE** 528> 529> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [toPlainText](#toplaintext9). 530 531**System capability**: SystemCapability.MiscServices.Pasteboard 532 533**Return value** 534 535| Type| Description| 536| -------- | -------- | 537| Promise<string> | Promise used to return the text obtained from the conversion.| 538 539**Example** 540 541```ts 542import { BusinessError } from '@kit.BasicServicesKit'; 543 544let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 545record.convertToText().then((data: string) => { 546 console.info(`Succeeded in converting to text. Data: ${data}`); 547}).catch((err: BusinessError) => { 548 console.error(`Failed to convert to text. Cause: ${err.message}`); 549}); 550``` 551 552## PasteData 553 554Implements a **PasteData** object. Paste data contains one or more data records ([PasteDataRecord](#pastedatarecord7)) and property description objects ([PasteDataProperty](#pastedataproperty7)). 555 556Before calling any API in **PasteData**, you must use **[createData()](#pasteboardcreatedata9)** or **[getData()](#getdata9)** to create a **PasteData** object. 557 558**System capability**: SystemCapability.MiscServices.Pasteboard 559 560### getPrimaryText 561 562getPrimaryText(): string 563 564Obtains the plain text of the primary record. 565 566**Atomic service API**: This API can be used in atomic services since API version 11. 567 568**System capability**: SystemCapability.MiscServices.Pasteboard 569 570**Return value** 571 572| Type| Description| 573| -------- | -------- | 574| string | Plain text.| 575 576**Example** 577 578```ts 579let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 580let plainText: string = pasteData.getPrimaryText(); 581``` 582 583### getPrimaryHtml<sup>7+</sup> 584 585getPrimaryHtml(): string 586 587Obtains the HTML content of the primary record. 588 589**Atomic service API**: This API can be used in atomic services since API version 11. 590 591**System capability**: SystemCapability.MiscServices.Pasteboard 592 593**Return value** 594 595| Type| Description| 596| -------- | -------- | 597| string | HTML content.| 598 599**Example** 600 601```ts 602let 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>"; 603let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, html); 604let htmlText: string = pasteData.getPrimaryHtml(); 605``` 606 607### getPrimaryWant<sup>7+</sup> 608 609getPrimaryWant(): Want 610 611Obtains the Want object of the primary record. 612 613**Atomic service API**: This API can be used in atomic services since API version 11. 614 615**System capability**: SystemCapability.MiscServices.Pasteboard 616 617**Return value** 618 619| Type| Description| 620| -------- | -------- | 621| [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Want object.| 622 623**Example** 624 625```ts 626import { Want } from '@kit.AbilityKit'; 627 628let object: Want = { 629 bundleName: "com.example.aafwk.test", 630 abilityName: "com.example.aafwk.test.TwoAbility" 631}; 632let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_WANT, object); 633let want: Want = pasteData.getPrimaryWant(); 634``` 635 636### getPrimaryUri<sup>7+</sup> 637 638getPrimaryUri(): string 639 640Obtains the URI of the primary record. 641 642**Atomic service API**: This API can be used in atomic services since API version 11. 643 644**System capability**: SystemCapability.MiscServices.Pasteboard 645 646**Return value** 647 648| Type| Description| 649| -------- | -------- | 650| string | URI content.| 651 652**Example** 653 654```ts 655let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 656let uri: string = pasteData.getPrimaryUri(); 657``` 658 659### getPrimaryPixelMap<sup>9+</sup> 660 661getPrimaryPixelMap(): image.PixelMap 662 663Obtains the pixel map of the primary record. 664 665**Atomic service API**: This API can be used in atomic services since API version 11. 666 667**System capability**: SystemCapability.MiscServices.Pasteboard 668 669**Return value** 670 671| Type| Description| 672| -------- | -------- | 673| [image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7) | Pixel map.| 674 675**Example** 676 677```ts 678import { image } from '@kit.ImageKit'; 679 680let buffer = new ArrayBuffer(128); 681let realSize: image.Size = { height: 3, width: 5 }; 682let opt: image.InitializationOptions = { 683 size: realSize, 684 pixelFormat: 3, 685 editable: true, 686 alphaType: 1, 687 scaleMode: 1 688}; 689image.createPixelMap(buffer, opt).then((pixelMap: image.PixelMap) => { 690 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP, pixelMap); 691 let PixelMap: image.PixelMap = pasteData.getPrimaryPixelMap(); 692}); 693``` 694 695### addRecord<sup>7+</sup> 696 697addRecord(record: PasteDataRecord): void 698 699Adds a data record to this pasteboard, and adds its type to **mimeTypes** in [PasteDataProperty](#pastedataproperty7). The parameters cannot be empty. Otherwise, the operation fails. 700 701**Atomic service API**: This API can be used in atomic services since API version 11. 702 703**System capability**: SystemCapability.MiscServices.Pasteboard 704 705**Parameters** 706 707| Name| Type| Mandatory| Description| 708| -------- | -------- | -------- | -------- | 709| record | [PasteDataRecord](#pastedatarecord7) | Yes| Record to add.| 710 711**Example** 712 713```ts 714let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 715let textRecord: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 716let 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>"; 717let htmlRecord: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_HTML, html); 718pasteData.addRecord(textRecord); 719pasteData.addRecord(htmlRecord); 720``` 721### addRecord<sup>9+</sup> 722 723addRecord(mimeType: string, value: ValueType): void 724 725Adds 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. 726 727**Atomic service API**: This API can be used in atomic services since API version 11. 728 729**System capability**: SystemCapability.MiscServices.Pasteboard 730 731**Parameters** 732 733| Name| Type| Mandatory| Description| 734| -------- | -------- | -------- | -------- | 735| mimeType | string | Yes| MIME type of custom data. The length cannot exceed 1024 bytes.| 736| value | [ValueType](#valuetype9) | Yes| Content of custom data.| 737 738**Error codes** 739 740For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 741 742| Error Code ID| Error Message| 743| -------- | -------- | 744| 12900002 | The number of records exceeds the upper limit. | 745| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 746 747**Example** 748 749 ```ts 750 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 751 let dataXml = new ArrayBuffer(256); 752 pasteData.addRecord('app/xml', dataXml); 753 ``` 754 755### getMimeTypes<sup>7+</sup> 756 757getMimeTypes(): Array<string> 758 759Obtains a list of **mimeTypes** objects in [PasteDataProperty](#pastedataproperty7) from this pasteboard. If the pasteboard is empty, the returned list is also empty. 760 761**Atomic service API**: This API can be used in atomic services since API version 11. 762 763**System capability**: SystemCapability.MiscServices.Pasteboard 764 765**Return value** 766 767| Type| Description| 768| -------- | -------- | 769| Array<string> | Non-repeating data types of the data records on the pasteboard.| 770 771**Example** 772 773```ts 774let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 775let types: string[] = pasteData.getMimeTypes(); 776``` 777 778### getPrimaryMimeType<sup>7+</sup> 779 780getPrimaryMimeType(): string 781 782Obtains the data type of the primary record in this pasteboard. 783 784**Atomic service API**: This API can be used in atomic services since API version 11. 785 786**System capability**: SystemCapability.MiscServices.Pasteboard 787 788**Return value** 789 790| Type| Description| 791| -------- | -------- | 792| string | Data type of the primary record.| 793 794**Example** 795 796```ts 797let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 798let type: string = pasteData.getPrimaryMimeType(); 799``` 800 801### getProperty<sup>7+</sup> 802 803getProperty(): PasteDataProperty 804 805Obtains the property of the pasteboard data. 806 807**Atomic service API**: This API can be used in atomic services since API version 11. 808 809**System capability**: SystemCapability.MiscServices.Pasteboard 810 811**Return value** 812 813| Type| Description| 814| -------- | -------- | 815| [PasteDataProperty](#pastedataproperty7) | Property of the pasteboard data.| 816 817**Example** 818 819```ts 820let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 821let property: pasteboard.PasteDataProperty = pasteData.getProperty(); 822``` 823 824### setProperty<sup>9+</sup> 825 826setProperty(property: PasteDataProperty): void 827 828Sets a [PasteDataProperty](#pastedataproperty7) object. 829 830**Atomic service API**: This API can be used in atomic services since API version 11. 831 832**System capability**: SystemCapability.MiscServices.Pasteboard 833 834**Parameters** 835 836| Name| Type| Mandatory| Description| 837| -------- | -------- | -------- | -------- | 838| property | [PasteDataProperty](#pastedataproperty7) | Yes| Property of the pasteboard data.| 839 840**Error codes** 841 842For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 843 844| Error Code ID| Error Message| 845| -------- | -------- | 846| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 847 848**Example** 849 850```ts 851type AdditionType = Record<string, Record<string, Object>>; 852 853let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml'); 854let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 855prop.shareOption = pasteboard.ShareOption.INAPP; 856// Note that attributes cannot be added to additions. Attributes can be added only by re-assigning values. 857prop.additions = { 'TestOne': { 'Test': 123 }, 'TestTwo': { 'Test': 'additions' } } as AdditionType; 858prop.tag = 'TestTag'; 859pasteData.setProperty(prop); 860``` 861The **localOnly** and **shareOption** attributes of [PasteDataProperty](#pastedataproperty7) are mutually exclusive. The **shareOption** attribute is prioritized, and its value affects the value of **localOnly**. 862```ts 863(async () => { 864 let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 865 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 866 prop.shareOption = pasteboard.ShareOption.INAPP; 867 prop.localOnly = false; 868 pasteData.setProperty(prop); 869 let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 870 871 await systemPasteboard.setData(pasteData).then(async () => { 872 console.info('Succeeded in setting PasteData.'); 873 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 874 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 875 prop.localOnly; // true 876 }); 877 }); 878 879 prop.shareOption = pasteboard.ShareOption.LOCALDEVICE; 880 prop.localOnly = false; 881 pasteData.setProperty(prop); 882 883 await systemPasteboard.setData(pasteData).then(async () => { 884 console.info('Succeeded in setting PasteData.'); 885 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 886 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 887 prop.localOnly; // true 888 }); 889 }); 890 891 prop.shareOption = pasteboard.ShareOption.CROSSDEVICE; 892 prop.localOnly = true; 893 pasteData.setProperty(prop); 894 895 await systemPasteboard.setData(pasteData).then(async () => { 896 console.info('Succeeded in setting PasteData.'); 897 await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 898 let prop: pasteboard.PasteDataProperty = pasteData.getProperty(); 899 prop.localOnly; // false 900 }); 901 }); 902})() 903``` 904 905### getRecord<sup>9+</sup> 906 907getRecord(index: number): PasteDataRecord 908 909Obtains the specified record in the pasteboard. 910 911**Atomic service API**: This API can be used in atomic services since API version 11. 912 913**System capability**: SystemCapability.MiscServices.Pasteboard 914 915**Parameters** 916 917| Name| Type| Mandatory| Description| 918| -------- | -------- | -------- | -------- | 919| index | number | Yes| Index of the target record.| 920 921**Return value** 922 923| Type| Description| 924| -------- | -------- | 925| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| 926 927**Error codes** 928 929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 930 931| Error Code ID| Error Message| 932| -------- | -------- | 933| 12900001 | The index is out of the record. | 934| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 935 936**Example** 937 938```ts 939let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 940let record: pasteboard.PasteDataRecord = pasteData.getRecord(0); 941``` 942 943### getRecordCount<sup>7+</sup> 944 945getRecordCount(): number 946 947Obtains the number of records in the pasteboard. 948 949**Atomic service API**: This API can be used in atomic services since API version 11. 950 951**System capability**: SystemCapability.MiscServices.Pasteboard 952 953**Return value** 954 955| Type| Description| 956| -------- | -------- | 957| number | Number of records.| 958 959**Example** 960 961```ts 962let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 963let count: number = pasteData.getRecordCount(); 964``` 965 966### getTag<sup>7+</sup> 967 968getTag(): string 969 970Obtains the custom tag from the pasteboard. If no custom tag is set, null is returned. 971 972**Atomic service API**: This API can be used in atomic services since API version 11. 973 974**System capability**: SystemCapability.MiscServices.Pasteboard 975 976**Return value** 977 978| Type| Description| 979| -------- | -------- | 980| string | Custom tag. If no custom tag is set, null is returned.| 981 982**Example** 983 984```ts 985let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 986let tag: string = pasteData.getTag(); 987``` 988 989### hasType<sup>9+</sup> 990 991hasType(mimeType: string): boolean 992 993Checks whether the pasteboard contains data of the specified type. 994 995**Atomic service API**: This API can be used in atomic services since API version 11. 996 997**System capability**: SystemCapability.MiscServices.Pasteboard 998 999**Parameters** 1000 1001| Name| Type| Mandatory| Description| 1002| -------- | -------- | -------- | -------- | 1003| mimeType | string | Yes| Type of the data to query.| 1004 1005**Return value** 1006 1007| Type| Description| 1008| -------- | -------- | 1009| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.| 1010 1011**Error codes** 1012 1013For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1014 1015| Error Code ID| Error Message| 1016| -------- | -------- | 1017| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1018 1019**Example** 1020 1021```ts 1022let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1023let hasType: boolean = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); 1024``` 1025 1026### removeRecord<sup>9+</sup> 1027 1028removeRecord(index: number): void 1029 1030Removes the record with the specified index from the pasteboard. 1031 1032**Atomic service API**: This API can be used in atomic services since API version 11. 1033 1034**System capability**: SystemCapability.MiscServices.Pasteboard 1035 1036**Parameters** 1037 1038| Name| Type| Mandatory| Description| 1039| -------- | -------- | -------- | -------- | 1040| index | number | Yes| Specified index.| 1041 1042**Error codes** 1043 1044For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1045 1046| Error Code ID| Error Message| 1047| -------- | -------- | 1048| 12900001 | The index is out of the record. | 1049| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1050 1051**Example** 1052 1053```ts 1054let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1055pasteData.removeRecord(0); 1056``` 1057 1058### replaceRecord<sup>9+</sup> 1059 1060replaceRecord(index: number, record: PasteDataRecord): void 1061 1062Replaces the record with the specified index in the pasteboard with a new record. 1063 1064**Atomic service API**: This API can be used in atomic services since API version 11. 1065 1066**System capability**: SystemCapability.MiscServices.Pasteboard 1067 1068**Parameters** 1069 1070| Name| Type| Mandatory| Description| 1071| -------- | -------- | -------- | -------- | 1072| index | number | Yes| Specified index.| 1073| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| 1074 1075**Error codes** 1076 1077For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1078 1079| Error Code ID| Error Message| 1080| -------- | -------- | 1081| 12900001 | The index is out of the record. | 1082| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1083 1084**Example** 1085 1086```ts 1087let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 1088let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 1089pasteData.replaceRecord(0, record); 1090``` 1091### addHtmlRecord<sup>(deprecated)</sup> 1092 1093addHtmlRecord(htmlText: string): void 1094 1095Adds 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. 1096 1097> **NOTE** 1098> 1099> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1100 1101**System capability**: SystemCapability.MiscServices.Pasteboard 1102 1103**Parameters** 1104 1105| Name| Type| Mandatory| Description| 1106| -------- | -------- | -------- | -------- | 1107| htmlText | string | Yes| HTML content.| 1108 1109**Example** 1110 1111```ts 1112let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1113let 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>"; 1114pasteData.addHtmlRecord(html); 1115``` 1116 1117### addWantRecord<sup>(deprecated)</sup> 1118 1119addWantRecord(want: Want): void 1120 1121Adds 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. 1122 1123> **NOTE** 1124> 1125> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1126 1127**System capability**: SystemCapability.MiscServices.Pasteboard 1128 1129**Parameters** 1130 1131| Name| Type| Mandatory| Description| 1132| -------- | -------- | -------- | -------- | 1133| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes| Want object.| 1134 1135**Example** 1136 1137```ts 1138import { Want } from '@kit.AbilityKit'; 1139 1140let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1141let object: Want = { 1142 bundleName: "com.example.aafwk.test", 1143 abilityName: "com.example.aafwk.test.TwoAbility" 1144}; 1145pasteData.addWantRecord(object); 1146``` 1147 1148### addTextRecord<sup>(deprecated)</sup> 1149 1150addTextRecord(text: string): void 1151 1152Adds 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. 1153 1154> **NOTE** 1155> 1156> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1157 1158**System capability**: SystemCapability.MiscServices.Pasteboard 1159 1160**Parameters** 1161 1162| Name| Type| Mandatory| Description| 1163| -------- | -------- | -------- | -------- | 1164| text | string | Yes| Plain text.| 1165 1166**Example** 1167 1168```ts 1169let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1170pasteData.addTextRecord('good'); 1171``` 1172 1173### addUriRecord<sup>(deprecated)</sup> 1174 1175addUriRecord(uri: string): void 1176 1177Adds 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. 1178 1179> **NOTE** 1180> 1181> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [addRecord](#addrecord9). 1182 1183**System capability**: SystemCapability.MiscServices.Pasteboard 1184 1185**Parameters** 1186 1187| Name| Type| Mandatory| Description| 1188| -------- | -------- | -------- | -------- | 1189| uri | string | Yes| URI content.| 1190 1191**Example** 1192 1193```ts 1194let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1195pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt'); 1196``` 1197### getRecordAt<sup>(deprecated)</sup> 1198 1199getRecordAt(index: number): PasteDataRecord 1200 1201Obtains the specified record in the pasteboard. 1202> **NOTE** 1203> 1204> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRecord](#getrecord9). 1205 1206**System capability**: SystemCapability.MiscServices.Pasteboard 1207 1208**Parameters** 1209 1210| Name| Type| Mandatory| Description| 1211| -------- | -------- | -------- | -------- | 1212| index | number | Yes| Index of the target record.| 1213 1214**Return value** 1215 1216| Type| Description| 1217| -------- | -------- | 1218| [PasteDataRecord](#pastedatarecord7) | Record with the specified index.| 1219 1220**Error codes** 1221 1222For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1223 1224| Error Code ID| Error Message| 1225| -------- | -------- | 1226| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1227 1228**Example** 1229 1230```ts 1231let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1232let record: pasteboard.PasteDataRecord = pasteData.getRecordAt(0); 1233``` 1234 1235### hasMimeType<sup>(deprecated)</sup> 1236 1237hasMimeType(mimeType: string): boolean 1238 1239Checks whether the pasteboard contains data of the specified type. 1240> **NOTE** 1241> 1242> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasType](#hastype9). 1243 1244**System capability**: SystemCapability.MiscServices.Pasteboard 1245 1246**Parameters** 1247 1248| Name| Type| Mandatory| Description| 1249| -------- | -------- | -------- | -------- | 1250| mimeType | string | Yes| Type of the data to query.| 1251 1252**Return value** 1253 1254| Type| Description| 1255| -------- | -------- | 1256| boolean | Returns **true** if the specified data type exists; returns **false** otherwise.| 1257 1258**Error codes** 1259 1260For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1261 1262| Error Code ID| Error Message| 1263| -------- | -------- | 1264| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1265 1266**Example** 1267 1268```ts 1269let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1270let hasType: boolean = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); 1271``` 1272### removeRecordAt<sup>(deprecated)</sup> 1273 1274removeRecordAt(index: number): boolean 1275 1276Removes the record with the specified index from the pasteboard. 1277> **NOTE** 1278> 1279> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [removeRecord](#removerecord9). 1280 1281**System capability**: SystemCapability.MiscServices.Pasteboard 1282 1283**Parameters** 1284 1285| Name| Type| Mandatory| Description| 1286| -------- | -------- | -------- | -------- | 1287| index | number | Yes| Specified index.| 1288 1289**Return value** 1290 1291| Type| Description| 1292| -------- | -------- | 1293| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1294 1295**Error codes** 1296 1297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1298 1299| Error Code ID| Error Message| 1300| -------- | -------- | 1301| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1302 1303**Example** 1304 1305```ts 1306let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1307let isRemove: boolean = pasteData.removeRecordAt(0); 1308``` 1309### replaceRecordAt<sup>(deprecated)</sup> 1310 1311replaceRecordAt(index: number, record: PasteDataRecord): boolean 1312 1313Replaces the record with the specified index in the pasteboard with a new record. 1314> **NOTE** 1315> 1316> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [replaceRecord](#replacerecord9). 1317 1318**System capability**: SystemCapability.MiscServices.Pasteboard 1319 1320**Parameters** 1321 1322| Name| Type| Mandatory| Description| 1323| -------- | -------- | -------- | -------- | 1324| index | number | Yes| Specified index.| 1325| record | [PasteDataRecord](#pastedatarecord7) | Yes| New record.| 1326 1327**Return value** 1328 1329| Type| Description| 1330| -------- | -------- | 1331| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| 1332 1333**Example** 1334 1335```ts 1336let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello'); 1337let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 1338let isReplace: boolean = pasteData.replaceRecordAt(0, record); 1339``` 1340 1341## SystemPasteboard 1342 1343Provides **SystemPasteboard** APIs. 1344 1345Before calling any **SystemPasteboard** API, you must obtain a **SystemPasteboard** object using [getSystemPasteboard](#pasteboardgetsystempasteboard). 1346 1347```ts 1348let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1349``` 1350 1351### on('update')<sup>7+</sup> 1352 1353on(type: 'update', callback: () =>void ): void 1354 1355Subscribes to the content change event of the system pasteboard. 1356 1357**System capability**: SystemCapability.MiscServices.Pasteboard 1358 1359**Parameters** 1360 1361| Name| Type| Mandatory| Description| 1362| -------- | -------- | -------- | -------- | 1363| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content.| 1364| callback | function | Yes| Callback invoked when the pasteboard content changes.| 1365 1366**Error codes** 1367 1368For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1369 1370| Error Code ID| Error Message| 1371| -------- | -------- | 1372| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1373 1374**Example** 1375 1376```ts 1377let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1378let listener = () => { 1379 console.info('The system pasteboard has changed.'); 1380}; 1381systemPasteboard.on('update', listener); 1382``` 1383 1384### off('update')<sup>7+</sup> 1385 1386off(type: 'update', callback?: () =>void ): void 1387 1388Unsubscribes from the system pasteboard content change event. 1389 1390**System capability**: SystemCapability.MiscServices.Pasteboard 1391 1392**Parameters** 1393 1394| Name| Type| Mandatory| Description | 1395| -------- | -------- | -------- |---------------------------------------------------------| 1396| type | string | Yes| Event type. The value **'update'** indicates changes in the pasteboard content. | 1397| 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.| 1398 1399**Error codes** 1400 1401For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1402 1403| Error Code ID| Error Message| 1404| -------- | -------- | 1405| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1406 1407**Example** 1408 1409```ts 1410let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1411let listener = () => { 1412 console.info('The system pasteboard has changed.'); 1413}; 1414systemPasteboard.off('update', listener); 1415``` 1416 1417### clearData<sup>9+</sup> 1418 1419clearData(callback: AsyncCallback<void>): void 1420 1421Clears the system pasteboard. This API uses an asynchronous callback to return the result. 1422 1423**Atomic service API**: This API can be used in atomic services since API version 11. 1424 1425**System capability**: SystemCapability.MiscServices.Pasteboard 1426 1427**Parameters** 1428 1429| Name| Type| Mandatory| Description| 1430| -------- | -------- | -------- | -------- | 1431| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1432 1433**Error codes** 1434 1435For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1436 1437| Error Code ID| Error Message| 1438| -------- | -------- | 1439| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1440 1441**Example** 1442 1443```ts 1444let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1445systemPasteboard.clearData((err, data) => { 1446 if (err) { 1447 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1448 return; 1449 } 1450 console.info('Succeeded in clearing the pasteboard.'); 1451}); 1452``` 1453 1454### clearData<sup>9+</sup> 1455 1456clearData(): Promise<void> 1457 1458Clears the system pasteboard. This API uses a promise to return the result. 1459 1460**Atomic service API**: This API can be used in atomic services since API version 11. 1461 1462**System capability**: SystemCapability.MiscServices.Pasteboard 1463 1464**Return value** 1465 1466| Type| Description| 1467| -------- | -------- | 1468| Promise<void> | Promise that returns no value.| 1469 1470**Example** 1471 1472```ts 1473import { BusinessError } from '@kit.BasicServicesKit'; 1474 1475let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1476systemPasteboard.clearData().then((data: void) => { 1477 console.info('Succeeded in clearing the pasteboard.'); 1478}).catch((err: BusinessError) => { 1479 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1480}); 1481``` 1482 1483### setData<sup>9+</sup> 1484 1485setData(data: PasteData, callback: AsyncCallback<void>): void 1486 1487Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. 1488 1489**Atomic service API**: This API can be used in atomic services since API version 11. 1490 1491**System capability**: SystemCapability.MiscServices.Pasteboard 1492 1493**Parameters** 1494 1495| Name| Type| Mandatory| Description| 1496| -------- | -------- | -------- | -------- | 1497| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1498| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1499 1500**Error codes** 1501 1502For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1503 1504| Error Code ID| Error Message| 1505| -------- | -------- | 1506| 12900003 | Another copy or paste operation is in progress. | 1507| 12900004 | Replication is prohibited. | 1508| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1509 1510**Example** 1511 1512```ts 1513let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1514let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1515systemPasteboard.setData(pasteData, (err, data) => { 1516 if (err) { 1517 console.error('Failed to set PasteData. Cause: ' + err.message); 1518 return; 1519 } 1520 console.info('Succeeded in setting PasteData.'); 1521}); 1522``` 1523 1524### setData<sup>9+</sup> 1525 1526setData(data: PasteData): Promise<void> 1527 1528Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 1529 1530**Atomic service API**: This API can be used in atomic services since API version 11. 1531 1532**System capability**: SystemCapability.MiscServices.Pasteboard 1533 1534**Parameters** 1535 1536| Name| Type| Mandatory| Description| 1537| -------- | -------- | -------- | -------- | 1538| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1539 1540**Return value** 1541 1542| Type| Description| 1543| -------- | -------- | 1544| Promise<void> | Promise that returns no value.| 1545 1546**Error codes** 1547 1548For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1549 1550| Error Code ID| Error Message| 1551| -------- | -------- | 1552| 12900003 | Another copy or paste operation is in progress. | 1553| 12900004 | Replication is prohibited. | 1554| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1555 1556**Example** 1557 1558```ts 1559import { BusinessError } from '@kit.BasicServicesKit'; 1560 1561let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1562let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1563systemPasteboard.setData(pasteData).then((data: void) => { 1564 console.info('Succeeded in setting PasteData.'); 1565}).catch((err: BusinessError) => { 1566 console.error('Failed to set PasteData. Cause: ' + err.message); 1567}); 1568``` 1569 1570### getData<sup>9+</sup> 1571 1572getData( callback: AsyncCallback<PasteData>): void 1573 1574Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. 1575 1576**Required permissions**: ohos.permission.READ_PASTEBOARD 1577 1578**Atomic service API**: This API can be used in atomic services since API version 11. 1579 1580**System capability**: SystemCapability.MiscServices.Pasteboard 1581 1582**Parameters** 1583 1584| Name| Type| Mandatory| Description| 1585| -------- | -------- | -------- | -------- | 1586| 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.| 1587 1588**Error codes** 1589 1590For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1591 1592| Error Code ID| Error Message| 1593| -------- | -------- | 1594| 12900003 | Another copy or paste operation is in progress. | 1595| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1596 1597**Example** 1598 1599```ts 1600import { BusinessError } from '@kit.BasicServicesKit'; 1601 1602let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1603systemPasteboard.getData((err: BusinessError, pasteData: pasteboard.PasteData) => { 1604 if (err) { 1605 console.error('Failed to get PasteData. Cause: ' + err.message); 1606 return; 1607 } 1608 let text: string = pasteData.getPrimaryText(); 1609}); 1610``` 1611 1612### getData<sup>9+</sup> 1613 1614getData(): Promise<PasteData> 1615 1616Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 1617 1618**Required permissions**: ohos.permission.READ_PASTEBOARD 1619 1620**Atomic service API**: This API can be used in atomic services since API version 11. 1621 1622**System capability**: SystemCapability.MiscServices.Pasteboard 1623 1624**Return value** 1625 1626| Type| Description| 1627| -------- | -------- | 1628| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| 1629 1630**Error codes** 1631 1632For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 1633 1634| Error Code ID| Error Message| 1635| -------- | -------- | 1636| 12900003 | Another copy or paste operation is in progress. | 1637| 201 | Permission verification failed. The application does not have the permission required to call the API. | 1638 1639**Example** 1640 1641```ts 1642import { BusinessError } from '@kit.BasicServicesKit'; 1643 1644let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1645systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => { 1646 let text: string = pasteData.getPrimaryText(); 1647}).catch((err: BusinessError) => { 1648 console.error('Failed to get PasteData. Cause: ' + err.message); 1649}); 1650``` 1651 1652### hasData<sup>9+</sup> 1653 1654hasData(callback: AsyncCallback<boolean>): void 1655 1656Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. 1657 1658**Atomic service API**: This API can be used in atomic services since API version 11. 1659 1660**System capability**: SystemCapability.MiscServices.Pasteboard 1661 1662**Parameters** 1663 1664| Name| Type| Mandatory| Description| 1665| -------- | -------- | -------- | -------- | 1666| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 1667 1668**Error codes** 1669 1670For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1671 1672| Error Code ID| Error Message| 1673| -------- | -------- | 1674| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1675 1676**Example** 1677 1678```ts 1679import { BusinessError } from '@kit.BasicServicesKit'; 1680 1681let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1682systemPasteboard.hasData((err: BusinessError, data: boolean) => { 1683 if (err) { 1684 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1685 return; 1686 } 1687 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1688}); 1689``` 1690 1691### hasData<sup>9+</sup> 1692 1693hasData(): Promise<boolean> 1694 1695Checks whether the system pasteboard contains data. This API uses a promise to return the result. 1696 1697**Atomic service API**: This API can be used in atomic services since API version 11. 1698 1699**System capability**: SystemCapability.MiscServices.Pasteboard 1700 1701**Return value** 1702 1703| Type| Description| 1704| -------- | -------- | 1705| Promise<boolean> | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 1706 1707**Example** 1708 1709```ts 1710import { BusinessError } from '@kit.BasicServicesKit'; 1711 1712let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1713systemPasteboard.hasData().then((data: boolean) => { 1714 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1715}).catch((err: BusinessError) => { 1716 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1717}); 1718``` 1719 1720### clear<sup>(deprecated)</sup> 1721 1722clear(callback: AsyncCallback<void>): void 1723 1724Clears the system pasteboard. This API uses an asynchronous callback to return the result. 1725> **NOTE** 1726> 1727> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9). 1728 1729**System capability**: SystemCapability.MiscServices.Pasteboard 1730 1731**Parameters** 1732 1733| Name| Type| Mandatory| Description| 1734| -------- | -------- | -------- | -------- | 1735| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1736 1737**Error codes** 1738 1739For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1740 1741| Error Code ID| Error Message| 1742| -------- | -------- | 1743| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1744 1745**Example** 1746 1747```ts 1748let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1749systemPasteboard.clear((err, data) => { 1750 if (err) { 1751 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 1752 return; 1753 } 1754 console.info('Succeeded in clearing the PasteData.'); 1755}); 1756``` 1757 1758### clear<sup>(deprecated)</sup> 1759 1760clear(): Promise<void> 1761 1762Clears the system pasteboard. This API uses a promise to return the result. 1763> **NOTE** 1764> 1765> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [pasteboard.clearData](#cleardata9-1). 1766 1767**System capability**: SystemCapability.MiscServices.Pasteboard 1768 1769**Return value** 1770 1771| Type| Description| 1772| -------- | -------- | 1773| Promise<void> | Promise that returns no value.| 1774 1775**Example** 1776 1777```ts 1778import { BusinessError } from '@kit.BasicServicesKit'; 1779 1780let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1781systemPasteboard.clear().then((data) => { 1782 console.info('Succeeded in clearing the PasteData.'); 1783}).catch((err: BusinessError) => { 1784 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 1785}); 1786``` 1787 1788### getPasteData<sup>(deprecated)</sup> 1789 1790getPasteData( callback: AsyncCallback<PasteData>): void 1791 1792Obtains a **PasteData** object from the pasteboard. This API uses an asynchronous callback to return the result. 1793> **NOTE** 1794> 1795> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9). 1796 1797**System capability**: SystemCapability.MiscServices.Pasteboard 1798 1799**Parameters** 1800 1801| Name| Type| Mandatory| Description| 1802| -------- | -------- | -------- | -------- | 1803| 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.| 1804 1805**Error codes** 1806 1807For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1808 1809| Error Code ID| Error Message| 1810| -------- | -------- | 1811| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1812 1813**Example** 1814 1815```ts 1816import { BusinessError } from '@kit.BasicServicesKit'; 1817 1818let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1819systemPasteboard.getPasteData((err: BusinessError, pasteData: pasteboard.PasteData) => { 1820 if (err) { 1821 console.error('Failed to get PasteData. Cause: ' + err.message); 1822 return; 1823 } 1824 let text: string = pasteData.getPrimaryText(); 1825}); 1826``` 1827 1828### getPasteData<sup>(deprecated)</sup> 1829 1830getPasteData(): Promise<PasteData> 1831 1832Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 1833> **NOTE** 1834> 1835> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [getData](#getdata9-1). 1836 1837**System capability**: SystemCapability.MiscServices.Pasteboard 1838 1839**Return value** 1840 1841| Type| Description| 1842| -------- | -------- | 1843| Promise<[PasteData](#pastedata)> | Promise used to return the system pasteboard data.| 1844 1845**Example** 1846 1847```ts 1848import { BusinessError } from '@kit.BasicServicesKit'; 1849 1850let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1851systemPasteboard.getPasteData().then((pasteData: pasteboard.PasteData) => { 1852 let text: string = pasteData.getPrimaryText(); 1853}).catch((err: BusinessError) => { 1854 console.error('Failed to get PasteData. Cause: ' + err.message); 1855}); 1856``` 1857 1858### hasPasteData<sup>(deprecated)</sup> 1859 1860hasPasteData(callback: AsyncCallback<boolean>): void 1861 1862Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result. 1863> **NOTE** 1864> 1865> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9). 1866 1867**System capability**: SystemCapability.MiscServices.Pasteboard 1868 1869**Parameters** 1870 1871| Name| Type| Mandatory| Description| 1872| -------- | -------- | -------- | -------- | 1873| callback | AsyncCallback<boolean> | Yes| Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 1874 1875**Error codes** 1876 1877For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1878 1879| Error Code ID| Error Message| 1880| -------- | -------- | 1881| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1882 1883**Example** 1884 1885```ts 1886import { BusinessError } from '@kit.BasicServicesKit'; 1887 1888let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1889systemPasteboard.hasPasteData((err: BusinessError, data: boolean) => { 1890 if (err) { 1891 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1892 return; 1893 } 1894 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1895}); 1896``` 1897 1898### hasPasteData<sup>(deprecated)</sup> 1899 1900hasPasteData(): Promise<boolean> 1901 1902Checks whether the system pasteboard contains data. This API uses a promise to return the result. 1903> **NOTE** 1904> 1905> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [hasData](#hasdata9-1). 1906 1907**System capability**: SystemCapability.MiscServices.Pasteboard 1908 1909**Return value** 1910 1911| Type| Description| 1912| -------- | -------- | 1913| Promise<boolean> | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 1914 1915**Example** 1916 1917```ts 1918import { BusinessError } from '@kit.BasicServicesKit'; 1919 1920let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1921systemPasteboard.hasPasteData().then((data: boolean) => { 1922 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1923}).catch((err: BusinessError) => { 1924 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1925}); 1926``` 1927 1928### setPasteData<sup>(deprecated)</sup> 1929 1930setPasteData(data: PasteData, callback: AsyncCallback<void>): void 1931 1932Writes a **PasteData** object to the pasteboard. This API uses an asynchronous callback to return the result. 1933> **NOTE** 1934> 1935> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setData](#setdata9). 1936 1937**System capability**: SystemCapability.MiscServices.Pasteboard 1938 1939**Parameters** 1940 1941| Name| Type| Mandatory| Description| 1942| -------- | -------- | -------- | -------- | 1943| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1944| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1945 1946**Error codes** 1947 1948For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1949 1950| Error Code ID| Error Message| 1951| -------- | -------- | 1952| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1953 1954**Example** 1955 1956```ts 1957let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 1958let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1959systemPasteboard.setPasteData(pasteData, (err, data) => { 1960 if (err) { 1961 console.error('Failed to set PasteData. Cause: ' + err.message); 1962 return; 1963 } 1964 console.info('Succeeded in setting PasteData.'); 1965}); 1966``` 1967### setPasteData<sup>(deprecated)</sup> 1968 1969setPasteData(data: PasteData): Promise<void> 1970 1971Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 1972> **NOTE** 1973> 1974> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [setData](#setdata9-1). 1975 1976**System capability**: SystemCapability.MiscServices.Pasteboard 1977 1978**Parameters** 1979 1980| Name| Type| Mandatory| Description| 1981| -------- | -------- | -------- | -------- | 1982| data | [PasteData](#pastedata) | Yes| **PasteData** object.| 1983 1984**Return value** 1985 1986| Type| Description| 1987| -------- | -------- | 1988| Promise<void> | Promise that returns no value.| 1989 1990**Example** 1991 1992```ts 1993import { BusinessError } from '@kit.BasicServicesKit'; 1994 1995let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('content'); 1996let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 1997systemPasteboard.setPasteData(pasteData).then((data: void) => { 1998 console.info('Succeeded in setting PasteData.'); 1999}).catch((err: BusinessError) => { 2000 console.error('Failed to set PasteData. Cause: ' + err.message); 2001}); 2002``` 2003### isRemoteData<sup>11+</sup> 2004 2005isRemoteData(): boolean 2006 2007Checks whether the data in the pasteboard is from another device. 2008 2009**Atomic service API**: This API can be used in atomic services since API version 11. 2010 2011**System capability**: SystemCapability.MiscServices.Pasteboard 2012 2013**Return value** 2014 2015| Type | Description | 2016| ------- | ------------------------------------- | 2017| boolean | Returns **true** if the data in the pasteboard is from another device; returns **false** otherwise.| 2018 2019**Error codes** 2020 2021For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2022 2023| Error Code ID| Error Message| 2024| -------- | -------- | 2025| 12900005 | Request timed out. | 2026 2027**Example** 2028 2029```ts 2030let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2031try { 2032 let result: boolean = systemPasteboard.isRemoteData(); 2033 console.info(`Succeeded in checking the RemoteData. Result: ${result}`); 2034} catch (err) { 2035 console.error('Failed to check the RemoteData. Cause:' + err.message); 2036}; 2037``` 2038 2039### getDataSource<sup>11+</sup> 2040 2041getDataSource(): string 2042 2043Obtains the data source. 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| string | Data source.| 2054 2055**Error codes** 2056 2057For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2058 2059| Error Code ID| Error Message| 2060| -------- | -------- | 2061| 12900005 | Request timed out. | 2062 2063**Example** 2064 2065```ts 2066let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2067try { 2068 let result: string = systemPasteboard.getDataSource(); 2069 console.info(`Succeeded in getting DataSource. Result: ${result}`); 2070} catch (err) { 2071 console.error('Failed to get DataSource. Cause:' + err.message); 2072}; 2073``` 2074 2075### hasDataType<sup>11+</sup> 2076 2077hasDataType(mimeType: string): boolean 2078 2079Checks whether the pasteboard contains data of the specified type. 2080 2081**Atomic service API**: This API can be used in atomic services since API version 11. 2082 2083**System capability**: SystemCapability.MiscServices.Pasteboard 2084 2085**Parameters** 2086 2087| Name | Type | Mandatory| Description | 2088| -------- | ------ | ---- | ------------------ | 2089| mimeType | string | Yes | Data type.| 2090 2091**Return value** 2092 2093| Type | Description | 2094| ------- | ------------------------------------------- | 2095| boolean | Returns **true** if the pasteboard contains data of the specified type; returns **false** otherwise.| 2096 2097**Error codes** 2098 2099For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2100 2101| Error Code ID| Error Message| 2102| -------- | -------- | 2103| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2104| 12900005 | Request timed out. | 2105 2106**Example** 2107 2108```ts 2109let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2110try { 2111 let result: boolean = systemPasteboard.hasDataType(pasteboard.MIMETYPE_TEXT_PLAIN); 2112 console.info(`Succeeded in checking the DataType. Result: ${result}`); 2113} catch (err) { 2114 console.error('Failed to check the DataType. Cause:' + err.message); 2115}; 2116``` 2117 2118### clearDataSync<sup>11+</sup> 2119 2120clearDataSync(): void 2121 2122Clears the system pasteboard. This API returns the result synchronously. 2123 2124**Atomic service API**: This API can be used in atomic services since API version 11. 2125 2126**System capability**: SystemCapability.MiscServices.Pasteboard 2127 2128**Error codes** 2129 2130For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2131 2132| Error Code ID| Error Message| 2133| -------- | -------- | 2134| 12900005 | Request timed out. | 2135 2136**Example** 2137 2138```ts 2139let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2140try { 2141 systemPasteboard.clearDataSync(); 2142 console.info('Succeeded in clearing the pasteboard.'); 2143} catch (err) { 2144 console.error('Failed to clear the pasteboard. Cause:' + err.message); 2145}; 2146``` 2147 2148### getDataSync<sup>11+</sup> 2149 2150getDataSync(): PasteData 2151 2152Reads data in the system pasteboard. This API returns the result synchronously. 2153 2154**Required permissions**: ohos.permission.READ_PASTEBOARD 2155 2156**Atomic service API**: This API can be used in atomic services since API version 11. 2157 2158**System capability**: SystemCapability.MiscServices.Pasteboard 2159 2160**Return value** 2161 2162| Type | Description | 2163| ----------------------- | -------------------- | 2164| [PasteData](#pastedata) | Data in the system pasteboard.| 2165 2166**Error codes** 2167 2168For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2169 2170| Error Code ID| Error Message| 2171| -------- | -------- | 2172| 12900005 | Request timed out. | 2173| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2174 2175**Example** 2176 2177```ts 2178let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2179try { 2180 let result: pasteboard.PasteData = systemPasteboard.getDataSync(); 2181 console.info('Succeeded in getting PasteData.'); 2182} catch (err) { 2183 console.error('Failed to get PasteData. Cause:' + err.message); 2184}; 2185``` 2186 2187### setDataSync<sup>11+</sup> 2188 2189setDataSync(data: PasteData): void 2190 2191Writes data to the system pasteboard. This API returns the result synchronously. 2192 2193**Atomic service API**: This API can be used in atomic services since API version 11. 2194 2195**System capability**: SystemCapability.MiscServices.Pasteboard 2196 2197**Parameters** 2198 2199| Name| Type | Mandatory| Description | 2200| ------ | ----------------------- | ---- | ---------------- | 2201| data | [PasteData](#pastedata) | Yes | Data to be written to the pasteboard.| 2202 2203**Error codes** 2204 2205For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Pasteboard Error Codes](errorcode-pasteboard.md). 2206 2207| Error Code ID| Error Message| 2208| -------- | -------- | 2209| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2210| 12900005 | Request timed out. | 2211 2212**Example** 2213 2214```ts 2215let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 2216let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2217try { 2218 systemPasteboard.setDataSync(pasteData); 2219 console.info('Succeeded in setting PasteData.'); 2220} catch (err) { 2221 console.error('Failed to set PasteData. Cause:' + err.message); 2222}; 2223``` 2224 2225### hasDataSync<sup>11+</sup> 2226 2227hasDataSync(): boolean 2228 2229Checks whether the system pasteboard contains data. This API returns the result synchronously. 2230 2231**Atomic service API**: This API can be used in atomic services since API version 11. 2232 2233**System capability**: SystemCapability.MiscServices.Pasteboard 2234 2235**Return value** 2236 2237| Type | Description | 2238| ------- | ----------------------------------------------------------------------- | 2239| boolean | Callback used to return the result. Returns **true** if the system pasteboard contains data; returns **false** otherwise.| 2240 2241**Error codes** 2242 2243For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2244 2245| Error Code ID| Error Message| 2246| -------- | -------- | 2247| 12900005 | Request timed out. | 2248 2249**Example** 2250 2251```ts 2252let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2253try { 2254 let result: boolean = systemPasteboard.hasDataSync(); 2255 console.info(`Succeeded in checking the PasteData. Result: ${result}`); 2256} catch (err) { 2257 console.error('Failed to check the PasteData. Cause:' + err.message); 2258}; 2259``` 2260 2261### getUnifiedData<sup>12+</sup> 2262 2263getUnifiedData(): Promise<unifiedDataChannel.UnifiedData> 2264 2265Obtains a **PasteData** object from the pasteboard. This API uses a promise to return the result. 2266 2267**Required permissions**: ohos.permission.READ_PASTEBOARD 2268 2269**Atomic service API**: This API can be used in atomic services since API version 12. 2270 2271**System capability**: SystemCapability.MiscServices.Pasteboard 2272 2273**Return value** 2274 2275| Type| Description| 2276| -------- | -------- | 2277| Promise<[unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata)> | Promise used to return the system pasteboard data.| 2278 2279**Error codes** 2280 2281For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2282 2283| Error Code ID| Error Message| 2284| -------- | -------- | 2285| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2286| 12900003 | Another copy or paste operation is in progress. | 2287 2288**Example** 2289 2290```ts 2291import { BusinessError } from '@kit.BasicServicesKit'; 2292import { unifiedDataChannel } from '@kit.ArkData'; 2293import { uniformTypeDescriptor } from '@kit.ArkData'; 2294 2295let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2296systemPasteboard.getUnifiedData().then((data) => { 2297 let records: Array<unifiedDataChannel.UnifiedRecord> = data.getRecords(); 2298 for (let j = 0; j < records.length; j++) { 2299 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 2300 let text = records[j] as unifiedDataChannel.PlainText; 2301 console.info(`${j + 1}.${text.textContent}`); 2302 } 2303 } 2304}).catch((err: BusinessError) => { 2305 console.error('Failed to get UnifiedData. Cause: ' + err.message); 2306}); 2307``` 2308 2309### getUnifiedDataSync<sup>12+</sup> 2310 2311getUnifiedDataSync(): unifiedDataChannel.UnifiedData 2312 2313Reads data in the system pasteboard. This API returns the result synchronously. 2314 2315**Required permissions**: ohos.permission.READ_PASTEBOARD 2316 2317**Atomic service API**: This API can be used in atomic services since API version 12. 2318 2319**System capability**: SystemCapability.MiscServices.Pasteboard 2320 2321**Return value** 2322 2323| Type | Description | 2324| -------------------- | -------------------- | 2325| [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Data in the system pasteboard.| 2326 2327**Error codes** 2328 2329For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2330 2331| Error Code ID| Error Message| 2332| -------- | -------- | 2333| 201 | Permission verification failed. The application does not have the permission required to call the API. | 2334| 12900005 | Request timed out. | 2335 2336**Example** 2337 2338```ts 2339import { unifiedDataChannel } from '@kit.ArkData'; 2340 2341let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2342try { 2343 let result: unifiedDataChannel.UnifiedData = systemPasteboard.getUnifiedDataSync(); 2344 console.info('Succeeded in getting UnifiedData.'); 2345} catch (err) { 2346 console.error('Failed to get UnifiedData. Cause:' + err.message); 2347}; 2348``` 2349 2350### setUnifiedData<sup>12+</sup> 2351 2352setUnifiedData(data: unifiedDataChannel.UnifiedData): Promise<void> 2353 2354Writes a **PasteData** object to the pasteboard. This API uses a promise to return the result. 2355 2356**System capability**: SystemCapability.MiscServices.Pasteboard 2357 2358**Atomic service API**: This API can be used in atomic services since API version 12. 2359 2360**Parameters** 2361 2362| Name| Type| Mandatory| Description| 2363| -------- | -------- | -------- | -------- | 2364| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Yes| Data to be written to the pasteboard.| 2365 2366**Return value** 2367 2368| Type| Description| 2369| -------- | -------- | 2370| Promise<void> | Promise that returns no value.| 2371 2372**Error codes** 2373 2374For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2375 2376| Error Code ID| Error Message| 2377| -------- | -------- | 2378| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2379| 12900003 | Another copy or paste operation is in progress. | 2380| 12900004 | Replication is prohibited. | 2381 2382**Example** 2383 2384```ts 2385import { BusinessError } from '@kit.BasicServicesKit'; 2386import { unifiedDataChannel } from '@kit.ArkData'; 2387 2388let plainTextData = new unifiedDataChannel.UnifiedData(); 2389let plainText = new unifiedDataChannel.PlainText(); 2390plainText.details = { 2391 Key: 'delayPlaintext', 2392 Value: 'delayPlaintext', 2393}; 2394plainText.textContent = 'delayTextContent'; 2395plainText.abstract = 'delayTextContent'; 2396plainTextData.addRecord(plainText); 2397 2398let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2399systemPasteboard.setUnifiedData(plainTextData).then((data: void) => { 2400 console.info('Succeeded in setting UnifiedData.'); 2401}).catch((err: BusinessError) => { 2402 console.error('Failed to set UnifiedData. Cause: ' + err.message); 2403}); 2404``` 2405 2406### setUnifiedDataSync<sup>12+</sup> 2407 2408setUnifiedDataSync(data: unifiedDataChannel.UnifiedData): void 2409 2410Writes data to the system pasteboard. This API returns the result synchronously. 2411 2412**System capability**: SystemCapability.MiscServices.Pasteboard 2413 2414**Atomic service API**: This API can be used in atomic services since API version 12. 2415 2416**Parameters** 2417 2418| Name| Type | Mandatory| Description | 2419| ------ | ----------- | ---- | ---------------- | 2420| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | Yes | Data to be written to the pasteboard.| 2421 2422**Error codes** 2423 2424For details about the error codes, see [Pasteboard Error Codes](errorcode-pasteboard.md). 2425 2426| Error Code ID| Error Message| 2427| -------- | -------- | 2428| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2429| 12900005 | Request timed out. | 2430 2431**Example** 2432 2433```ts 2434import { unifiedDataChannel } from '@kit.ArkData'; 2435 2436let plainTextData = new unifiedDataChannel.UnifiedData(); 2437let plainText = new unifiedDataChannel.PlainText(); 2438plainText.details = { 2439 Key: 'delayPlaintext', 2440 Value: 'delayPlaintext', 2441}; 2442plainText.textContent = 'delayTextContent'; 2443plainText.abstract = 'delayTextContent'; 2444plainTextData.addRecord(plainText); 2445 2446let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2447try { 2448 systemPasteboard.setUnifiedDataSync(plainTextData); 2449 console.info('Succeeded in setting UnifiedData.'); 2450} catch (err) { 2451 console.error('Failed to set UnifiedData. Cause:' + err.message); 2452}; 2453``` 2454### Pattern<sup>13+</sup> 2455Describes the modes supported by the pasteboard. 2456 2457**System capability**: SystemCapability.MiscServices.Pasteboard 2458 2459| Name | Value | Description | 2460| ---------------------------------- | --- | ------------------------------------------------------------------------------------- | 2461| URL | 0 | URL. | 2462| NUMBER | 1 | Number. | 2463| EMAIL_ADDRESS | 2 | Email address.| 2464 2465### detectPatterns<sup>13+</sup> 2466 2467detectPatterns(patterns: Array<Pattern>): Promise<Array<Pattern>> 2468 2469Detects patterns on the **local** pasteboard. This API uses a promise to return the result. 2470 2471**System capability**: SystemCapability.MiscServices.Pasteboard 2472 2473**Parameters** 2474 2475| Name| Type| Mandatory| Description| 2476| -------- | -------- | -------- | -------- | 2477| patterns | [Array<Pattern>](#pattern13) | Yes| Pattern to be detected in the pasteboard.| 2478 2479**Return value** 2480 2481| Type| Description| 2482| -------- | -------- | 2483| Promise<Array<Pattern>> | Promise used to return the detected pattern.| 2484 2485**Error codes** 2486 2487For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2488 2489| Error Code ID| Error Message| 2490| -------- | -------- | 2491| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 2492 2493**Example** 2494 2495```ts 2496import { pasteboard } from '@kit.BasicServicesKit' 2497 2498let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 2499let patterns: Array<pasteboard.Pattern> = [pasteboard.Pattern.URL, pasteboard.Pattern.EMAIL_ADDRESS]; 2500 2501systemPasteboard.detectPatterns(patterns).then((data: Array<pasteboard.Pattern>) => { 2502 if (patterns.sort().join('')==data.sort().join('')) { 2503 console.info('All needed patterns detected, next get data'); 2504 try { 2505 let result: pasteboard.PasteData = systemPasteboard.getDataSync(); 2506 console.info('Succeeded in getting PasteData.'); 2507 } catch (err) { 2508 console.error('Failed to get PasteData. Cause:' + err.message); 2509 }; 2510 } else { 2511 console.info("Not all needed patterns detected, no need to get data."); 2512 } 2513}); 2514``` 2515