1# 使用剪贴板进行复制粘贴 2<!--Kit: Basic Services Kit--> 3<!--Subsystem: MiscServices--> 4<!--Owner: @yangxiaodong41--> 5<!--Designer: @guo867--> 6<!--Tester: @maxiaorong2--> 7<!--Adviser: @fang-jinxu--> 8 9## 场景介绍 10 11[剪贴板](../../reference/apis-basic-services-kit/js-apis-pasteboard.md)为开发者提供数据的复制粘贴能力。当需要使用复制粘贴等功能时，例如：复制文字内容到备忘录中粘贴，复制图库照片到文件管理粘贴，就可以通过剪贴板来完成。 12 13## 约束限制 14 15- 剪贴板内容包含剪贴板系统服务元数据和应用设置的数据，总大小上限默认为128MB，PC/2in1设备可通过系统配置修改上限，有效范围为128MB~2GB。 16- 为保证剪贴板数据的准确性，同一时间只能支持一个复制操作。 17- API version 12及之后，系统为提升用户隐私安全保护能力，剪贴板读取接口增加[权限管控](get-pastedata-permission-guidelines.md)。 18 19## 使用基础数据类型进行复制粘贴 20 21剪贴板支持使用基础数据类型进行复制粘贴，当前支持的基础数据类型有文本、HTML、URI、Want、PixelMap。ArkTS接口与NDK接口支持数据类型不完全一致，使用时须匹配接口支持类型。 22 23新开发的应用建议使用本方案实现复制粘贴功能。 24 25### ArkTS接口与NDK接口数据类型对应关系 26| ArkTS数据类型 | NDK数据类型 | 27| -------- |----------------------------------------------------------------------------------------------------------------------------------------| 28| MIMETYPE_PIXELMAP : "pixelMap" | UDMF_META_OPENHARMONY_PIXEL_MAP : "openharmony.pixel-map" | 29| MIMETYPE_TEXT_HTML : "text/html" | UDMF_META_HTML : "general.html" | 30| MIMETYPE_TEXT_PLAIN : "text/plain" | UDMF_META_PLAIN_TEXT : "general.plain-text" | 31| MIMETYPE_TEXT_URI : "text/uri" | UDMF_META_GENERAL_FILE_URI : "general.file-uri" | 32| MIMETYPE_TEXT_WANT : "text/want" | NDK接口不支持该数据类型。 | 33 34ArkTS数据类型对应剪贴板类型，详见[ohos.pasteboard](../../reference/apis-basic-services-kit/js-apis-pasteboard.md)。NDK数据类型对应统一数据管理框架，详见[UDMF](../../reference/apis-arkdata/capi-udmf.md)。 35 36### 接口说明 37 38详细接口见[接口文档](../../reference/apis-basic-services-kit/js-apis-pasteboard.md#getdata9)。 39 40使用剪贴板getData接口获取到uri类型数据之后，请使用文件管理的[fs.copy](../../reference/apis-core-file-kit/js-apis-file-fs.md#fscopy11)接口获取文件。 41 42| 名称 | 说明 | 43| -------- |----------------------------------------------------------------------------------------------------------------------------------------| 44| setData(data: PasteData, callback: AsyncCallback<void>): void | 将数据写入系统剪贴板，使用callback异步回调。 | 45| setData(data: PasteData): Promise<void> | 将数据写入系统剪贴板，使用Promise异步回调。 | 46| getData( callback: AsyncCallback<PasteData>): void | 读取系统剪贴板内容，使用callback异步回调。 | 47| getData(): Promise<PasteData> | 读取系统剪贴板内容，使用Promise异步回调。 | 48| getDataSync(): PasteData | 读取系统剪贴板内容, 此接口为同步接口，不能与SetData同线程调用。 | 49 50### 示例代码 51```ts 52import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 53import { BusinessError, pasteboard } from '@kit.BasicServicesKit'; 54 55export default class EntryAbility extends UIAbility { 56 async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> { 57 // 获取系统剪贴板对象 58 let text = "test"; 59 // 创建一条纯文本类型的剪贴板内容对象 60 let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, text); 61 // 将数据写入系统剪贴板 62 let systemPasteboard = pasteboard.getSystemPasteboard(); 63 await systemPasteboard.setData(pasteData); 64 //从系统剪贴板中读取数据 65 systemPasteboard.getData().then((data) => { 66 let outputData = data; 67 // 从剪贴板数据中获取条目数量 68 let recordCount = outputData.getRecordCount(); 69 // 从剪贴板数据中获取对应条目信息 70 for (let i = 0; i < recordCount; i++) { 71 let record = outputData.getRecord(i).toPlainText(); 72 console.info('Get data success, record:' + record); 73 } 74 }).catch((error: BusinessError) => { 75 // 处理异常场景 76 }) 77 } 78} 79``` 80 81## 使用统一数据类型进行复制粘贴 82 83为了方便剪贴板与其他应用间进行数据交互，减少数据类型适配的工作量，剪贴板支持使用统一数据对象进行复制粘贴。详细的统一数据对象请见[标准化数据通路](../../reference/apis-arkdata/js-apis-data-unifiedDataChannel.md)文档介绍。 84 85剪贴板支持使用基础数据类型进行复制粘贴，当前支持的基础数据类型有文本、HTML。ArkTS接口与NDK接口支持数据类型不完全一致，使用时须匹配接口支持类型。 86 87### 接口说明 88 89详细接口见[接口文档](../../reference/apis-basic-services-kit/js-apis-pasteboard.md#getunifieddata12)。 90 91| 名称 | 说明 | 92| -------- |----------------------------------------------------------------------------------------------------------------------------------------| 93| setUnifiedData(data: udc.UnifiedData): Promise\<void\> | 将统一数据对象的数据写入系统剪贴板。 94| setUnifiedDataSync(data: udc.UnifiedData): void | 将统一数据对象的数据写入系统剪贴板，此接口为同步接口。 | 95| getUnifiedData(): Promise\<udc.UnifiedData\> | 从系统剪贴板中读取统一数据对象的数据。 | 96| getUnifiedDataSync(): udc.UnifiedData | 从系统剪贴板中读取统一数据对象的数据，此接口为同步接口。 97 98### 示例代码 99```ts 100import {BusinessError, pasteboard} from '@kit.BasicServicesKit'; 101import { unifiedDataChannel, uniformDataStruct, uniformTypeDescriptor } from '@kit.ArkData'; 102 103// 构造一条PlainText数据 104let plainText : uniformDataStruct.PlainText = { 105 uniformDataType: uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, 106 textContent : 'PLAINTEXT_CONTENT', 107 abstract : 'PLAINTEXT_ABSTRACT', 108} 109let record = new unifiedDataChannel.UnifiedRecord(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT, plainText); 110let data = new unifiedDataChannel.UnifiedData(); 111data.addRecord(record); 112 113// 向系统剪贴板中存入一条PlainText数据 114let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 115systemPasteboard.setUnifiedData(data).then((data: void) => { 116 console.info('Succeeded in setting UnifiedData.'); 117 // 存入成功，处理正常场景 118}).catch((err: BusinessError) => { 119 console.error('Failed to set UnifiedData. Cause: ' + err.message); 120 // 处理异常场景 121}); 122 123// 从系统剪贴板中读取这条text数据 124systemPasteboard.getUnifiedData().then((data) => { 125 let records: Array<unifiedDataChannel.UnifiedRecord> = data.getRecords(); 126 for (let j = 0; j < records.length; j++) { 127 if (records[j].getType() === uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 128 let text = records[j].getValue() as uniformDataStruct.PlainText; 129 console.info(`${j + 1}.${text.textContent}`); 130 } 131 } 132}).catch((err: BusinessError) => { 133 console.error('Failed to get UnifiedData. Cause: ' + err.message); 134 // 处理异常场景 135}); 136``` 137 138<!--RP1--> 139<!--RP1End-->