HarmonyOS ArkWeb 系列之网页里的复制粘贴，没你想的那么简单

文章目录先搞清楚Web 里有几种剪贴板操作Async Clipboard API 是什么ArkTS 侧怎么接入H5 侧的完整实现整体流程图权限问题说清楚踩坑记录写在最后说实话刚开始做 Web 嵌入的时候我以为剪贴板功能是最简单的那一类——不就是CtrlC、CtrlV的事吗结果一实际操作发现坑不少。Web 页面里有两套剪贴板机制用法完全不一样权限申请也有讲究。今天把这块彻底说清楚。先搞清楚Web 里有几种剪贴板操作在 HarmonyOS 的 Web 组件里剪贴板相关的能力分两层第一层Async Clipboard API现代浏览器标准这是 W3C 的标准接口在 H5 页面的 JavaScript 里用navigator.clipboard调用。支持读写文本、HTML、图片等富内容。第二层Web 组件属性控制这是 ArkTS 层能控制的比如用.copyOptions()限制用户能不能复制内容。今天先把第一层讲透——Async Clipboard API 怎么在 Web 组件里用。Async Clipboard API 是什么大白话解释浏览器提供了一个叫navigator.clipboard的对象让网页 JS 代码可以主动读写系统剪贴板。它有 4 个核心方法方法作用writeText(text)把纯文本写入剪贴板write(items)把富内容HTML、图片等写入剪贴板readText()从剪贴板读取纯文本read()从剪贴板读取富内容这 4 个方法都返回 Promise所以要配合async/await使用。ArkTS 侧怎么接入ArkTS 这边其实很简单就是一个标准的 Web 组件加载包含剪贴板逻辑的 HTML 文件就够了import{webview}fromkit.ArkWeb;EntryComponentstruct WebComponent{controller:webview.WebviewControllernewwebview.WebviewController();build(){Column(){Web({src:$rawfile(clipboard.html),controller:this.controller})}}}关键点$rawfile(clipboard.html)加载的是放在resources/rawfile/目录下的本地 HTML 文件。剪贴板的实际逻辑都在 HTML 的script里实现。H5 侧的完整实现下面是一个完整的剪贴板操作示例覆盖了 4 个核心方法!DOCTYPEhtmlhtmllangzhheadmetacharsetUTF-8metanameviewportcontentwidthdevice-width, initial-scale1.0titleClipboard API 演示/titlestylebody{font-family:sans-serif;padding:20px;}#output{margin-top:20px;border:1px solid #ccc;padding:10px;min-height:50px;border-radius:4px;}button{margin:4px;padding:8px 16px;cursor:pointer;}#result{color:#4caf50;margin:10px 0;}/style/headbodyh2剪贴板 API 演示/h2divbuttonidcopyTextBtn复制文本/buttonbuttonidcopyHtmlBtn复制 HTML/button/divdivbuttonidpasteTextBtn粘贴文本/buttonbuttonidpasteHtmlBtn粘贴 HTML/buttonbuttonidclearBtn清空/button/divdividresult/divdividoutputcontenteditabletrue粘贴内容将显示在这里/divscriptconsttextContent这是一段纯文本内容;consthtmlContentstrongem这是一段 HTML 内容/em/strong;// 方法一writeText() —— 写入纯文本asyncfunctioncopyText(){try{awaitnavigator.clipboard.writeText(textContent);document.getElementById(result).innerText✓ 文本已写入剪贴板;}catch(err){document.getElementById(result).innerText✗ 复制失败err.message;}}// 方法二write() —— 写入富内容HTMLasyncfunctioncopyHtml(){try{constitemnewClipboardItem({text/html:newBlob([htmlContent],{type:text/html})});awaitnavigator.clipboard.write([item]);document.getElementById(result).innerText✓ HTML 已写入剪贴板;}catch(err){document.getElementById(result).innerText✗ 复制失败err.message;}}// 方法三readText() —— 读取纯文本asyncfunctionpasteText(){try{consttextawaitnavigator.clipboard.readText();document.getElementById(output).innerTexttext;document.getElementById(result).innerText✓ 文本已从剪贴板读取;}catch(err){document.getElementById(result).innerText✗ 粘贴失败err.message;}}// 方法四read() —— 读取富内容asyncfunctionpasteHtml(){try{constitemsawaitnavigator.clipboard.read();for(constitemofitems){if(item.types.includes(text/html)){constblobawaititem.getType(text/html);consthtmlawaitblob.text();document.getElementById(output).innerHTMLhtml;document.getElementById(result).innerText✓ HTML 已从剪贴板读取;return;}}document.getElementById(result).innerText✗ 剪贴板中没有 HTML 内容;}catch(err){document.getElementById(result).innerText✗ 粘贴失败err.message;}}functionclearOutput(){document.getElementById(result).innerText;document.getElementById(output).innerHTML;}document.getElementById(copyTextBtn).addEventListener(click,copyText);document.getElementById(copyHtmlBtn).addEventListener(click,copyHtml);document.getElementById(pasteTextBtn).addEventListener(click,pasteText);document.getElementById(pasteHtmlBtn).addEventListener(click,pasteHtml);document.getElementById(clearBtn).addEventListener(click,clearOutput);/script/body/html代码里有几个容易踩坑的地方ClipboardItem构造时键名必须是 MIME 类型字符串比如text/html、text/plain、image/pngnavigator.clipboard.read()返回的是ClipboardItem[]每个 item 可能有多种类型要用item.types先判断所有操作都要用try/catch包裹——用户可能拒绝权限授予整体流程图权限问题说清楚writeText()和write()通常不需要特别的权限弹窗因为是主动写入操作。但readText()和read()在某些场景下会触发系统权限请求——读取剪贴板是敏感操作系统需要用户明确授权。如果你的应用读取剪贴板时一直报错先检查两件事H5 代码是否在用户手势回调里比如click事件触发剪贴板读取Web 组件所在的页面权限配置是否有问题踩坑记录坑一write()的 Blob type 必须精确// 错误type 写错了不会报错但数据不对constitemnewClipboardItem({html:newBlob([htmlContent],{type:html})});// 正确必须是完整 MIME 类型constitemnewClipboardItem({text/html:newBlob([htmlContent],{type:text/html})});坑二忘记处理 Promise 拒绝Async Clipboard API 的所有方法都可能被拒绝比如用户禁止了权限。没有try/catch的话拒绝会变成未捕获的 Promise 异常很难排查。坑三contenteditable元素的innerHTML和innerText别混用粘贴 HTML 内容时用innerHTML粘贴纯文本时用innerText或textContent。如果用innerHTML显示纯文本用户输入中含有等字符会被当作 HTML 解析。写在最后Async Clipboard API 用起来并不难核心就是 4 个方法记住它们的异步性质就好。复杂的地方在于权限机制和不同内容类型的处理。下一篇我们会讲剪贴板事件监听——当用户在 Web 组件里进行复制/粘贴操作时H5 页面如何捕获这些事件并做自定义处理。