iOS Safari Clipboard API 权限弹窗问题

问题现象

在 iOS Safari 中使用 navigator.clipboard.write() 复制文本时，会弹出系统权限弹窗要求用户确认，而在其他浏览器（Chrome、Firefox、桌面 Safari）中则不会。

原因分析

iOS Safari 对 Clipboard API 有严格的安全限制： clipboard.write() 必须在用户手势（点击）的同步执行上下文中调用 。

错误示例

const handleCopy = async () => {
    const link = await fetchLink();  // ❌ 异步操作后，用户手势上下文丢失
    await navigator.clipboard.write([
        new ClipboardItem({
            'text/plain': new Blob([link], { type: 'text/plain' }),
        }),
    ]);
};

上述代码中，await fetchLink() 执行完成后，已经脱离了用户点击的同步上下文，此时调用 clipboard.write() 会触发权限弹窗。

正确示例

const handleCopy = async () => {
    // ✅ 在用户手势上下文中立即创建 ClipboardItem，传入 Promise
    const clipboardItem = new ClipboardItem({
        'text/plain': fetchLink().then(link => new Blob([link], { type: 'text/plain' })),
    });
    await navigator.clipboard.write([clipboardItem]);
};

ClipboardItem 构造函数支持接收 Promise<Blob> 作为值。在用户手势上下文中立即创建 ClipboardItem 并传入 Promise，浏览器会"预订"这个剪贴板写入操作，等待 Promise resolve 后再写入数据，从而避免权限弹窗。

技术要点

方法	用途	iOS Safari 权限要求
clipboard.writeText()	复制纯文本	较宽松，推荐用于同步文本
clipboard.write()	复制任意类型数据	严格，需在用户手势上下文中

ClipboardItem 支持的值类型

• Blob
• Promise<Blob>
• string（部分浏览器）
• Promise<string>（部分浏览器）

封装建议

type TextInput = string | Promise<string> | (() => string | Promise<string>);

async function copyToClipboard(textInput: TextInput): Promise<boolean> {
    // 统一转换为 Promise
    const textPromise =
        typeof textInput === 'function'
            ? Promise.resolve(textInput())
            : Promise.resolve(textInput);

    if (navigator.clipboard?.write && typeof ClipboardItem !== 'undefined') {
        try {
            // 关键：立即创建 ClipboardItem，传入 Promise
            const clipboardItem = new ClipboardItem({
                'text/plain': textPromise.then(text => new Blob([text], { type: 'text/plain' })),
            });
            await navigator.clipboard.write([clipboardItem]);
            return true;
        } catch {
            // 降级处理
        }
    }

    // 降级到 execCommand 或第三方库
    const text = await textPromise;
    return fallbackCopy(text);
}

调用方式

// 同步文本
copyToClipboard('静态文本');

// 异步获取文本 - 传入 Promise
copyToClipboard(fetchLink());

// 异步获取文本 - 传入函数（推荐）
copyToClipboard(() => fetchLink());

注意事项

1. 图片复制同理 - copyImageFromUrl 也应在用户手势上下文中立即创建 ClipboardItem

2. 降级方案 - 始终提供 execCommand('copy') 或 copy-to-clipboard 库作为降级

3. 错误处理 - Clipboard API 可能因权限、HTTPS 等原因失败，需要完善的错误处理

参考资料

• Clipboard API - MDN
• ClipboardItem - MDN
• Async Clipboard API