剪贴板 API
剪贴板 API 提供了响应剪贴板命令(剪切、复制和粘贴)以及异步读写系统剪贴板的能力。
注意: 使用此 API 优先于已弃用的 document.execCommand()
方法来访问剪贴板。
注意: 此 API 不可用于 Web Workers(不通过 WorkerNavigator
公开)。
概念和用法
接口
Clipboard
安全上下文-
提供了一个接口,用于读写文本和数据到系统剪贴板或从系统剪贴板中读取。规范将此称为“异步剪贴板 API”。
ClipboardEvent
ClipboardItem
安全上下文-
表示读取或写入数据时使用的单个项目格式。
其他接口的扩展
安全注意事项
剪贴板 API 允许用户以编程方式在 安全上下文 中读写文本和其他类型的数据到系统剪贴板或从系统剪贴板中读取。
规范要求用户最近与页面交互才能从剪贴板中读取(需要 短暂用户激活)。如果读取操作是由用户与浏览器或操作系统“粘贴元素”(例如上下文菜单)交互引起的,则浏览器预计会提示用户确认。对于写入剪贴板,规范期望页面已获得 权限 API 的 clipboard-write
权限,并且浏览器也可能需要 短暂用户激活。浏览器可能会对使用这些方法访问剪贴板设置额外的限制。
浏览器实现已偏离规范。差异在 浏览器兼容性 部分中有所体现,当前状态在下面概述
Chromium 浏览器
- 读取需要获得 权限 API 的
clipboard-read
权限。不需要短暂激活。 - 写入需要
clipboard-read
权限或短暂激活。如果授予了权限,则该权限将持久化,并且不需要进一步的短暂激活。 - HTTP 权限策略 权限
clipboard-read
和clipboard-write
必须允许用于访问剪贴板的<iframe>
元素。 - 当读取操作是由浏览器或操作系统“粘贴元素”引起时,不会显示持久粘贴提示。
Firefox 和 Safari
- 读取和写入需要短暂激活。
- 如果读取同源剪贴板内容,则会抑制粘贴提示,但跨源内容则不会。
- Firefox 或 Safari 不支持
clipboard-read
和clipboard-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 表格仅在浏览器中加载