Electron clipboard 模块实战指南基于 W3C Clipboard API 的系统剪贴板操作与自定义 MIME 格式【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electronElectron 的clipboard模块运行在主进程是当前版本中面向系统剪贴板进行复制/粘贴的唯一官方入口。本篇以 clipboard API 文档 为核心完整覆盖其 W3C 风格方法read/write/readText/writeText/has/clear、Electron 自定义 MIME 格式bookmark、findtext、osclipboard、web前缀以及 Linux 特有的selection剪贴板并结合仓库中的 JavaScript 封装层lib/browser/api/clipboard.ts与 C 原生实现shell/browser/api/electron_api_clipboard.cc说明底层调用链读完后你可以掌握跨平台多格式剪贴板读写、原子写入与原生格式穿透raw format round-trip的完整实现方案。模块定位与设计模型clipboard模块的设计目标是复刻 W3C Clipboard APInavigator.clipboard的接口形态但提供的是不受隐私沙箱限制的原生剪贴板访问能力clipboard.read()返回PromiseClipboardItem[]其中ClipboardItem携带一个或多个 MIME 类型到Blob负载的映射clipboard.write()接受ClipboardItem[]数组所有条目在一次调用内原子性地提交到系统剪贴板与渲染进程的navigator.clipboard不同主进程的clipboard能读到文件的真实绝对路径例如text/uri-list不做隐私脱敏并且能访问平台级原始剪贴板格式。需要注意一条已废弃行为见 docs/api/clipboard.md 中的 history 注释在渲染进程中直接使用clipboardAPI 已被废弃该模块只在主进程中可用进程模型定义参见 glossary。[!NOTE]ClipboardItem不能被用户代码继承Electron 内置类的通用限制详见 FAQ。Electron 自定义 MIME 格式除了标准 MIME 类型text/plain、text/html、text/rtf、image/png、image/jpeg等Electron 暴露了一小组自定义格式遵循 W3C 自定义格式提案但使用electron前缀而非web以避免命名冲突自定义格式平台说明electron application/bookmark全平台读取侧 Linux 不支持URL 书签。唯一例外读写两侧都是ClipboardBookmark对象{ title, url }而非Blob即getType(electron application/bookmark)解析为对象electron application/findtext仅 macOS活跃应用查找粘贴板find pasteboard的内容electron application/osclipboard;formatname全平台平台特定剪贴板格式的原始负载。name是平台格式名Windows 如HTML FormatmacOS 如public.utf8-plain-text。clipboard.read()还会把没有标准 MIME 映射的任意平台格式归入该自定义格式暴露因此原始 OS 格式可以原样往返写进去和读出来是同一个 MIME 字符串此外read()和write()都接受任意 MIME 类型包括以web前缀后跟空格如web application/x.my-format开头的 W3C web 自定义格式const { clipboard, ClipboardItem } require(electron) async function writeClipboard () { await clipboard.write([ new ClipboardItem({ web application/x.my-app-clip: new Blob([arbitrary payload]) }) ]) } writeClipboard()核心方法详解clipboard.readText()返回Promisestring以纯文本形式读取剪贴板内容对标 W3Cnavigator.clipboard.readTextconst { clipboard } require(electron) async function readText () { await clipboard.writeText(hello i am a bit of text!) const text await clipboard.readText() console.log(text) // hello i am a bit of text! } readText()从源码结构看electron_api_clipboard.cc 中Clipboard::ReadText是常见调用的快速路径直接走ui::Clipboard::ReadText绕过了getType()的逐 MIME 分派开销在 Windows 上若 Unicode 读取为空还会自动回退到ReadAsciiTextReadText中的IS_WIN分支。clipboard.writeText(text)textstring返回Promisevoid文本写入完成时 resolve对标 W3Cnavigator.clipboard.writeTextconst { clipboard } require(electron) async function writeClipboardText () { await clipboard.writeText(hello i am a bit of text!) } writeClipboardText()clipboard.read()返回PromiseClipboardItem[]resolve 为携带剪贴板全部内容的ClipboardItem数组const { clipboard } require(electron) async function dumpClipboard () { const items await clipboard.read() for (const item of items) { for (const type of item.types) { const blob await item.getType(type) console.log(type, blob) } } } dumpClipboard()原生侧的类型枚举管线EnumerateAvailableTypes见 electron_api_clipboard.cc解释了types数组是如何聚合出来的它按顺序合并三个来源ReadAvailableStandardAndCustomFormatNames— 标准 MIME 类型及web前缀的 W3C 自定义格式GetAllAvailableFormats— 其余所有原始平台格式。标准格式会被过滤掉避免text/plain和electron application/osclipboard;formatpublic.utf8-plain-text重复暴露同一条内容其余包装为 osclipboard MIMEmacOS 上还在此处探测 find pasteboard 并追加findtext伪 MIMEReadURL非 Linux— 若剪贴板中有书签则追加electron application/bookmark。因此read()返回的types是一份完整的聚合 MIME 列表而每个类型的具体负载由getType(type)按需从平台剪贴板惰性读取。clipboard.write(data)dataClipboardItem[] — 通过new ClipboardItem({ [mime]: payload })构造的条目数组返回Promisevoid。单次write()调用中的所有条目原子地提交到系统剪贴板const { clipboard, ClipboardItem, nativeImage } require(electron) const png nativeImage.createFromPath(/path/to/icon.png).toPNG() async function writeClipboard () { await clipboard.write([ new ClipboardItem({ text/plain: hello, text/html: bhello/b, image/png: new Blob([png], { type: image/png }), electron application/bookmark: { title: Electron, url: https://electronjs.org } }) ]) } writeClipboard()JS 封装层如何保证先解析、后原子提交可以清晰地从源码看出lib/browser/api/clipboard.ts 中的wrapClipboard拦截write先把每个ClipboardItem的Blob/Promise负载全部 resolve 成BufferkToNative再经一次同步的原生write提交。而 C 侧Clipboard::Writeelectron_api_clipboard.cc用单个ui::ScopedClipboardWriter依次写入所有条目析构时才真正提交——这就是原子性的实现来源。两个值得注意的运行时约束均可在测试与源码中验证write()参数必须是ClipboardItem数组非数组或非ClipboardItem元素会抛出TypeErrorclipboard.read()返回的ClipboardItem是只读的轻量读取器不能回传给write()必须重新构造新的ClipboardItem见 lib/browser/api/clipboard-item.ts 中[kToNative]的显式拒绝逻辑。clipboard.has(mimetype)mimetypestring - 要检查的 MIME 类型返回Promiseboolean剪贴板中存在该 MIME 数据时 resolve 为true。要检查原始平台格式如public/utf8-plain-text需使用 osclipboard 自定义格式const { clipboard } require(electron) async function check () { const hasFormat await clipboard.has(text/html) console.log(hasFormat) // true 或 false const rawFormat electron application/osclipboard;formatpublic/utf8-plain-text const hasRawFormat await clipboard.has(rawFormat) } check()实现上has与read共用同一条聚合枚举管线EnumerateAvailableTypes后做成员判定所以has对read暴露的每一种 MIME——标准类型、web前缀格式、osclipboard 原始格式、bookmark、macOS findtext——都保持一致的判定结果。clipboard.clear()清除剪贴板内容同步方法。安全边界MIME 键即能力面clipboard-item.md 文档中有一条重要警告不要直接用不可信对象构造ClipboardItem例如从渲染进程经 IPC 传来的负载。MIME 键本身是能力面text/uri-list会把真实文件引用放到 OS 剪贴板允许粘贴文件到其他应用electron application/osclipboard;format...和web前缀格式会写入原始平台数据。从未经自己审核的数据构建ClipboardItem之前务必对 MIME 类型和负载结构做白名单校验。Linux 特有clipboard.selection属性在 Linux 上还存在一个selection剪贴板对应 X11 的 PRIMARY 选择通过clipboard.selection子命名空间暴露它与顶层clipboard接口完全同构const { clipboard } require(electron) async function run () { await clipboard.selection.writeText(Example string) console.log(await clipboard.selection.readText()) } run()两个剪贴板相互独立通过clipboard.selection写入的数据不会影响clipboard.read()的返回值反之亦然。注意selection剪贴板不支持W3C web 自定义格式。[!NOTE]clipboard.selection是只读属性Linux 上为一个Clipboard对象暴露与顶层一致的read、write、readText、writeText、has、clear方法其他平台为undefined。从源码结构看electron_api_clipboard.cc 中的Initialize在 Linux 分支上调用两次PopulateClipboardObject——分别绑定kCopyPaste和kSelection两个ui::ClipboardBuffer——同一套 C 方法通过绑定期注入不同的 buffer 实例化为两个 JS 对象。JS 层lib/browser/api/clipboard.ts仅在binding.selection存在时才挂selection包装对象。测试视角的行为验证仓库中的 spec/api-clipboard-spec.ts 对上述文档声明提供了逐项的行为验证可作为可信行为参考image/*负载通过clipboard.writegetType完成NativeImage往返写入后读回的数据 URL 一致剪贴板只有文本时read()的types中不出现任何 image 类型readText()/writeText()均返回Promise且 Unicode 文本如千江有水千江月万里无云万里天正确往返has()对已写入的标准 MIME、web前缀自定义 MIME如web text/plainelectron-test、以及 osclipboard 原始格式public/utf8-plain-text均能正确返回true未写入时返回false。小结能力API关键约束纯文本读写readText()/writeText(text)返回 PromiseWindows 自动回退 ASCII 读取多格式原子写入write(ClipboardItem[])所有条目单次原子提交不能接受read()产生的读取器全量读取read()返回单元素ClipboardItem[]types为聚合 MIME 列表负载惰性读取存在性检查has(mimetype)与read()的暴露面严格一致原始格式需用 osclipboard MIME清空clear()同步Linux 选择剪贴板clipboard.selection.*与系统剪贴板隔离不支持 web 自定义格式这套 API 的实用价值在于主进程既能以 W3C 标准形态操作常见文本/HTML/图片/书签/文件列表又能通过electron application/osclipboard;format...穿透到 Windows 注册格式、macOS pasteboard 类型等任意平台格式实现与其他桌面应用的数据互操作——这正是以 W3C Clipboard API 为骨架、以平台原始格式为逃生舱的完整落地。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考