1# 使用剪贴板进行延迟复制粘贴 2 3## 场景介绍 4 5[剪贴板服务](../../reference/apis-basic-services-kit/js-apis-pasteboard.md)主要提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。 6 7反复执行复制操作时，剪贴板缓存中会存储多余数据从而导致内存增加，为了优化内存以及后续支持指定数据类型粘贴，剪贴板提供了延迟复制粘贴的功能。 8 9用户复制使用延迟复制技术的应用内的数据时，该条真实数据不会立即写入剪贴板服务的缓存中，而是等需要粘贴时，再从应用获取数据。 10 11## 约束限制 12 13- 剪贴板内容大小<128MB时支持使用。 14 15## 使用基于Record级别的延迟复制粘贴（推荐） 16 17本方案可以在粘贴前查询数据type信息，应用可以据此决定是否向剪贴板请求数据，因此建议使用本方案实现延迟复制功能。 18 19### 接口说明 20 21详细接口见[Pasteboard文档](../../reference/apis-basic-services-kit/_pasteboard.md)和[UDMF接口文档](../../reference/apis-arkdata/_u_d_m_f.md)。 22 23| 名称 | 说明 | 24| -------- |----------------------------------------------------------------------| 25| OH_UdmfRecordProvider* OH_UdmfRecordProvider_Create() | 创建一个指向统一数据提供者的指针。 | 26| int OH_UdmfRecordProvider_SetData(OH_UdmfRecordProvider* provider, void* context, const OH_UdmfRecordProvider_GetData callback, const UdmfData_Finalize finalize) | 设置统一数据提供者的回调函数。 | 27| int OH_UdmfRecord_SetProvider(OH_UdmfRecord* pThis, const char* const* types, unsigned int count, OH_UdmfRecordProvider* provider) | 将统一数据提供者配置到OH_UdmfRecord中。 | 28| int OH_Pasteboard_SetData(OH_Pasteboard* pasteboard, OH_UdmfData* data) | 向剪贴板中写入数据。 | 29| OH_UdmfData * OH_Pasteboard_GetData (OH_Pasteboard* pasteboard, int* status) | 获取剪贴板中的数据。 | 30| OH_UdmfRecord** OH_UdmfData_GetRecords(OH_UdmfData* pThis, unsigned int* count) | 获取OH_UdmfData中全部的数据记录。 | 31 32### 开发步骤 33 34 下面以纯文本类型和HTML类型数据为例，说明如何向剪贴板服务设置延迟复制数据。 35 36 为了代码可读性，代码中省略了各个步骤操作结果的校验，实际开发中需要确认每次调用的成功。 37 381. 引用头文件。 39 40 ```c 41 #include <database/pasteboard/oh_pasteboard.h> 42 #include <database/udmf/udmf.h> 43 #include <database/udmf/udmf_meta.h> 44 #include <database/udmf/uds.h> 45 ``` 46 472. 定义`OH_UdmfRecordProvider`的数据提供函数和实例注销回调函数。 48 49 ```c 50 // 1. 获取数据时触发的提供剪贴板数据的回调函数。 51 void* GetDataCallback(void* context, const char* type) { 52 // 纯文本类型 53 if (strcmp(type, UDMF_META_PLAIN_TEXT) == 0) { 54 // 创建纯文本类型的Uds对象。 55 OH_UdsPlainText* udsText = OH_UdsPlainText_Create(); 56 // 设置纯文本内容。 57 OH_UdsPlainText_SetContent(udsText, "hello world"); 58 return udsText; 59 } 60 // HTML类型 61 else if (strcmp(type, UDMF_META_HTML) == 0) { 62 // 创建HTML类型的Uds对象。 63 OH_UdsHtml* udsHtml = OH_UdsHtml_Create(); 64 // 设置HTML内容。 65 OH_UdsHtml_SetContent(udsHtml, "<div>hello world</div>"); 66 return udsHtml; 67 } 68 return nullptr; 69 } 70 // 2. OH_UdmfRecordProvider销毁时触发的回调函数。 71 void ProviderFinalizeCallback(void* context) { 72 printf("OH_UdmfRecordProvider finalize."); 73 } 74 ``` 75 763. 在剪贴板中准备延迟复制数据。需要注意，此步骤完成后纯文本类型数据与HTML类型数据并未真正写入剪贴板服务，只有当数据使用者从`OH_UdmfRecord`中获取`OH_UdsPlainText`或`OH_UdsHtml`时，才会触发上文定义的`GetDataCallback`数据提供函数，从中得到数据。 77 78 ```c 79 // 3. 创建OH_UdmfRecord对象。 80 OH_UdmfRecord* record = OH_UdmfRecord_Create(); 81 82 // 4. 创建OH_UdmfRecordProvider对象，并设置用于提供延迟数据、析构的两个回调函数。 83 OH_UdmfRecordProvider* provider = OH_UdmfRecordProvider_Create(); 84 OH_UdmfRecordProvider_SetData(provider, (void*)record, GetDataCallback, ProviderFinalizeCallback); 85 86 // 5. 将provider绑定到record，并设置支持的数据类型。 87 const char* types[2] = { UDMF_META_PLAIN_TEXT, UDMF_META_HTML }; 88 OH_UdmfRecord_SetProvider(record, types, 2, provider); 89 90 // 6. 创建OH_UdmfData对象，并向OH_UdmfData中添加OH_UdmfRecord。 91 OH_UdmfData* setData = OH_UdmfData_Create(); 92 OH_UdmfData_AddRecord(setData, record); 93 94 // 7. 创建OH_Pasteboard对象，将数据写入剪贴板中。 95 OH_Pasteboard* pasteboard = OH_Pasteboard_Create(); 96 OH_Pasteboard_SetData(pasteboard, setData); 97 ``` 98 994. 从剪贴板获取延迟复制数据。 100 101 ```c 102 // 8. 从剪贴板获取OH_UdmfData。 103 int status = -1; 104 OH_UdmfData* getData = OH_Pasteboard_GetData(pasteboard, &status); 105 106 // 9. 获取OH_UdmfData中的所有OH_UdmfRecord。 107 unsigned int recordCount = 0; 108 OH_UdmfRecord** getRecords = OH_UdmfData_GetRecords(getData, &recordCount); 109 110 // 10. 遍历OH_UdmfRecord。 111 for (unsigned int recordIndex = 0; recordIndex < recordCount; ++recordIndex) { 112 OH_UdmfRecord* record = getRecords[recordIndex]; 113 114 // 11. 查询OH_UdmfRecord中的数据类型。 115 unsigned typeCount = 0; 116 char** recordTypes = OH_UdmfRecord_GetTypes(record, &typeCount); 117 118 // 12. 遍历数据类型。 119 for (unsigned int typeIndex = 0; typeIndex < typeCount; ++typeCount) { 120 char* recordType = recordTypes[typeIndex]; 121 122 // 纯文本类型 123 if (strcmp(recordType, UDMF_META_PLAIN_TEXT) == 0) { 124 // 创建纯文本类型的Uds对象 125 OH_UdsPlainText* udsText = OH_UdsPlainText_Create(); 126 // 从record中获取纯文本类型的Uds对象 127 OH_UdmfRecord_GetPlainText(record, udsText); 128 // 从Uds对象中获取内容 129 const char* content = OH_UdsPlainText_GetContent(udsText); 130 } 131 // HTML类型 132 else if (strcmp(recordType, UDMF_META_HTML) == 0) { 133 // 创建HTML类型的Uds对象 134 OH_UdsHtml* udsHtml = OH_UdsHtml_Create(); 135 // 从record中获取HTML类型的Uds对象 136 OH_UdmfRecord_GetHtml(record, udsHtml); 137 // 从Uds对象中获取内容 138 const char* content = OH_UdsHtml_GetContent(udsHtml); 139 } 140 } 141 } 142 ``` 143 1445. 使用完毕后需要及时释放相关对象的内存。 145 146 ```c 147 OH_UdsPlainText_Destroy(udsText); 148 OH_UdsHtml_Destroy(udsHtml); 149 OH_UdmfRecordProvider_Destroy(provider); 150 OH_UdmfRecord_Destroy(record); 151 OH_UdmfData_Destroy(setData); 152 OH_UdmfData_Destroy(getData); 153 OH_Pasteboard_Destroy(pasteboard); 154 ``` 155 156 157## 使用基于PasteData级别的延迟复制粘贴 158 159本方案不支持粘贴前对数据type的查询。 160 161### 接口说明 162 163| 名称 | 说明 | 164| -------- |----------------------------------------------------------------------| 165| setUnifiedData(data: udc.UnifiedData): Promise\<void> | 将统一数据类型的数据写入系统剪贴板，在使用延迟复制粘贴功能时，不可与getUnifiedDataSync同线程调用。| 166| setUnifiedDataSync(data: udc.UnifiedData): void | 将统一数据类型的数据写入系统剪贴板，此接口为同步接口，在使用延迟复制粘贴功能时，不可与getUnifiedDataSync同线程调用。| 167| getUnifiedData(): Promise\<udc.UnifiedData> | 从系统剪贴板中读取统一数据类型的数据。| 168| getUnifiedDataSync(): udc.UnifiedData | 从系统剪贴板中读取统一数据类型的数据，此接口为同步接口，在使用延迟复制粘贴功能时，不可与setUnifiedData和setUnifiedDataSync同线程调用。| 169| setAppShareOptions(shareOptions: ShareOption): void | 应用设置本应用剪贴板数据的可粘贴范围。| 170| removeAppShareOptions(): void | 应用删除本应用设置的剪贴板数据可粘贴范围配置。| 171 172### 开发步骤 173 1741. 导入pasteboard,unifiedDataChannel和uniformTypeDescriptor模块。 175 176 ```ts\ 177 import {unifiedDataChannel, uniformTypeDescriptor} from '@kit.ArkData'; 178 import {BusinessError, pasteboard} from '@kit.BasicServicesKit' 179 ``` 180 1812. 构造一条PlainText数据,并书写获取延时数据的函数。 182 183 ```ts 184 let plainTextData = new unifiedDataChannel.UnifiedData(); 185 let GetDelayPlainText = ((dataType:string) => { 186 let plainText = new unifiedDataChannel.PlainText(); 187 plainText.details = { 188 Key: 'delayPlaintext', 189 Value: 'delayPlaintext', 190 }; 191 plainText.textContent = 'delayTextContent'; 192 plainText.abstract = 'delayTextContent'; 193 plainTextData.addRecord(plainText); 194 return plainTextData; 195 }); 196 ``` 197 1983. 向系统剪贴板中存入一条PlainText数据。 199 200 ```ts 201 let SetDelayPlainText = (() => { 202 plainTextData.properties.shareOptions = unifiedDataChannel.ShareOptions.CROSS_APP; 203 // 跨应用使用时设置为CROSS_APP，本应用内使用时设置为IN_APP 204 plainTextData.properties.getDelayData = GetDelayPlainText; 205 pasteboard.getSystemPasteboard().setUnifiedData(plainTextData).then(()=>{ 206 // 存入成功，处理正常场景 207 }).catch((error: BusinessError) => { 208 // 处理异常场景 209 }); 210 }) 211 ``` 212 2134. 从系统剪贴板中读取这条text数据。 214 215 ```ts 216 let GetPlainTextUnifiedData = (() => { 217 pasteboard.getSystemPasteboard().getUnifiedData().then((data) => { 218 let outputData = data; 219 let records = outputData.getRecords(); 220 if (records[0].getType() == uniformTypeDescriptor.UniformDataType.PLAIN_TEXT) { 221 let record = records[0] as unifiedDataChannel.PlainText; 222 console.log('GetPlainText success, type:' + records[0].getType + ', details:' + 223 JSON.stringify(record.details) + ', textContent:' + record.textContent + ', abstract:' + record.abstract); 224 } else { 225 console.log('Get Plain Text Data No Success, Type is: ' + records[0].getType()); 226 } 227 }).catch((error: BusinessError) => { 228 //处理异常场景 229 }) 230 }) 231 ``` 232 2335. 应用设置本应用剪贴板数据的可粘贴范围。 234 235 ```ts 236 let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 237 try { 238 systemPasteboard.setAppShareOptions(pasteboard.ShareOption.INAPP); 239 console.info('Set app share options success.'); 240 } catch (err) { 241 let error: BusinessError = err as BusinessError; 242 //处理异常场景 243 } 244 ``` 245 2466. 应用删除本应用设置的剪贴板数据可粘贴范围配置。 247 248 ```ts 249 let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard(); 250 try { 251 systemPasteboard.removeAppShareOptions(); 252 console.info('Remove app share options success.'); 253 } catch (err) { 254 let error: BusinessError = err as BusinessError; 255 //处理异常场景 256 } 257 ```