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