无需登录 数据私有 本地保存

剪贴板读取权限演示 - Clipboard API

12
0
0
0
正在检测环境...
读取权限 clipboard-read
检测中
点击下方"读取剪贴板"按钮时将触发权限请求
写入权限 clipboard-write
检测中
写入通常自动授权,部分浏览器可能需要用户手势
读取剪贴板

读取当前系统剪贴板中的文本或图片内容

读取结果
等待读取...
等待读取图片...
写入剪贴板

将文本或图片写入系统剪贴板

快捷填充:
注意:URL需支持跨域访问(CORS)
粘贴测试区(监听 Ctrl+V / 长按粘贴)

点击下方区域后按 Ctrl+V(Mac: ⌘+V)粘贴,无需Clipboard API权限即可捕获内容

点击此处,然后按 Ctrl+V 粘贴 支持文本和图片
等待粘贴...
读取历史记录
0 条记录
暂无记录,读取剪贴板后将自动保存
Clipboard API 常见问题与知识点

Clipboard API 是现代浏览器提供的异步剪贴板访问接口,通过 navigator.clipboard 对象暴露。与传统 document.execCommand('copy') 相比:

  • 异步操作:Clipboard API 返回 Promise,不会阻塞主线程。
  • 读取能力:Clipboard API 支持读取剪贴板内容(需授权),而 execCommand 只能写入。
  • 丰富数据类型:支持文本、HTML、图片(PNG/JPEG)等多种 MIME 类型。
  • 安全性:Clipboard API 必须在安全上下文(HTTPS 或 localhost)中使用,且读取需要用户明确授权。
  • 标准化:execCommand 已被标记为废弃,Clipboard API 是 W3C 标准。

剪贴板可能包含敏感信息(密码、银行卡号、私人照片等)。浏览器强制要求 Clipboard API 仅在安全上下文(Secure Context)中可用,即通过 HTTPS 访问的页面或本地开发环境(localhost/127.0.0.1)。这防止了中间人攻击和恶意脚本在非安全页面中窃取剪贴板数据。您可以通过 window.isSecureContext 检查当前页面是否为安全上下文。

使用 navigator.permissions.query() 可以查询权限状态:

// 查询读取权限
const readStatus = await navigator.permissions.query({name: 'clipboard-read'});
console.log(readStatus.state); // 'granted' | 'denied' | 'prompt'

// 查询写入权限(部分浏览器支持)
const writeStatus = await navigator.permissions.query({name: 'clipboard-write'});
console.log(writeStatus.state);

注意:Firefox 不完全支持 clipboard-read 权限查询;clipboard-write 查询在多数浏览器中可能不被识别。建议始终做好异常处理。

移动端支持情况因平台和浏览器而异:

  • Android Chrome:较好地支持 Clipboard API(读取和写入),需 HTTPS。
  • iOS Safari(14+):支持 writeText(),但对 read()readText() 的支持有限,通常需要用户手势触发。
  • Android Firefox:支持写入,读取支持有限。
  • 微信内置浏览器等:Clipboard API 支持不完整,可能需要降级方案。

建议在移动端使用粘贴事件(paste event)作为补充方案,本工具提供的"粘贴测试区"即适用于此类场景。

当用户拒绝剪贴板读取权限时,navigator.clipboard.read() 会抛出 NotAllowedError。处理方式:

  1. 友好提示:告知用户需要授权才能读取剪贴板。
  2. 引导设置:提示用户在浏览器地址栏左侧的权限设置中重新启用剪贴板访问。
  3. 降级方案:提供粘贴事件监听区域(如本工具的"粘贴测试区"),让用户通过 Ctrl+V 手动粘贴。
  4. 检测权限状态:使用 Permissions API 提前检测,避免不必要的 API 调用。

通过 navigator.clipboard.read() 返回的 ClipboardItem 对象可包含多种 MIME 类型:

  • text/plain — 纯文本
  • text/html — 带格式的 HTML 内容
  • image/png — PNG 图片
  • image/jpeg — JPEG 图片
  • image/webp — WebP 图片(部分浏览器)

使用 item.types 可以查看剪贴板中所有可用的数据类型,使用 item.getType(mimeType) 获取特定类型的 Blob 数据。

两者有本质区别:

  • Clipboard API:程序化访问剪贴板,可主动读取和写入,需要安全上下文和用户授权。
  • paste 事件:响应用户的粘贴操作(Ctrl+V),从 event.clipboardData 获取数据,无需额外权限,但需要用户主动触发。

paste 事件是 Clipboard API 的重要补充,尤其在权限被拒绝或浏览器不支持 Clipboard API 读取时,仍可通过粘贴事件获取剪贴板内容。本工具同时提供两种方式以确保最大兼容性。