1# @ohos.pasteboard (剪贴板) 2 3本模块主要提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪贴板支持对文本、HTML、URI、Want、PixelMap等内容的操作。 4 5> **说明：** 6> 7> 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import pasteboard from '@ohos.pasteboard'; 13``` 14 15## 常量 16 17**系统能力：** SystemCapability.MiscServices.Pasteboard 18 19| 名称 | 类型 | 值 | 说明 | 20| -------- | -------- | -------- | -------- | 21| MAX_RECORD_NUM<sup>7+</sup> | number | 512 | 单个PasteData中所能包含的最大条目数。 | 22| MIMETYPE_TEXT_HTML<sup>7+</sup> | string | 'text/html' | HTML内容的MIME类型定义。 | 23| MIMETYPE_TEXT_WANT<sup>7+</sup> | string | 'text/want' | Want内容的MIME类型定义。 | 24| MIMETYPE_TEXT_PLAIN<sup>7+</sup> | string | 'text/plain' | 纯文本内容的MIME类型定义。 | 25| MIMETYPE_TEXT_URI<sup>7+</sup> | string | 'text/uri' | URI内容的MIME类型定义。 | 26| MIMETYPE_PIXELMAP<sup>9+</sup> | string | 'pixelMap' | PixelMap内容的MIME类型定义。 | 27 28## ValueType<sup>9+</sup> 29 30用于表示允许的数据字段类型。 31 32**系统能力：** SystemCapability.MiscServices.Pasteboard 33 34| 类型 | 说明 | 35| -------- | -------- | 36| string | 表示string的类型。 | 37| image.PixelMap | 表示[image.PixelMap](js-apis-image.md#pixelmap7)的类型。 | 38| Want | 表示[Want](js-apis-app-ability-want.md)的类型。 | 39| ArrayBuffer | 表示ArrayBuffer的类型。 | 40 41## pasteboard.createData<sup>9+</sup> 42 43createData(mimeType: string, value: ValueType): PasteData 44 45构建一个自定义类型的剪贴板内容对象。 46 47**系统能力：** SystemCapability.MiscServices.Pasteboard 48 49**参数：** 50 51| 参数名 | 类型 | 必填 | 说明 | 52| -------- | -------- | -------- | -------- | 53| mimeType | string | 是 | 剪贴板数据对应的MIME类型，可以是[常量](#常量)中已定义的类型，包括HTML类型，WANT类型，纯文本类型，URI类型，PIXELMAP类型；也可以是自定义的MIME类型，开发者可自定义此参数值。 | 54| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 | 55 56**返回值：** 57 58| 类型 | 说明 | 59| -------- | -------- | 60| [PasteData](#pastedata) | 剪贴板内容对象。 | 61 62**示例1：** 63 64```js 65let dataXml = new ArrayBuffer(256); 66let pasteData = pasteboard.createData('app/xml', dataXml); 67``` 68 69**示例2：** 70 71```js 72let dataText = 'hello'; 73let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, dataText); 74``` 75 76## pasteboard.createRecord<sup>9+</sup> 77 78createRecord(mimeType: string, value: ValueType):PasteDataRecord; 79 80创建一条自定义数据内容条目。 81 82**系统能力：** SystemCapability.MiscServices.Pasteboard 83 84**参数：** 85 86| 参数名 | 类型 | 必填 | 说明 | 87| -------- | -------- | -------- | -------- | 88| mimeType | string | 是 | 剪贴板数据对应的MIME类型，可以是[常量](#常量)中已定义的类型，包括HTML类型，WANT类型，纯文本类型，URI类型，PIXELMAP类型；也可以是自定义的MIME类型，开发者可自定义此参数值。 | 89| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 | 90 91**返回值：** 92 93| 类型 | 说明 | 94| -------- | -------- | 95| [PasteDataRecord](#pastedatarecord7) | 一条新建的自定义数据内容条目。 | 96 97**示例1：** 98 99```js 100let dataXml = new ArrayBuffer(256); 101let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); 102``` 103 104**示例2：** 105 106```js 107let dataUri = 'dataability:///com.example.myapplication1/user.txt'; 108let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, dataUri); 109``` 110 111## pasteboard.getSystemPasteboard 112 113getSystemPasteboard(): SystemPasteboard 114 115获取系统剪贴板对象。 116 117**系统能力：** SystemCapability.MiscServices.Pasteboard 118 119**返回值：** 120 121| 类型 | 说明 | 122| -------- | -------- | 123| [SystemPasteboard](#systempasteboard) | 系统剪贴板对象。 | 124 125**示例：** 126 127```js 128let systemPasteboard = pasteboard.getSystemPasteboard(); 129``` 130 131## ShareOption<sup>9+</sup> 132 133可粘贴数据的范围类型枚举。 134 135**系统能力：** SystemCapability.MiscServices.Pasteboard 136 137| 名称 | 值 | 说明 | 138|-------------|---|-------------------| 139| INAPP | 0 | 表示仅允许同应用内粘贴。 | 140| LOCALDEVICE | 1 | 表示允许在此设备中任何应用内粘贴。 | 141| CROSSDEVICE | 2 | 表示允许跨设备在任何应用内粘贴。 | 142 143## pasteboard.createHtmlData<sup>(deprecated)</sup> 144 145createHtmlData(htmlText: string): PasteData 146 147构建一个HTML剪贴板内容对象。 148> **说明：** 149> 150> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。 151 152**系统能力：** SystemCapability.MiscServices.Pasteboard 153 154**参数：** 155 156| 参数名 | 类型 | 必填 | 说明 | 157| -------- | -------- | -------- | -------- | 158| htmlText | string | 是 | HTML内容。 | 159 160**返回值：** 161 162| 类型 | 说明 | 163| -------- | -------- | 164| [PasteData](#pastedata) | 剪贴板内容对象。 | 165 166**示例：** 167 168```js 169let 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>"; 170let pasteData = pasteboard.createHtmlData(html); 171``` 172 173## pasteboard.createWantData<sup>(deprecated)</sup> 174 175createWantData(want: Want): PasteData 176 177构建一个Want剪贴板内容对象。 178> **说明：** 179> 180> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。 181 182**系统能力：** SystemCapability.MiscServices.Pasteboard 183 184**参数：** 185 186| 参数名 | 类型 | 必填 | 说明 | 187| -------- | -------- | -------- | -------- | 188| want | [Want](js-apis-app-ability-want.md) | 是 | Want内容。 | 189 190**返回值：** 191 192| 类型 | 说明 | 193| -------- | -------- | 194| [PasteData](#pastedata) | 剪贴板内容对象。 | 195 196**示例：** 197 198```js 199let object = { 200 bundleName: "com.example.aafwk.test", 201 abilityName: "com.example.aafwk.test.TwoAbility" 202}; 203let pasteData = pasteboard.createWantData(object); 204``` 205 206## pasteboard.createPlainTextData<sup>(deprecated)</sup> 207 208createPlainTextData(text: string): PasteData 209 210构建一个纯文本剪贴板内容对象。 211> **说明：** 212> 213> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。 214 215**系统能力：** SystemCapability.MiscServices.Pasteboard 216 217**参数：** 218 219| 参数名 | 类型 | 必填 | 说明 | 220| -------- | -------- | -------- | -------- | 221| text | string | 是 | 纯文本内容。 | 222 223**返回值：** 224 225| 类型 | 说明 | 226| -------- | -------- | 227| [PasteData](#pastedata) | 剪贴板内容对象。 | 228 229**示例：** 230 231```js 232let pasteData = pasteboard.createPlainTextData('content'); 233``` 234 235## pasteboard.createUriData<sup>(deprecated)</sup> 236 237createUriData(uri: string): PasteData 238 239构建一个URI剪贴板内容对象。 240> **说明：** 241> 242> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createData](#pasteboardcreatedata9)替代。 243 244**系统能力：** SystemCapability.MiscServices.Pasteboard 245 246**参数：** 247 248| 参数名 | 类型 | 必填 | 说明 | 249| -------- | -------- | -------- | -------- | 250| uri | string | 是 | URI内容。 | 251 252**返回值：** 253 254| 类型 | 说明 | 255| -------- | -------- | 256| [PasteData](#pastedata) | 剪贴板内容对象。 | 257 258**示例：** 259 260```js 261let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt'); 262``` 263## pasteboard.createHtmlTextRecord<sup>(deprecated)</sup> 264 265createHtmlTextRecord(htmlText: string): PasteDataRecord 266 267创建一条HTML内容的条目。 268> **说明：** 269> 270> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。 271 272**系统能力：** SystemCapability.MiscServices.Pasteboard 273 274**参数：** 275 276| 参数名 | 类型 | 必填 | 说明 | 277| -------- | -------- | -------- | -------- | 278| htmlText | string | 是 | HTML内容。 | 279 280**返回值：** 281 282| 类型 | 说明 | 283| -------- | -------- | 284| [PasteDataRecord](#pastedatarecord7) | 一条新建的HTML内容条目。 | 285 286**示例：** 287 288```js 289let 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>"; 290let record = pasteboard.createHtmlTextRecord(html); 291``` 292 293## pasteboard.createWantRecord<sup>(deprecated)</sup> 294 295createWantRecord(want: Want): PasteDataRecord 296 297创建一条Want内容条目。 298> **说明：** 299> 300> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。 301 302**系统能力：** SystemCapability.MiscServices.Pasteboard 303 304**参数：** 305 306| 参数名 | 类型 | 必填 | 说明 | 307| -------- | -------- | -------- | -------- | 308| want | [Want](js-apis-app-ability-want.md) | 是 | Want内容。 | 309 310**返回值：** 311 312| 类型 | 说明 | 313| -------- | -------- | 314| [PasteDataRecord](#pastedatarecord7) | 一条新建的Want内容条目。 | 315 316**示例：** 317 318```js 319let object = { 320 bundleName: "com.example.aafwk.test", 321 abilityName: "com.example.aafwk.test.TwoAbility" 322}; 323let record = pasteboard.createWantRecord(object); 324``` 325 326## pasteboard.createPlainTextRecord<sup>(deprecated)</sup> 327 328createPlainTextRecord(text: string): PasteDataRecord 329 330创建一条纯文本内容条目。 331> **说明：** 332> 333> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。 334 335**系统能力：** SystemCapability.MiscServices.Pasteboard 336 337**参数：** 338 339| 参数名 | 类型 | 必填 | 说明 | 340| -------- | -------- | -------- | -------- | 341| text | string | 是 | 纯文本内容。 | 342 343**返回值：** 344 345| 类型 | 说明 | 346| -------- | -------- | 347| [PasteDataRecord](#pastedatarecord7) | 一条新建的纯文本内容条目。 | 348 349**示例：** 350 351```js 352let record = pasteboard.createPlainTextRecord('hello'); 353``` 354 355## pasteboard.createUriRecord<sup>(deprecated)</sup> 356 357createUriRecord(uri: string): PasteDataRecord 358 359创建一条URI内容的条目。 360> **说明：** 361> 362> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.createRecord](#pasteboardcreaterecord9)替代。 363 364**系统能力：** SystemCapability.MiscServices.Pasteboard 365 366**参数：** 367 368| 参数名 | 类型 | 必填 | 说明 | 369| -------- | -------- | -------- | -------- | 370| uri | string | 是 | URI内容。 | 371 372**返回值：** 373 374| 类型 | 说明 | 375| -------- | -------- | 376| [PasteDataRecord](#pastedatarecord7) | 一条新建的URI内容条目。 | 377 378**示例：** 379 380```js 381let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 382``` 383 384 385## PasteDataProperty<sup>7+</sup> 386 387定义了剪贴板中所有内容条目的属性，包含时间戳、数据类型、粘贴范围以及一些附加数据等。 388 389**系统能力：** SystemCapability.MiscServices.Pasteboard 390 391| 名称 | 类型 | 可读 | 可写 | 说明 | 392| -------- | -------- | -------- | -------- |--------------------------------------------------------------------------------------------| 393| additions<sup>7+</sup> | {[key:string]:object} | 是 | 是 | 设置其他附加属性数据。 | 394| mimeTypes<sup>7+</sup> | Array<string> | 是 | 否 | 剪贴板内容条目的数据类型，非重复的类型列表。 | 395| tag<sup>7+</sup> | string | 是 | 是 | 用户自定义标签。 | 396| timestamp<sup>7+</sup> | number | 是 | 否 | 剪贴板数据的写入时间戳（单位：ms）。 | 397| localOnly<sup>7+</sup> | boolean | 是 | 是 | 配置剪贴板内容是否为“仅在本地”，默认值为false。暂不支持，推荐使用shareOption属性。<br/>- 配置为true时，表示内容仅在本地，不会在设备之间传递。<br/>- 配置为false时，表示内容将在设备间传递。 | 398| shareOption<sup>9+</sup> | [ShareOption](#shareoption9) | 是 | 是 | 指示剪贴板数据可以粘贴到的范围，如果未设置或设置不正确，则默认值为CROSSDEVICE。 | 399 400## PasteDataRecord<sup>7+</sup> 401 402对于剪贴板中内容记录的抽象定义，称之为条目。剪贴板内容部分由一个或者多个条目构成，例如一条文本内容、一份HTML、一个URI或者一个Want。 403 404### 属性 405 406**系统能力：** SystemCapability.MiscServices.Pasteboard 407 408| 名称 | 类型 | 可读 | 可写 | 说明 | 409| -------- | -------- | -------- | -------- | -------- | 410| htmlText<sup>7+</sup> | string | 是 | 否 | HTML内容。 | 411| want<sup>7+</sup> | [Want](js-apis-app-ability-want.md) | 是 | 否 | Want内容。 | 412| mimeType<sup>7+</sup> | string | 是 | 否 | 数据类型。 | 413| plainText<sup>7+</sup> | string | 是 | 否 | 纯文本内容。 | 414| uri<sup>7+</sup> | string | 是 | 否 | URI内容。 | 415| pixelMap<sup>9+</sup> | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | 否 | PixelMap内容。 | 416| data<sup>9+</sup> | {[mimeType: string]: ArrayBuffer} | 是 | 否 | 自定义数据内容。 | 417 418### toPlainText<sup>9+</sup> 419 420toPlainText(): string 421 422将一个PasteData中的内容强制转换为文本内容。 423 424**系统能力：** SystemCapability.MiscServices.Pasteboard 425 426**返回值：** 427 428| 类型 | 说明 | 429| -------- | -------- | 430| string | 纯文本内容。 | 431 432**示例：** 433 434```js 435let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 436let data = record.toPlainText(); 437console.info(`Succeeded in converting to text. Data: ${data}`); 438``` 439 440### convertToText<sup>(deprecated)</sup> 441 442convertToText(callback: AsyncCallback<string>): void 443 444将一个PasteData中的内容强制转换为文本内容，使用callback异步回调。 445> **说明：** 446> 447> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[toPlainText](#toplaintext9)替代。 448 449**系统能力：** SystemCapability.MiscServices.Pasteboard 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 说明 | 454| -------- | -------- | -------- | -------- | 455| callback | AsyncCallback<string> | 是 | 回调函数，当转换成功，err为undefined，data为强制转换的文本内容；否则返回错误信息。 | 456 457**示例：** 458 459```js 460let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 461record.convertToText((err, data) => { 462 if (err) { 463 console.error(`Failed to convert to text. Cause: ${err.message}`); 464 return; 465 } 466 console.info(`Succeeded in converting to text. Data: ${data}`); 467}); 468``` 469 470### convertToText<sup>(deprecated)</sup> 471 472convertToText(): Promise<string> 473 474将一个PasteData中的内容强制转换为文本内容，使用Promise异步回调。 475> **说明：** 476> 477> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[toPlainText](#toplaintext9)替代。 478 479**系统能力：** SystemCapability.MiscServices.Pasteboard 480 481**返回值：** 482 483| 类型 | 说明 | 484| -------- | -------- | 485| Promise<string> | Promise对象，返回强制转换的文本内容。 | 486 487**示例：** 488 489```js 490let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 491record.convertToText().then((data) => { 492 console.info(`Succeeded in converting to text. Data: ${data}`); 493}).catch((err) => { 494 console.error(`Failed to convert to text. Cause: ${err.message}`); 495}); 496``` 497 498## PasteData 499 500剪贴板内容对象。剪贴板内容包含一个或者多个内容条目（[PasteDataRecord](#pastedatarecord7)）以及属性描述对象（[PasteDataProperty](#pastedataproperty7)）。 501 502在调用PasteData的接口前，需要先通过[createData()](#pasteboardcreatedata9)或[getData()](#getdata9)获取一个PasteData对象。 503 504**系统能力：** SystemCapability.MiscServices.Pasteboard 505 506### getPrimaryText 507 508getPrimaryText(): string 509 510获取首个条目的纯文本内容。 511 512**系统能力：** SystemCapability.MiscServices.Pasteboard 513 514**返回值：** 515 516| 类型 | 说明 | 517| -------- | -------- | 518| string | 纯文本内容。 | 519 520**示例：** 521 522```js 523let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 524let plainText = pasteData.getPrimaryText(); 525``` 526 527### getPrimaryHtml<sup>7+</sup> 528 529getPrimaryHtml(): string 530 531获取首个条目的HTML内容。 532 533**系统能力：** SystemCapability.MiscServices.Pasteboard 534 535**返回值：** 536 537| 类型 | 说明 | 538| -------- | -------- | 539| string | HTML内容。 | 540 541**示例：** 542 543```js 544let 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>"; 545let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, html); 546let htmlText = pasteData.getPrimaryHtml(); 547``` 548 549### getPrimaryWant<sup>7+</sup> 550 551getPrimaryWant(): Want 552 553获取首个条目的Want对象内容。 554 555**系统能力：** SystemCapability.MiscServices.Pasteboard 556 557**返回值：** 558 559| 类型 | 说明 | 560| -------- | -------- | 561| [Want](js-apis-app-ability-want.md) | Want对象内容。 | 562 563**示例：** 564 565```js 566let object = { 567 bundleName: "com.example.aafwk.test", 568 abilityName: "com.example.aafwk.test.TwoAbility" 569}; 570let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_WANT, object); 571let want = pasteData.getPrimaryWant(); 572``` 573 574### getPrimaryUri<sup>7+</sup> 575 576getPrimaryUri(): string 577 578获取首个条目的URI内容。 579 580**系统能力：** SystemCapability.MiscServices.Pasteboard 581 582**返回值：** 583 584| 类型 | 说明 | 585| -------- | -------- | 586| string | URI内容。 | 587 588**示例：** 589 590```js 591let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 592let uri = pasteData.getPrimaryUri(); 593``` 594 595### getPrimaryPixelMap<sup>9+</sup> 596 597getPrimaryPixelMap(): image.PixelMap 598 599获取首个条目的PixelMap内容。 600 601**系统能力：** SystemCapability.MiscServices.Pasteboard 602 603**返回值：** 604 605| 类型 | 说明 | 606| -------- | -------- | 607| [image.PixelMap](js-apis-image.md#pixelmap7) | PixelMap内容。 | 608 609**示例：** 610 611```js 612import image from '@ohos.multimedia.image'; 613 614let buffer = new ArrayBuffer(128); 615let opt = { 616 size: { height: 3, width: 5 }, 617 pixelFormat: 3, 618 editable: true, 619 alphaType: 1, 620 scaleMode: 1 621}; 622image.createPixelMap(buffer, opt).then((pixelMap) => { 623 let pasteData = pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP, pixelMap); 624 let PixelMap = pasteData.getPrimaryPixelMap(); 625}); 626``` 627 628### addRecord<sup>7+</sup> 629 630addRecord(record: PasteDataRecord): void 631 632向当前剪贴板内容中添加一条条目，同时也会将条目类型添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 633 634剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 635 636**系统能力：** SystemCapability.MiscServices.Pasteboard 637 638**参数：** 639 640| 参数名 | 类型 | 必填 | 说明 | 641| -------- | -------- | -------- | -------- | 642| record | [PasteDataRecord](#pastedatarecord7) | 是 | 待添加的条目。 | 643 644**示例：** 645 646```js 647let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 648let textRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 649let 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>"; 650let htmlRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_HTML, html); 651pasteData.addRecord(textRecord); 652pasteData.addRecord(htmlRecord); 653``` 654### addRecord<sup>9+</sup> 655 656addRecord(mimeType: string, value: ValueType): void 657 658向当前剪贴板内容中添加一条自定义数据内容条目，同时也会将自定义数据类型添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 659 660剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 661 662**系统能力：** SystemCapability.MiscServices.Pasteboard 663 664**参数：** 665 666| 参数名 | 类型 | 必填 | 说明 | 667| -------- | -------- | -------- | -------- | 668| mimeType | string | 是 | 自定义数据的MIME类型。 | 669| value | [ValueType](#valuetype9) | 是 | 自定义数据内容。 | 670 671**错误码：** 672 673以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 674 675| 错误码ID | 错误信息 | 676| -------- | -------- | 677| 12900002 | The number of record exceeds the maximum limit. | 678 679**示例：** 680 681 ```js 682 let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 683 let dataXml = new ArrayBuffer(256); 684 pasteData.addRecord('app/xml', dataXml); 685 ``` 686 687### getMimeTypes<sup>7+</sup> 688 689getMimeTypes(): Array<string> 690 691获取剪贴板中[PasteDataProperty](#pastedataproperty7)的mimeTypes列表，当剪贴板内容为空时，返回列表为空。 692 693**系统能力：** SystemCapability.MiscServices.Pasteboard 694 695**返回值：** 696 697| 类型 | 说明 | 698| -------- | -------- | 699| Array<string> | 剪贴板内容条目的数据类型，非重复的类型列表。 | 700 701**示例：** 702 703```js 704let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 705let types = pasteData.getMimeTypes(); 706``` 707 708### getPrimaryMimeType<sup>7+</sup> 709 710getPrimaryMimeType(): string 711 712获取剪贴板内容中首个条目的数据类型。 713 714**系统能力：** SystemCapability.MiscServices.Pasteboard 715 716**返回值：** 717 718| 类型 | 说明 | 719| -------- | -------- | 720| string | 首个条目的数据类型。 | 721 722**示例：** 723 724```js 725let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 726let type = pasteData.getPrimaryMimeType(); 727``` 728 729### getProperty<sup>7+</sup> 730 731getProperty(): PasteDataProperty 732 733获取剪贴板内容的属性描述对象。 734 735**系统能力：** SystemCapability.MiscServices.Pasteboard 736 737**返回值：** 738 739| 类型 | 说明 | 740| -------- | -------- | 741| [PasteDataProperty](#pastedataproperty7) | 属性描述对象。 | 742 743**示例：** 744 745```js 746let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 747let property = pasteData.getProperty(); 748``` 749 750### setProperty<sup>9+</sup> 751 752setProperty(property: PasteDataProperty): void 753 754设置剪贴板内容的属性描述对象，当前仅支持设置shareOption属性。 755 756**系统能力：** SystemCapability.MiscServices.Pasteboard 757 758**参数：** 759 760| 参数名 | 类型 | 必填 | 说明 | 761| -------- | -------- | -------- | -------- | 762| property | [PasteDataProperty](#pastedataproperty7) | 是 | 属性描述对象。 | 763 764**示例：** 765 766```js 767let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml'); 768let prop = pasteData.getProperty(); 769prop.shareOption = pasteboard.ShareOption.INAPP; 770pasteData.setProperty(prop); 771``` 772 773### getRecord<sup>9+</sup> 774 775getRecord(index: number): PasteDataRecord 776 777获取剪贴板内容中指定下标的条目。 778 779**系统能力：** SystemCapability.MiscServices.Pasteboard 780 781**参数：** 782 783| 参数名 | 类型 | 必填 | 说明 | 784| -------- | -------- | -------- | -------- | 785| index | number | 是 | 指定条目的下标。 | 786 787**返回值：** 788 789| 类型 | 说明 | 790| -------- | -------- | 791| [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 | 792 793**错误码：** 794 795以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 796 797| 错误码ID | 错误信息 | 798| -------- | -------- | 799| 12900001 | The index is out of the record. | 800 801**示例：** 802 803```js 804let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 805let record = pasteData.getRecord(0); 806``` 807 808### getRecordCount<sup>7+</sup> 809 810getRecordCount(): number 811 812获取剪贴板内容中条目的个数。 813 814**系统能力：** SystemCapability.MiscServices.Pasteboard 815 816**返回值：** 817 818| 类型 | 说明 | 819| -------- | -------- | 820| number | 条目的个数。 | 821 822**示例：** 823 824```js 825let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 826let count = pasteData.getRecordCount(); 827``` 828 829### getTag<sup>7+</sup> 830 831getTag(): string 832 833获取剪贴板内容中用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。 834 835**系统能力：** SystemCapability.MiscServices.Pasteboard 836 837**返回值：** 838 839| 类型 | 说明 | 840| -------- | -------- | 841| string | 返回用户自定义的标签内容，如果没有设置用户自定义的标签内容，将返回空。 | 842 843**示例：** 844 845```js 846let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 847let tag = pasteData.getTag(); 848``` 849 850### hasType<sup>9+</sup> 851 852hasType(mimeType: string): boolean 853 854检查剪贴板内容中是否有指定的MIME数据类型。 855 856**系统能力：** SystemCapability.MiscServices.Pasteboard 857 858**参数：** 859 860| 参数名 | 类型 | 必填 | 说明 | 861| -------- | -------- | -------- | -------- | 862| mimeType | string | 是 | 待查询的数据类型。 | 863 864**返回值：** 865 866| 类型 | 说明 | 867| -------- | -------- | 868| boolean | 有指定的数据类型返回true，否则返回false。 | 869 870**示例：** 871 872```js 873let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 874let hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); 875``` 876 877### removeRecord<sup>9+</sup> 878 879removeRecord(index: number): void 880 881移除剪贴板内容中指定下标的条目。 882 883**系统能力：** SystemCapability.MiscServices.Pasteboard 884 885**参数：** 886 887| 参数名 | 类型 | 必填 | 说明 | 888| -------- | -------- | -------- | -------- | 889| index | number | 是 | 指定的下标。 | 890 891**错误码：** 892 893以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 894 895| 错误码ID | 错误信息 | 896| -------- | -------- | 897| 12900001 | The index is out of the record. | 898 899**示例：** 900 901```js 902let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 903pasteData.removeRecord(0); 904``` 905 906### replaceRecord<sup>9+</sup> 907 908replaceRecord(index: number, record: PasteDataRecord): void 909 910替换剪贴板内容中指定下标的条目。 911 912**系统能力：** SystemCapability.MiscServices.Pasteboard 913 914**参数：** 915 916| 参数名 | 类型 | 必填 | 说明 | 917| -------- | -------- | -------- | -------- | 918| index | number | 是 | 指定的下标。 | 919| record | [PasteDataRecord](#pastedatarecord7) | 是 | 新条目的内容。 | 920 921**错误码：** 922 923以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 924 925| 错误码ID | 错误信息 | 926| -------- | -------- | 927| 12900001 | The index is out of the record. | 928 929**示例：** 930 931```js 932let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello'); 933let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt'); 934pasteData.replaceRecord(0, record); 935``` 936### addHtmlRecord<sup>(deprecated)</sup> 937 938addHtmlRecord(htmlText: string): void 939 940向当前剪贴板内容中添加一条HTML内容条目，并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 941 942剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 943> **说明：** 944> 945> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[addRecord](#addrecord9)替代。 946 947**系统能力：** SystemCapability.MiscServices.Pasteboard 948 949**参数：** 950 951| 参数名 | 类型 | 必填 | 说明 | 952| -------- | -------- | -------- | -------- | 953| htmlText | string | 是 | HTML内容。 | 954 955**示例：** 956 957```js 958let pasteData = pasteboard.createPlainTextData('hello'); 959let 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>"; 960pasteData.addHtmlRecord(html); 961``` 962 963### addWantRecord<sup>(deprecated)</sup> 964 965addWantRecord(want: Want): void 966 967向当前剪贴板内容中添加一条Want条目，并将MIMETYPE_TEXT_WANT添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 968 969剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 970> **说明：** 971> 972> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[addRecord](#addrecord9)替代。 973 974**系统能力：** SystemCapability.MiscServices.Pasteboard 975 976**参数：** 977 978| 参数名 | 类型 | 必填 | 说明 | 979| -------- | -------- | -------- | -------- | 980| want | [Want](js-apis-app-ability-want.md) | 是 | Want对象内容。 | 981 982**示例：** 983 984```js 985let pasteData = pasteboard.createPlainTextData('hello'); 986let object = { 987 bundleName: "com.example.aafwk.test", 988 abilityName: "com.example.aafwk.test.TwoAbility" 989}; 990pasteData.addWantRecord(object); 991``` 992 993### addTextRecord<sup>(deprecated)</sup> 994 995addTextRecord(text: string): void 996 997向当前剪贴板内容中添加一条纯文本条目，并将MIME_TEXT_PLAIN添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 998 999剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 1000> **说明：** 1001> 1002> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[addRecord](#addrecord9)替代。 1003 1004**系统能力：** SystemCapability.MiscServices.Pasteboard 1005 1006**参数：** 1007 1008| 参数名 | 类型 | 必填 | 说明 | 1009| -------- | -------- | -------- | -------- | 1010| text | string | 是 | 纯文本内容。 | 1011 1012**示例：** 1013 1014```js 1015let pasteData = pasteboard.createPlainTextData('hello'); 1016pasteData.addTextRecord('good'); 1017``` 1018 1019### addUriRecord<sup>(deprecated)</sup> 1020 1021addUriRecord(uri: string): void 1022 1023向当前剪贴板内容中添加一条URI条目，并将MIMETYPE_TEXT_URI添加到[PasteDataProperty](#pastedataproperty7)的mimeTypes中。入参均不能为空，否则添加失败。 1024 1025剪贴板内容中添加的条目达到数量上限512后，后续的添加操作无效。 1026> **说明：** 1027> 1028> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[addRecord](#addrecord9)替代。 1029 1030**系统能力：** SystemCapability.MiscServices.Pasteboard 1031 1032**参数：** 1033 1034| 参数名 | 类型 | 必填 | 说明 | 1035| -------- | -------- | -------- | -------- | 1036| uri | string | 是 | URI内容。 | 1037 1038**示例：** 1039 1040```js 1041let pasteData = pasteboard.createPlainTextData('hello'); 1042pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt'); 1043``` 1044### getRecordAt<sup>(deprecated)</sup> 1045 1046getRecordAt(index: number): PasteDataRecord 1047 1048获取剪贴板内容中指定下标的条目。 1049> **说明：** 1050> 1051> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[getRecord](#getrecord9)替代。 1052 1053**系统能力：** SystemCapability.MiscServices.Pasteboard 1054 1055**参数：** 1056 1057| 参数名 | 类型 | 必填 | 说明 | 1058| -------- | -------- | -------- | -------- | 1059| index | number | 是 | 指定条目的下标。 | 1060 1061**返回值：** 1062 1063| 类型 | 说明 | 1064| -------- | -------- | 1065| [PasteDataRecord](#pastedatarecord7) | 指定下标的条目。 | 1066 1067**示例：** 1068 1069```js 1070let pasteData = pasteboard.createPlainTextData('hello'); 1071let record = pasteData.getRecordAt(0); 1072``` 1073 1074### hasMimeType<sup>(deprecated)</sup> 1075 1076hasMimeType(mimeType: string): boolean 1077 1078检查剪贴板内容中是否有指定的数据类型。 1079> **说明：** 1080> 1081> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[hasType](#hastype9)替代。 1082 1083**系统能力：** SystemCapability.MiscServices.Pasteboard 1084 1085**参数：** 1086 1087| 参数名 | 类型 | 必填 | 说明 | 1088| -------- | -------- | -------- | -------- | 1089| mimeType | string | 是 | 待查询的数据类型。 | 1090 1091**返回值：** 1092 1093| 类型 | 说明 | 1094| -------- | -------- | 1095| boolean | 有指定的数据类型返回true，否则返回false。 | 1096 1097**示例：** 1098 1099```js 1100let pasteData = pasteboard.createPlainTextData('hello'); 1101let hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN); 1102``` 1103### removeRecordAt<sup>(deprecated)</sup> 1104 1105removeRecordAt(index: number): boolean 1106 1107移除剪贴板内容中指定下标的条目。 1108> **说明：** 1109> 1110> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[removeRecord](#removerecord9)替代。 1111 1112**系统能力：** SystemCapability.MiscServices.Pasteboard 1113 1114**参数：** 1115 1116| 参数名 | 类型 | 必填 | 说明 | 1117| -------- | -------- | -------- | -------- | 1118| index | number | 是 | 指定的下标。 | 1119 1120**返回值：** 1121 1122| 类型 | 说明 | 1123| -------- | -------- | 1124| boolean | 成功移除返回true，失败返回false。 | 1125 1126**示例：** 1127 1128```js 1129let pasteData = pasteboard.createPlainTextData('hello'); 1130let isRemove = pasteData.removeRecordAt(0); 1131``` 1132### replaceRecordAt<sup>(deprecated)</sup> 1133 1134replaceRecordAt(index: number, record: PasteDataRecord): boolean 1135 1136替换剪贴板内容中指定下标的条目。 1137> **说明：** 1138> 1139> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[replaceRecord](#replacerecord9)替代。 1140 1141**系统能力：** SystemCapability.MiscServices.Pasteboard 1142 1143**参数：** 1144 1145| 参数名 | 类型 | 必填 | 说明 | 1146| -------- | -------- | -------- | -------- | 1147| index | number | 是 | 指定的下标。 | 1148| record | [PasteDataRecord](#pastedatarecord7) | 是 | 替换后的条目。 | 1149 1150**返回值：** 1151 1152| 类型 | 说明 | 1153| -------- | -------- | 1154| boolean | 成功替换返回true，失败返回false。 | 1155 1156**示例：** 1157 1158```js 1159let pasteData = pasteboard.createPlainTextData('hello'); 1160let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt'); 1161let isReplace = pasteData.replaceRecordAt(0, record); 1162``` 1163 1164## SystemPasteboard 1165 1166系统剪贴板对象。 1167 1168在调用SystemPasteboard的接口前，需要先通过[getSystemPasteboard](#pasteboardgetsystempasteboard)获取系统剪贴板。 1169 1170```js 1171let systemPasteboard = pasteboard.getSystemPasteboard(); 1172``` 1173 1174### on('update')<sup>7+</sup> 1175 1176on(type: 'update', callback: () =>void ): void 1177 1178订阅系统剪贴板内容变化事件，当系统剪贴板中内容变化时触发用户程序的回调。 1179 1180**系统能力：** SystemCapability.MiscServices.Pasteboard 1181 1182**参数：** 1183 1184| 参数名 | 类型 | 必填 | 说明 | 1185| -------- | -------- | -------- | -------- | 1186| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | 1187| callback | function | 是 | 剪贴板中内容变化时触发的用户程序的回调。 | 1188 1189**示例：** 1190 1191```js 1192let systemPasteboard = pasteboard.getSystemPasteboard(); 1193let listener = () => { 1194 console.info('The system pasteboard has changed.'); 1195}; 1196systemPasteboard.on('update', listener); 1197``` 1198 1199### off('update')<sup>7+</sup> 1200 1201off(type: 'update', callback?: () =>void ): void 1202 1203取消订阅系统剪贴板内容变化事件。 1204 1205**系统能力：** SystemCapability.MiscServices.Pasteboard 1206 1207**参数：** 1208 1209| 参数名 | 类型 | 必填 | 说明 | 1210| -------- | -------- | -------- |---------------------------------------------------------| 1211| type | string | 是 | 取值为'update'，表示系统剪贴板内容变化事件。 | 1212| callback | function | 否 | 剪贴板中内容变化时触发的用户程序的回调。如果此参数未填，表明清除本应用的所有监听回调，否则表示清除指定监听回调。| 1213 1214**示例：** 1215 1216```js 1217let systemPasteboard = pasteboard.getSystemPasteboard(); 1218let listener = () => { 1219 console.info('The system pasteboard has changed.'); 1220}; 1221systemPasteboard.off('update', listener); 1222``` 1223 1224### clearData<sup>9+</sup> 1225 1226clearData(callback: AsyncCallback<void>): void 1227 1228清空系统剪贴板内容，使用callback异步回调。 1229 1230**系统能力：** SystemCapability.MiscServices.Pasteboard 1231 1232**参数：** 1233 1234| 参数名 | 类型 | 必填 | 说明 | 1235| -------- | -------- | -------- | -------- | 1236| callback | AsyncCallback<void> | 是 | 回调函数。当成功清空时，err为undefined；否则为错误对象。 | 1237 1238**示例：** 1239 1240```js 1241let systemPasteboard = pasteboard.getSystemPasteboard(); 1242systemPasteboard.clearData((err, data) => { 1243 if (err) { 1244 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1245 return; 1246 } 1247 console.info('Succeeded in clearing the pasteboard.'); 1248}); 1249``` 1250 1251### clearData<sup>9+</sup> 1252 1253clearData(): Promise<void> 1254 1255清空系统剪贴板内容，使用Promise异步回调。 1256 1257**系统能力：** SystemCapability.MiscServices.Pasteboard 1258 1259**返回值：** 1260 1261| 类型 | 说明 | 1262| -------- | -------- | 1263| Promise<void> | 无返回结果的Promise对象。 | 1264 1265**示例：** 1266 1267```js 1268let systemPasteboard = pasteboard.getSystemPasteboard(); 1269systemPasteboard.clearData().then((data) => { 1270 console.info('Succeeded in clearing the pasteboard.'); 1271}).catch((err) => { 1272 console.error(`Failed to clear the pasteboard. Cause: ${err.message}`); 1273}); 1274``` 1275 1276### setData<sup>9+</sup> 1277 1278setData(data: PasteData, callback: AsyncCallback<void>): void 1279 1280将数据写入系统剪贴板，使用callback异步回调。 1281 1282**系统能力：** SystemCapability.MiscServices.Pasteboard 1283 1284**参数：** 1285 1286| 参数名 | 类型 | 必填 | 说明 | 1287| -------- | -------- | -------- | -------- | 1288| data | [PasteData](#pastedata) | 是 | PasteData对象。 | 1289| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 1290 1291**错误码：** 1292 1293以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 1294 1295| 错误码ID | 错误信息 | 1296| -------- | -------- | 1297| 12900003 | Another copy or paste is in progress. | 1298| 12900004 | Replication is prohibited. | 1299 1300**示例：** 1301 1302```js 1303let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1304let systemPasteboard = pasteboard.getSystemPasteboard(); 1305systemPasteboard.setData(pasteData, (err, data) => { 1306 if (err) { 1307 console.error('Failed to set PasteData. Cause: ' + err.message); 1308 return; 1309 } 1310 console.info('Succeeded in setting PasteData.'); 1311}); 1312``` 1313 1314### setData<sup>9+</sup> 1315 1316setData(data: PasteData): Promise<void> 1317 1318将数据写入系统剪贴板，使用Promise异步回调。 1319 1320**系统能力：** SystemCapability.MiscServices.Pasteboard 1321 1322**参数：** 1323 1324| 参数名 | 类型 | 必填 | 说明 | 1325| -------- | -------- | -------- | -------- | 1326| data | [PasteData](#pastedata) | 是 | PasteData对象。 | 1327 1328**返回值：** 1329 1330| 类型 | 说明 | 1331| -------- | -------- | 1332| Promise<void> | 无返回结果的Promise对象。 | 1333 1334**错误码：** 1335 1336以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 1337 1338| 错误码ID | 错误信息 | 1339| -------- | -------- | 1340| 12900003 | Another copy or paste is in progress. | 1341| 12900004 | Replication is prohibited. | 1342 1343**示例：** 1344 1345```js 1346let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content'); 1347let systemPasteboard = pasteboard.getSystemPasteboard(); 1348systemPasteboard.setData(pasteData).then((data) => { 1349 console.info('Succeeded in setting PasteData.'); 1350}).catch((err) => { 1351 console.error('Failed to set PasteData. Cause: ' + err.message); 1352}); 1353``` 1354 1355### getData<sup>9+</sup> 1356 1357getData( callback: AsyncCallback<PasteData>): void 1358 1359读取系统剪贴板内容，使用callback异步回调。 1360 1361**系统能力：** SystemCapability.MiscServices.Pasteboard 1362 1363**参数：** 1364 1365| 参数名 | 类型 | 必填 | 说明 | 1366| -------- | -------- | -------- | -------- | 1367| callback | AsyncCallback<[PasteData](#pastedata)> | 是 | 回调函数。当读取成功，err为undefined，data为返回的系统剪贴板数据；否则返回错误对象。 | 1368 1369**错误码：** 1370 1371以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 1372 1373| 错误码ID | 错误信息 | 1374| -------- | -------- | 1375| 12900003 | Another copy or paste is in progress. | 1376 1377**示例：** 1378 1379```js 1380let systemPasteboard = pasteboard.getSystemPasteboard(); 1381systemPasteboard.getData((err, pasteData) => { 1382 if (err) { 1383 console.error('Failed to get PasteData. Cause: ' + err.message); 1384 return; 1385 } 1386 let text = pasteData.getPrimaryText(); 1387}); 1388``` 1389 1390### getData<sup>9+</sup> 1391 1392getData(): Promise<PasteData> 1393 1394读取系统剪贴板内容，使用Promise异步回调。 1395 1396**系统能力：** SystemCapability.MiscServices.Pasteboard 1397 1398**返回值：** 1399 1400| 类型 | 说明 | 1401| -------- | -------- | 1402| Promise<[PasteData](#pastedata)> | Promise对象，返回系统剪贴板数据。 | 1403 1404**错误码：** 1405 1406以下错误码的详细介绍请参见[剪贴板错误码](../errorcodes/errorcode-pasteboard.md)。 1407 1408| 错误码ID | 错误信息 | 1409| -------- | -------- | 1410| 12900003 | Another copy or paste is in progress. | 1411 1412**示例：** 1413 1414```js 1415let systemPasteboard = pasteboard.getSystemPasteboard(); 1416systemPasteboard.getData().then((pasteData) => { 1417 let text = pasteData.getPrimaryText(); 1418}).catch((err) => { 1419 console.error('Failed to get PasteData. Cause: ' + err.message); 1420}) 1421``` 1422 1423### hasData<sup>9+</sup> 1424 1425hasData(callback: AsyncCallback<boolean>): void 1426 1427判断系统剪贴板中是否有内容，使用callback异步回调。 1428 1429**系统能力：** SystemCapability.MiscServices.Pasteboard 1430 1431**参数：** 1432 1433| 参数名 | 类型 | 必填 | 说明 | 1434| -------- | -------- | -------- | -------- | 1435| callback | AsyncCallback<boolean> | 是 | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | 1436 1437**示例：** 1438 1439```js 1440let systemPasteboard = pasteboard.getSystemPasteboard(); 1441systemPasteboard.hasData((err, data) => { 1442 if (err) { 1443 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1444 return; 1445 } 1446 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1447}); 1448``` 1449 1450### hasData<sup>9+</sup> 1451 1452hasData(): Promise<boolean> 1453 1454判断系统剪贴板中是否有内容，使用Promise异步回调。 1455 1456**系统能力：** SystemCapability.MiscServices.Pasteboard 1457 1458**返回值：** 1459 1460| 类型 | 说明 | 1461| -------- | -------- | 1462| Promise<boolean> | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | 1463 1464**示例：** 1465 1466```js 1467let systemPasteboard = pasteboard.getSystemPasteboard(); 1468systemPasteboard.hasData().then((data) => { 1469 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1470}).catch((err) => { 1471 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1472}); 1473``` 1474 1475### clear<sup>(deprecated)</sup> 1476 1477clear(callback: AsyncCallback<void>): void 1478 1479清空系统剪贴板内容，使用callback异步回调。 1480> **说明：** 1481> 1482> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.clearData](#cleardata9)替代。 1483 1484**系统能力：** SystemCapability.MiscServices.Pasteboard 1485 1486**参数：** 1487 1488| 参数名 | 类型 | 必填 | 说明 | 1489| -------- | -------- | -------- | -------- | 1490| callback | AsyncCallback<void> | 是 | 回调函数。当成功清空时，err为undefined；否则为错误对象。 | 1491 1492**示例：** 1493 1494```js 1495systemPasteboard.clear((err, data) => { 1496 if (err) { 1497 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 1498 return; 1499 } 1500 console.info('Succeeded in clearing the PasteData.'); 1501}); 1502``` 1503 1504### clear<sup>(deprecated)</sup> 1505 1506clear(): Promise<void> 1507 1508清空系统剪贴板内容，使用Promise异步回调。 1509> **说明：** 1510> 1511> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[pasteboard.clearData](#cleardata9-1)替代。 1512 1513**系统能力：** SystemCapability.MiscServices.Pasteboard 1514 1515**返回值：** 1516 1517| 类型 | 说明 | 1518| -------- | -------- | 1519| Promise<void> | 无返回结果的Promise对象。 | 1520 1521**示例：** 1522 1523```js 1524systemPasteboard.clear().then((data) => { 1525 console.info('Succeeded in clearing the PasteData.'); 1526}).catch((err) => { 1527 console.error(`Failed to clear the PasteData. Cause: ${err.message}`); 1528}); 1529``` 1530 1531### getPasteData<sup>(deprecated)</sup> 1532 1533getPasteData( callback: AsyncCallback<PasteData>): void 1534 1535读取系统剪贴板内容，使用callback异步回调。 1536> **说明：** 1537> 1538> 从 API Version 6 开始支持，从 API Version 9 开始废弃，建议使用[getData](#getdata9)替代。 1539 1540**系统能力：** SystemCapability.MiscServices.Pasteboard 1541 1542**参数：** 1543 1544| 参数名 | 类型 | 必填 | 说明 | 1545| -------- | -------- | -------- | -------- | 1546| callback | AsyncCallback<[PasteData](#pastedata)> | 是 | 回调函数。当读取成功，err为undefined，data为返回的系统剪贴板数据；否则返回错误对象。 | 1547 1548**示例：** 1549 1550```js 1551let systemPasteboard = pasteboard.getSystemPasteboard(); 1552systemPasteboard.getPasteData((err, pasteData) => { 1553 if (err) { 1554 console.error('Failed to get PasteData. Cause: ' + err.message); 1555 return; 1556 } 1557 let text = pasteData.getPrimaryText(); 1558}); 1559``` 1560 1561### getPasteData<sup>(deprecated)</sup> 1562 1563getPasteData(): Promise<PasteData> 1564 1565读取系统剪贴板内容，使用Promise异步回调。 1566> **说明：** 1567> 1568> 从 API Version 6 开始支持，从 API Version 9 开始废弃，建议使用[getData](#getdata9-1)替代。 1569 1570**系统能力：** SystemCapability.MiscServices.Pasteboard 1571 1572**返回值：** 1573 1574| 类型 | 说明 | 1575| -------- | -------- | 1576| Promise<[PasteData](#pastedata)> | Promise对象，返回系统剪贴板数据。 | 1577 1578**示例：** 1579 1580```js 1581let systemPasteboard = pasteboard.getSystemPasteboard(); 1582systemPasteboard.getPasteData().then((pasteData) => { 1583 let text = pasteData.getPrimaryText(); 1584}).catch((err) => { 1585 console.error('Failed to get PasteData. Cause: ' + err.message); 1586}) 1587``` 1588 1589### hasPasteData<sup>(deprecated)</sup> 1590 1591hasPasteData(callback: AsyncCallback<boolean>): void 1592 1593判断系统剪贴板中是否有内容，使用callback异步回调。 1594> **说明：** 1595> 1596> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[hasData](#hasdata9)替代。 1597 1598**系统能力：** SystemCapability.MiscServices.Pasteboard 1599 1600**参数：** 1601 1602| 参数名 | 类型 | 必填 | 说明 | 1603| -------- | -------- | -------- | -------- | 1604| callback | AsyncCallback<boolean> | 是 | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | 1605 1606**示例：** 1607 1608```js 1609systemPasteboard.hasPasteData((err, data) => { 1610 if (err) { 1611 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1612 return; 1613 } 1614 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1615}); 1616``` 1617 1618### hasPasteData<sup>(deprecated)</sup> 1619 1620hasPasteData(): Promise<boolean> 1621 1622判断系统剪贴板中是否有内容，使用Promise异步回调。 1623> **说明：** 1624> 1625> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[hasData](#hasdata9-1)替代。 1626 1627**系统能力：** SystemCapability.MiscServices.Pasteboard 1628 1629**返回值：** 1630 1631| 类型 | 说明 | 1632| -------- | -------- | 1633| Promise<boolean> | 返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。 | 1634 1635**示例：** 1636 1637```js 1638systemPasteboard.hasPasteData().then((data) => { 1639 console.info(`Succeeded in checking the PasteData. Data: ${data}`); 1640}).catch((err) => { 1641 console.error(`Failed to check the PasteData. Cause: ${err.message}`); 1642}); 1643``` 1644 1645### setPasteData<sup>(deprecated)</sup> 1646 1647setPasteData(data: PasteData, callback: AsyncCallback<void>): void 1648 1649将数据写入系统剪贴板，使用callback异步回调。 1650> **说明：** 1651> 1652> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[setData](#setdata9)替代。 1653 1654**系统能力：** SystemCapability.MiscServices.Pasteboard 1655 1656**参数：** 1657 1658| 参数名 | 类型 | 必填 | 说明 | 1659| -------- | -------- | -------- | -------- | 1660| data | [PasteData](#pastedata) | 是 | PasteData对象。 | 1661| callback | AsyncCallback<void> | 是 | 回调函数。当写入成功，err为undefined，否则为错误对象。 | 1662 1663**示例：** 1664 1665```js 1666let pasteData = pasteboard.createPlainTextData('content'); 1667let systemPasteboard = pasteboard.getSystemPasteboard(); 1668systemPasteboard.setPasteData(pasteData, (err, data) => { 1669 if (err) { 1670 console.error('Failed to set PasteData. Cause: ' + err.message); 1671 return; 1672 } 1673 console.info('Succeeded in setting PasteData.'); 1674}); 1675``` 1676### setPasteData<sup>(deprecated)</sup> 1677 1678setPasteData(data: PasteData): Promise<void> 1679 1680将数据写入系统剪贴板，使用Promise异步回调。 1681> **说明：** 1682> 1683> 从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用[setData](#setdata9-1)替代。 1684 1685**系统能力：** SystemCapability.MiscServices.Pasteboard 1686 1687**参数：** 1688 1689| 参数名 | 类型 | 必填 | 说明 | 1690| -------- | -------- | -------- | -------- | 1691| data | [PasteData](#pastedata) | 是 | PasteData对象。 | 1692 1693**返回值：** 1694 1695| 类型 | 说明 | 1696| -------- | -------- | 1697| Promise<void> | 无返回结果的Promise对象。 | 1698 1699**示例：** 1700 1701```js 1702let pasteData = pasteboard.createPlainTextData('content'); 1703let systemPasteboard = pasteboard.getSystemPasteboard(); 1704systemPasteboard.setPasteData(pasteData).then((data) => { 1705 console.info('Succeeded in setting PasteData.'); 1706}).catch((err) => { 1707 console.error('Failed to set PasteData. Cause: ' + err.message); 1708}); 1709```