第8章 HarmonyOs开发图解 剪贴板HarmonyOS 学习系统 | 阶段二进阶实战期建议学习时长1 周学习目标序号能力1掌握 SystemPasteboard 和 PasteData 的使用方法2能实现文本复制、粘贴和剪贴板监听功能3理解剪贴板的权限限制和大小限制内容讲解8.1 剪贴板 API社区大门口有一块便签板系统剪贴板。你在便签板上贴了一张写着张三 电话 138xxxx的便签。不管你是谁哪个应用只要走到便签板前应用获得前台焦点就能看到最新的便签内容。新的便签会覆盖旧的便签板上的内容不会因为你离开就消失。HarmonyOS 的SystemPasteboard提供了系统剪贴板操作接口PasteData是剪贴板数据的载体。获取剪贴板对象// 获取系统剪贴板实例SystemPasteboardpasteboardSystemPasteboard.getSystemPasteboard(this);写入剪贴板// 创建纯文本数据PasteDatapasteDataPasteData.createPlainTextData(Hello HarmonyOS!);// 写入剪贴板pasteboard.setPasteData(pasteData);PasteData支持多种数据类型创建方法数据类型说明createPlainTextData()纯文本最常用的类型createHtmlData()HTML 文本保留富文本格式createUriData()URI 数据传递链接或文件路径createIntentData()Intent 数据传递 Intent 对象createMimeData()MIME 类型自定义 MIME 类型数据读取剪贴板// 检查剪贴板是否有数据if(pasteboard.hasPasteData()){// 获取剪贴板数据PasteDatadatapasteboard.getPasteData();// 获取主文本Stringtextdata.getPrimaryText();// 获取 HTML 文本Stringhtmldata.getPrimaryHtml();// 获取 URIUriuridata.getPrimaryUri();// 使用数据...}清除剪贴板// 清除剪贴板内容pasteboard.clearPasteData();8.2 剪贴板变化监听SystemPasteboard 支持监听剪贴板内容变化// 添加监听器pasteboard.addPasteDataChangedListener(newIPasteDataChangedListener(){OverridepublicvoidonChanged(){HiLog.info(TAG,剪贴板内容发生了变化);// 获取最新内容if(pasteboard.hasPasteData()){StringnewTextpasteboard.getPasteData().getPrimaryText();HiLog.info(TAG,新内容: newText);}}});// 移除监听器pasteboard.removePasteDataChangedListener(listener);8.3 实战要点剪贴板的权限限制只有前台获得焦点的应用才有读取剪贴板的权限系统默认输入法除外。这意味着后台服务无法直接读取剪贴板内容。剪贴板的大小限制剪贴板单次传递内容不能超过 500KB。如果需要传递大数据量应使用文件或分布式数据管理来实现。剪贴板的覆盖机制每次调用setPasteData()都会覆盖之前的剪贴板内容。系统剪贴板是全局唯一的所有应用共享同一个剪贴板。8.4 综合实战剪贴板工具页面下面是一个完整的剪贴板工具页面实现包含复制、粘贴和监听功能publicclassClipboardSliceextendsAbilitySlice{privatestaticfinalHiLogLabelTAGnewHiLogLabel(0,0,ClipboardSlice);privateSystemPasteboardpasteboard;privateTexttvPasteContent;OverridepublicvoidonStart(Intentintent){super.onStart(intent);super.setUIContent(ResourceTable.Layout_ability_clipboard);pasteboardSystemPasteboard.getSystemPasteboard(this);tvPasteContent(Text)findComponentById(ResourceTable.Id_tv_paste_content);ButtonbtnCopy(Button)findComponentById(ResourceTable.Id_btn_copy);ButtonbtnPaste(Button)findComponentById(ResourceTable.Id_btn_paste);ButtonbtnClear(Button)findComponentById(ResourceTable.Id_btn_clear);// 复制按钮btnCopy.setClickedListener(component-{TextFieldtfInput(TextField)findComponentById(ResourceTable.Id_tf_input);StringtexttfInput.getText();if(!text.isEmpty()){PasteDatadataPasteData.createPlainTextData(text);pasteboard.setPasteData(data);newToastDialog(getContext()).setText(已复制到剪贴板).show();}});// 粘贴按钮btnPaste.setClickedListener(component-{if(pasteboard.hasPasteData()){PasteDatadatapasteboard.getPasteData();Stringtext(data.getPrimaryText()!null)?data.getPrimaryText().toString():无文本内容;tvPasteContent.setText(剪贴板内容: text);}else{tvPasteContent.setText(剪贴板为空);}});// 清除按钮btnClear.setClickedListener(component-{pasteboard.clearPasteData();tvPasteContent.setText(剪贴板已清除);});// 添加剪贴板变化监听pasteboard.addPasteDataChangedListener(()-{getUITaskDispatcher().asyncDispatch(()-{if(pasteboard.hasPasteData()){PasteDatadatapasteboard.getPasteData();StringnewText(data.getPrimaryText()!null)?data.getPrimaryText().toString():非文本;tvPasteContent.setText(监听到变化: newText);}});});}OverridepublicvoidonStop(){// 移除监听防止内存泄漏pasteboard.removePasteDataChangedListener(null);super.onStop();}}8.5 剪贴板安全注意事项敏感数据不要将密码、Token 等敏感信息写入剪贴板任何前台应用都可以读取及时清除使用完剪贴板后建议调用clearPasteData()清除内容监听器泄漏在onStop()或onDestroy()中务必移除监听器线程安全剪贴板变化监听回调在非 UI 线程更新 UI 需要通过getUITaskDispatcher()代码速查卡API功能示例SystemPasteboard.getSystemPasteboard()获取剪贴板实例SystemPasteboard.getSystemPasteboard(this)PasteData.createPlainTextData()创建纯文本数据PasteData.createPlainTextData(text)setPasteData()写入剪贴板pasteboard.setPasteData(pasteData)getPasteData()读取剪贴板PasteData data pasteboard.getPasteData()hasPasteData()检查是否有数据pasteboard.hasPasteData()clearPasteData()清除剪贴板pasteboard.clearPasteData()addPasteDataChangedListener()添加变化监听pasteboard.addPasteDataChangedListener(listener)removePasteDataChangedListener()移除变化监听pasteboard.removePasteDataChangedListener(listener)与 Android/iOS 对比特性HarmonyOSAndroidiOS剪贴板管理类SystemPasteboardClipboardManagerUIPasteboard.general数据类型文本/HTML/URI/Intent文本/URI/Intent文本/URL/图像/颜色大小限制500KB无硬性限制无硬性限制读取权限前台聚焦应用所有应用前台应用变化监听addPasteDataChangedListeneraddPrimaryClipChangedListener无原生支持创建数据PasteDataClipDataUIPasteboard 数据⚠️ 踩坑回忆录做剪贴板功能时踩了一个大坑我写了一个后台服务定时读取剪贴板内容结果发现怎么都读不到。后来才知道只有前台获得焦点的应用才有读取剪贴板的权限系统默认输入法除外。另外剪贴板单次传递内容不能超过 500KB大数据量还是得用文件或分布式数据管理。还有一个容易忽略的问题SystemPasteboard.getSystemPasteboard(this)中的this参数是 Context如果你在非 UI 组件中调用比如工具类需要传入正确的 Context否则会返回一个无效的剪贴板实例。必做实操任务序号任务难度1实现一个复制文本到剪贴板的按钮功能★☆☆2实现从剪贴板读取文本并显示的粘贴功能★☆☆3添加剪贴板变化监听器实时显示剪贴板内容变化★★☆4尝试写入不同类型的数据文本、HTML、URI并分别读取★★☆5实现一个简易的剪贴板管理工具显示剪贴板历史记录★★★学习检查清单能说出 SystemPasteboard 和 PasteData 的关系能实现文本的复制和粘贴理解剪贴板的权限限制知道剪贴板的大小限制500KB能实现剪贴板变化监听了解 PasteData 支持的数据类型知道什么时候应该清除剪贴板进阶方向实现剪贴板与分布式数据管理结合的跨设备剪贴板了解系统输入法对剪贴板的特殊权限学习在 Service 中无法读取剪贴板的替代方案