1. 背景与需求分析
在 Web 开发中，复制文本到剪贴板是一个常见需求，比如：
- 复制分享链接、邀请码
- 复制代码片段
- 一键复制表单内容
现代浏览器提供了 navigator.clipboard API，但存在兼容性和安全上下文的限制；传统的 document.execCommand('copy') 虽然兼容性更好，但使用方式较为繁琐。本质上，我们需要一个统一的工具函数来屏蔽这些差异。
2. API 介绍与演进
2.1 传统方案：document.execCommand
const textarea = document.createElement('textarea')
textarea.value = content
document.body.appendChild(textarea)
textarea.select()
document.execCommand('copy')
document.body.removeChild(textarea)
优点：兼容性好，支持所有主流浏览器 缺点：需要创建临时 DOM 元素，代码冗长
2.2 现代方案：navigator.clipboard
await navigator.clipboard.writeText(content)
优点：简洁直观，直接操作剪贴板 缺点：需要安全上下文（HTTPS），部分浏览器支持受限
3. 核心实现解析
export interface CopyTextOptions {
/** 是否允许复制空白内容（空字符串或纯空格），默认 false */
allowWhitespace?: boolean
/** 是否使用旧版复制方法（不支持空白内容复制），默认 false */
legacy?: boolean
}
export interface CopyTextReturn {
success: boolean
message: string
}
export async function copyText(content: string, options: CopyTextOptions = {}): Promise<CopyTextReturn> {
try {
const { allowWhitespace = false, legacy = false } = options
if (!allowWhitespace && (!content || content.trim() === '')) {
return { success: false, message: '复制内容不能为空' }
} else if (navigator.clipboard && window.isSecureContext && !legacy) {
await navigator.clipboard.writeText(content)
} else {
const textarea = document.createElement('textarea')
textarea.style.cssText = 'position:fixed; opacity:0; z-index:-9999; left:-9999px; top:-9999px;'
textarea.value = content
document.body.appendChild(textarea)
textarea.select()
textarea.setSelectionRange?.(0, content.length)
const copied = document.execCommand('copy')
document.body.removeChild(textarea)
if (!copied) throw new Error('浏览器限制或无法复制')
}
return { success: true, message: '复制成功' }
} catch (error: unknown) {
const errMsg = error instanceof Error ? error.message : '未知错误'
return { success: false, message: `${errMsg}` }
}
}
关键逻辑说明
参数一：allowWhitespace
控制是否允许复制空白内容。默认 false 会过滤空字符串和纯空格内容，避免用户误操作。
参数二：legacy
强制使用传统 execCommand 方案。某些场景下（如在 iframe 内）可能需要降级处理。
优先级判断
navigator.clipboard 可用？
└─ 是 → 判断 isSecureContext（安全上下文）
└─ 是 → 使用现代 API
└─ 否 → 降级到 execCommand
└─ 否 → 降级到 execCommand
4. 兼容性处理策略
| 方案 | 兼容性 | 安全要求 | 代码复杂度 |
|---|---|---|---|
| navigator.clipboard | 现代浏览器 | 必须 HTTPS | 简洁 |
| execCommand | 所有浏览器 | 无 | 较繁琐 |
// 降级逻辑核心代码
const textarea = document.createElement('textarea')
textarea.style.cssText = 'position:fixed; opacity:0; z-index:-9999; left:-9999px; top:-9999px;'
textarea.value = content
document.body.appendChild(textarea)
textarea.select()
textarea.setSelectionRange?.(0, content.length) // 兼容 iOS Safari
const copied = document.execCommand('copy')
document.body.removeChild(textarea)
iOS Safari 兼容要点：setSelectionRange 在 iOS 设备上需要显式调用才能正确选中文本。
5. 安全上下文要求
navigator.clipboard 要求页面必须处于安全上下文：
- HTTPS 协议
- localhost 开发环境
- Chrome Extension 内部页面
开发环境下通常没问题，但部署到生产环境务必确保使用 HTTPS，否则会自动降级到传统方案。
6. 使用场景与示例
6.1 基础用法
const result = await copyText('hello world')
if (result.success) {
console.log('复制成功')
} else {
console.error(result.message)
}
6.2 允许空白内容
// 复制可能为空的文本时
const result = await copyText(userInput, { allowWhitespace: true })
6.3 强制使用传统方案
// 在特殊场景下强制降级
const result = await copyText(content, { legacy: true })
6.4 集成提示组件
注释掉的 TipModal 部分可根据项目实际使用的 UI 库进行适配：
// Element Plus 示例
import { ElMessage } from 'element-plus'
if (!allowWhitespace && (!content || content.trim() === '')) {
ElMessage.error('复制内容不能为空')
return { success: false, message: '复制内容不能为空' }
}
// 复制成功后
ElMessage.success('复制成功')
7. 核心总结
copyText 函数的核心设计要点：
- 自动降级：优先使用
navigator.clipboard，不支持时自动降级到execCommand - 安全优先：判断
isSecureContext确保在安全环境下使用现代 API - 灵活配置：通过
allowWhitespace和legacy参数适配不同业务场景 - 统一返回：返回
{ success, message }结构化结果，便于调用方处理
这个不到 50 行的工具函数覆盖了浏览器复制场景的绝大多数需求，可直接集成到项目中。
