菜鸟教程
Reference Web API reference

Clipboard API 参考

Clipboard API 用于在浏览器中读取或写入系统剪贴板。开发中最常见的是 navigator.clipboard.writeText()，用于在用户点击按钮后复制一段文本。

语法

js 
await navigator.clipboard.writeText(text);

参数

  • text：要写入剪贴板的字符串。

返回值

返回 Promise<void>。写入成功时 resolve；如果页面没有权限、不是安全上下文或不是用户主动触发，可能 reject。

示例

js 
async function copyText(text) {
  try {
    await navigator.clipboard.writeText(text);
    return true;
  } catch (error) {
    console.error(error);
    return false;
  }
}

可运行演示

下面的演示会在点击按钮后复制输入框内容。剪贴板写入通常要求 HTTPS、安全上下文和用户主动点击。

在线代码演示
源码 
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Clipboard writeText 演示</title>
    <style>
      * { box-sizing: border-box; }
      body { margin: 0; padding: 24px; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #0f172a; background: #f8fafc; }
      .demo { max-width: 720px; margin: 0 auto; padding: 20px; border: 1px solid #dbeafe; border-radius: 12px; background: #ffffff; }
      label { display: grid; gap: 8px; font-weight: 600; }
      textarea { min-height: 120px; padding: 12px; border: 1px solid #cbd5e1; border-radius: 8px; font: inherit; resize: vertical; }
      button { margin-top: 14px; padding: 10px 14px; border: 0; border-radius: 8px; color: #ffffff; background: #2563eb; cursor: pointer; }
      p { min-height: 24px; margin: 12px 0 0; color: #475569; }
    </style>
  </head>
  <body>
    <main class="demo">
      <label>
        要复制的文本
        <textarea id="copyText">https://caijiao.org/reference/web-api/clipboard</textarea>
      </label>
      <button id="copyButton" type="button">复制到剪贴板</button>
      <p id="status">点击按钮后调用 navigator.clipboard.writeText。</p>
    </main>
    <script>
      const textarea = document.querySelector("#copyText");
      const button = document.querySelector("#copyButton");
      const status = document.querySelector("#status");
      button.addEventListener("click", async () => {
        try {
          await navigator.clipboard.writeText(textarea.value);
          status.textContent = "已复制。";
        } catch (error) {
          status.textContent = "复制失败，请检查 HTTPS、浏览器权限或手动选择文本。";
        }
      });
    </script>
  </body>
</html>

常见错误

  • 在 HTTP 页面、部分 iframe 或没有用户点击的异步流程中调用，可能触发 NotAllowedError。
  • 复制失败时按钮没有反馈，用户会以为功能无效；应显示失败提示，并允许手动选择文本。
  • 不要把复制逻辑放在页面加载时自动执行，应放到 click 等用户操作中。

相关内容

相关内容