剪贴板 API

剪贴板 API 提供了响应剪贴板命令(剪切、复制和粘贴)以及异步读写系统剪贴板的能力。

注意: 使用此 API 优先于已弃用的 document.execCommand() 方法来访问剪贴板。

注意: 此 API 不可用Web Workers(不通过 WorkerNavigator 公开)。

概念和用法

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

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

事件是由于修改剪贴板的 cutcopypaste 操作触发的。这些事件具有默认操作,例如,copy 操作默认将当前选择复制到系统剪贴板。事件处理程序可以覆盖默认操作 - 请参阅每个事件以获取更多信息。

接口

Clipboard 安全上下文

提供了一个接口,用于读写文本和数据到系统剪贴板或从系统剪贴板中读取。规范将此称为“异步剪贴板 API”。

ClipboardEvent

表示提供与剪贴板修改相关的信息的事件,即 cutcopypaste 事件。规范将此称为“剪贴板事件 API”。

ClipboardItem 安全上下文

表示读取或写入数据时使用的单个项目格式。

其他接口的扩展

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

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

Element copy 事件

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

Element cut 事件

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

Element paste 事件

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

安全注意事项

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

规范要求用户最近与页面交互才能从剪贴板中读取(需要 短暂用户激活)。如果读取操作是由用户与浏览器或操作系统“粘贴元素”(例如上下文菜单)交互引起的,则浏览器预计会提示用户确认。对于写入剪贴板,规范期望页面已获得 权限 APIclipboard-write 权限,并且浏览器也可能需要 短暂用户激活。浏览器可能会对使用这些方法访问剪贴板设置额外的限制。

浏览器实现已偏离规范。差异在 浏览器兼容性 部分中有所体现,当前状态在下面概述

Chromium 浏览器

  • 读取需要获得 权限 APIclipboard-read 权限。不需要短暂激活。
  • 写入需要 clipboard-read 权限或短暂激活。如果授予了权限,则该权限将持久化,并且不需要进一步的短暂激活。
  • HTTP 权限策略 权限 clipboard-readclipboard-write 必须允许用于访问剪贴板的 <iframe> 元素。
  • 当读取操作是由浏览器或操作系统“粘贴元素”引起时,不会显示持久粘贴提示。

Firefox 和 Safari

  • 读取和写入需要短暂激活。
  • 如果读取同源剪贴板内容,则会抑制粘贴提示,但跨源内容则不会。
  • Firefox 或 Safari 不支持 clipboard-readclipboard-write 权限(并且不打算支持)。

Firefox Web 扩展

  • 读取文本仅适用于具有 Web 扩展 clipboardRead 权限的扩展。使用此权限,扩展不需要短暂激活或粘贴提示。
  • 在安全上下文中并通过短暂激活可以写入文本。使用 Web 扩展 clipboardWrite 权限,不需要短暂激活。

示例

访问剪贴板

可以通过 Navigator.clipboard 全局访问系统剪贴板。

此代码片段从剪贴板中获取文本并将其附加到找到的第一个具有类 editor 的元素。由于 readText()(以及 read())在剪贴板不是文本时返回一个空字符串,因此此代码是安全的。

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

规范

规范
剪贴板 API 和事件
# 剪贴板接口
剪贴板 API 和事件
# 剪贴板事件接口
剪贴板 API 和事件
# 剪贴板项

浏览器兼容性

api.Clipboard

BCD 表格仅在浏览器中加载

api.ClipboardEvent

BCD 表格仅在浏览器中加载

api.ClipboardItem

BCD 表格仅在浏览器中加载

另请参阅