17370845950

Clipboard API 使用需满足安全上下文（HTTPS/localhost）和用户手势触发两个条件；writeText() 写文本、readText() 读文本（权限受限）、write() 写图片（兼容性差），均需异常处理且不可静默执行。

Clipboard API 只能在安全上下文和用户手势触发下使用

浏览器不允许页面随意读写剪贴板，navigator.clipboard 必须满足两个硬性条件：当前页面运行在 https://（或 localhost）协议下，且调用必须由用户主动触发（如 click、keydown 事件），不能在定时器、异步回调或页面加载时直接执行。

• 在 HTTP 环境下调用 navigator.clipboard.writeText() 会直接抛出 SecurityError
• 在 setTimeout 或 fetch().then() 中调用，即使页面是 HTTPS，也会被拒绝并报错 NotAllowedError: Write permission denied
• Chrome 和 Edge 对 document.execCommand('copy') 已完全弃用，仅保留兼容路径，不推荐新项目使用

写入文本：用 clipboard.writeText() 替代 execCommand

现代标准写法简洁明确，返回 Promise，失败可捕获异常。注意它只接受字符串，不支持 HTML 或富文本。

button.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText('Hello, world!');
    console.log('复制成功');
  } catch (err) {
    console.error('复制失败:', err.name); // 可能是 'NotAllowedError' 或 'SecurityError'
  }
});

• 不要传入 undefined 或 null，会立即 reject 并抛 TypeError
• 如果用户禁用了剪贴板权限（如某些隐私模式或企业策略），也会触发 NotAllowedError
• 移动端 Safari 目前仅支持 writeText()，不支持 readText()（iOS 16.4+ 开始部分支持）

读取文本：clipboard.readText() 需要显式权限且兼容性有限

读取比写入限制更严，不仅需要用户手势，还可能触发权限提示（取决于浏览器策略）。不是所有环境都允许读取。

button.addEventListener('click', async () => {
  try {
    const text = await navigator.clipboard.readText();
    console.log('粘贴板内容:', text);
  } catch (err) {
    // 常见错误：'NotAllowedError'（未授权）、'NotFoundError'（无文本类型数据）、'SecurityError'
    console.error('读取失败:', err.name);
  }
});

• Firefox 默认禁用 readText()，需手动开启 dom.events.asyncClipboard.readText 配置项（仅限开发者调试）
• 读取结果是纯文本，即使剪贴板里有 HTML 表格或图片链接，也只会返回空字符串或纯文本片段
• 不能绕过权限自动读取——没有“静默读取”机制，每次调用都视为一次敏感操作

写入图片：clipboard.write() 支持 Blob，但支持度仍不统一

想复制截图或 canvas 导出图？得用底层 clipboard.write()，传入 ClipboardItem 数组。目前只有 Chrome/Edge 较稳定，Safari 和 Firefox 基本不支持。

async function copyImage(blob) {
  try {
    await navigator.clipboard.write([
      new ClipboardItem({ 'image/png': blob })
    ]);
  } catch (err) {
    console.error('图片复制失败:', err.name); // 如 'NotSupportedError' 或 'DataError'
  }
}

• blob 必须是有效的图像类型（image/png、image/jpeg），其他 MIME 类型会被忽略或报 DataError
• 不能直接传 canvas.toDataURL() 字符串，必须先转成 Blob（可用 fetch(url).then(r => r.blob()) 或 new Blob([uint8Array], {type: 'image/png'})）
• 即使调用成功，也无法保证目标应用（如微信、钉钉）能正确解析并粘贴该图片——这是跨应用兼容问题，非 API 层能解决

实际项目中，最稳妥的路径是：写文本用 writeText() + 用户点击触发；读文本谨慎使用，优先引导用户手动粘贴；图片复制按需降级为下载按钮或 base64 链接。别指望一次调用通吃所有浏览器和场景。