# Clipboard API 参考

URL: https://caijiao.org/reference/web-api/clipboard
Source: docs/reference/web-api/clipboard.md
Description: Clipboard API Reference，整理 navigator.clipboard.writeText 的语法、权限限制、可运行演示、常见错误和相关问题。

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、安全上下文和用户主动点击。

[在线代码演示](/web-api/demos/clipboard-write-text.html)

## 常见错误

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

## 相关内容

- [Web API Reference](/reference/web-api/)
- [JavaScript 如何复制文本到剪贴板](/how-to/javascript/copy-text-to-clipboard)
- [JavaScript 如何读取剪贴板文本](/how-to/javascript/clipboard-read)
- [JavaScript 教程](/javascript/)
- [MDN Clipboard.writeText](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText)