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