writeText() 必须在用户手势（如click、keydown）同步上下文中调用，否则会因权限拒绝失败；需避免异步回调、effect中调用，兼容旧版可降级使用execCommand；注意移动端Safari支持及空字符串、换行符等细节处理。
writeText 方法必须在用户手势触发的上下文中调用
直接在页面加载时或定时器里调用 navigator.clipboard.writeText() 会失败，浏览器会抛出 DOMException: Permission denied 或静默拒绝。这是因为 Clipboard API 要求操作必须由明确的用户交互（如 click、tap、keydown）发起，防止恶意脚本静默窃取/覆盖剪贴板内容。
常见错误现象：点击按钮没反应，控制台报错 NotAllowedError: writeText() called without user activation。
- 确保绑定在
click、mousedown或keydown（且按键可触发，如 Enter）等事件处理器中 - 避免在异步回调（如
setTimeout、fetch.then）里直接调用，除非该回调本身仍在用户手势的同步执行链中 - React/Vue 等框架中，不要在 effect 或 computed 里调用；必须放在事件处理函数内
需要显式请求 clipboard-write 权限（仅部分场景）
大多数现代浏览器（Chrome 66+、Edge 79+、Firefox 122+）在用户手势上下文中调用 writeText() 时会自动授权，无需提前申请。但若你在 iframe 中操作、或页面被嵌入沙箱环境（如 sandbox="allow-scripts" 但未加 allow-same-origin），就可能遇到权限拒绝。
此时可主动检查并请求权限：
立即学习“前端免费学习笔记（深入）”；
if (navigator.permissions) {
const result = await navigator.permissions.query({ name: 'clipboard-write' });
if (result.state === 'granted' || result.state === 'prompt') {
await navigator.clipboard.writeText('hello');
}
}
- 注意：
navigator.permissions在非安全上下文（HTTP）中不可用，必须使用 HTTPS - 权限状态为
denied时无法恢复，需引导用户手动开启（如 Chrome 地址栏右侧的锁图标 → 网站设置 → 剪贴板） - 移动端 Safari 对
writeText支持较晚（iOS 16.4+），且不支持navigator.permissions
兼容性 fallback：document.execCommand('copy') 已废弃但仍有用
虽然 document.execCommand('copy') 在 Chrome 87+ 和 Firefox 85+ 中已被标记为废弃，且在跨域 iframe 或无焦点元素时失效，但它仍是 Safari 15.6 之前、以及部分旧版 Android WebView 的唯一选择。
实操建议是「先试新 API，失败则降级」：
async function copyText(text) {
try {
await navigator.clipboard.writeText(text);
} catch (err) {
// 降级：创建临时 textarea 并 execCommand
const el = document.createElement('textarea');
el.value = text;
el.setAttribute('readonly', '');
el.style.position = 'absolute';
el.style.left = '-9999px';
document.body.appendChild(el);
el.select();
document.execCommand('copy');
document.body.removeChild(el);
}
}
- 降级方案中必须保证
el.select()成功，否则execCommand('copy')无效 —— 所以要插入 DOM、设为可见（哪怕离屏）、再选中 - Safari 16.4+ 已支持
writeText，但对中文等 Unicode 文本偶有编码问题，降级反而更稳 - 不要只依赖
execCommand：它在新版本中可能完全移除，且无法在无用户手势的 context 中工作
写入空字符串或特殊字符时的行为差异
navigator.clipboard.writeText('') 是合法的，会清空剪贴板；但某些系统（如 macOS）会保留上一次复制的富文本格式，导致粘贴时出现意外样式。而 writeText('\n\t ') 这类纯空白字符串也能成功写入，但部分应用（如微信、钉钉）粘贴时可能自动过滤或截断。
- 如果业务要求“复制后粘贴即用”，建议对输入做基础清洗：
text.trim()，避免首尾空格干扰 - 复制含换行符的文本时，Windows 记事本能正常识别
\r\n，但 macOS 的备忘录默认只认\n；统一用\n更稳妥 - emoji 或数学符号（如 ?、∑）一般无问题，但极少数老旧终端可能显示为 ；这不是 API 问题，而是目标应用的字体支持限制
