Clipboard API

概念与用法

系统剪贴板 是托管浏览器的操作系统的一个数据缓冲区，用于短期数据存储和/或文档或应用程序之间的数据传输。它通常实现为一个匿名的、临时的 数据缓冲区，有时也称为粘贴缓冲区，可以通过定义的编程接口从环境中的大多数或所有程序访问。

剪贴板 API 允许用户在安全上下文中以编程方式读写系统剪贴板中的文本和其他类型的数据，前提是用户已满足安全注意事项中概述的标准。

当剪贴板因 cut、copy 和 paste 操作而修改时，会触发事件。事件有默认操作，例如 `copy` 操作默认将当前选区复制到系统剪贴板。事件处理程序可以覆盖默认操作——有关更多信息，请参阅每个事件。

接口

Clipboard 安全上下文

提供一个接口，用于向系统剪贴板读写文本和数据。规范称之为“异步剪贴板 API”。

ClipboardEvent

表示提供与剪贴板修改相关的信息的事件，即 cut、copy 和 paste 事件。规范称之为“剪贴板事件 API”。

ClipboardItem 安全上下文

表示单个项目格式，用于读写数据。

其他接口的扩展

剪贴板 API 扩展了以下 API，并添加了列出的功能。

Navigator.clipboard 只读 安全上下文

返回一个 Clipboard 对象，该对象提供对系统剪贴板的读写访问。

Element copy 事件

每当用户发起复制操作时触发的事件。

Element cut 事件

每当用户发起剪切操作时触发的事件。

Element paste 事件

每当用户发起粘贴操作时触发的事件。

安全注意事项

剪贴板 API 允许用户在安全上下文中以编程方式读写系统剪贴板中的文本和其他类型的数据。

从剪贴板读取时，规范要求用户最近与页面进行了交互（临时用户激活），并且调用是在用户与浏览器或操作系统“粘贴元素”（例如在原生上下文菜单中选择“粘贴”）交互的结果下进行的。实际上，浏览器通常允许不满足这些要求的读取操作，但会施加其他要求（例如权限或每个操作的提示）。对于写入剪贴板，规范期望页面已获得 Permissions API 的 `clipboard-write` 权限，并且浏览器也可能需要临时用户激活。浏览器可能会对访问剪贴板的方法施加额外的限制。

浏览器实现已偏离规范。差异已在浏览器兼容性部分捕获，并且当前状态总结如下：

Chromium 浏览器

• 如果规范不允许读取，并且文档具有焦点，它会触发一个请求使用 `clipboard-read` 权限的请求，如果权限被授予（无论是用户接受了提示，还是权限已预先授予），则读取成功。
• 写入操作需要 `clipboard-write` 权限或临时激活。如果授予了权限，则该权限会持久化，并且不再需要临时激活。
• 对于访问剪贴板的 <iframe> 元素，必须允许 HTTP Permissions-Policy 权限 `clipboard-read` 和 `clipboard-write`。

Firefox 和 Safari

• 如果规范不允许读取，但仍然满足临时用户激活，则会触发一个临时上下文菜单形式的用户提示，其中只有一个“粘贴”选项（该选项在 1 秒后启用），如果用户选择该选项，则读取成功。
• 写入操作需要临时激活。
• 如果读取同源剪贴板内容，则会抑制粘贴提示，但不会抑制读取跨域内容。
• Firefox 或 Safari 不支持（也不计划支持）`clipboard-read` 和 `clipboard-write` 权限。

Firefox Web 扩展

• 读取文本仅对具有 `clipboardRead` Web 扩展权限的扩展可用。拥有此权限后，扩展不需要临时激活或粘贴提示。
• 写入文本在安全上下文和临时激活下可用。拥有 `clipboardWrite` Web 扩展权限后，不需要临时激活。

示例

访问剪贴板

系统剪贴板通过 Navigator.clipboard 全局对象访问。

此代码段从剪贴板获取文本并将其附加到找到的第一个类名为 `editor` 的元素。由于 readText() 在剪贴板不是文本时返回空字符串，因此此代码是安全的。

navigator.clipboard
  .readText()
  .then(
    (clipText) => (document.querySelector(".editor").innerText += clipText),
  );

规范

浏览器兼容性

api.Clipboard

api.ClipboardEvent

api.ClipboardItem

另见

• 异步剪贴板文章的图片支持