Clipboard API：在 React 中复制和粘贴

navigator.clipboard.writeText(text) 会将字符串写入系统剪贴板，并返回一个 Promise。它是旧版 execCommand 方案的现代替代方法。请始终等待这个 Promise，并处理可能的拒绝情况，例如用户拒绝剪贴板访问时。

navigator.clipboard.readText() 会将当前剪贴板内容读取为字符串，并同样返回一个 Promise。读取需要 clipboard-read 权限，浏览器会提示用户授予该权限。在实际的 React 应用中，读取剪贴板的使用频率通常低于写入剪贴板。

浏览器强制要求只能在用户手势处理程序中调用 clipboard.writeText，例如点击或按键事件处理程序。在 useEffect 中调用，或在手势发生后异步调用，都会抛出安全错误。请始终直接从 onClick 处理程序触发写入。

标准模式如下：用户点击复制按钮，您的处理程序调用 navigator.clipboard.writeText(value)，成功后将 copied 状态设置为 true，按钮暂时显示对勾或“已复制！”标签。经过短暂延迟后，按钮会恢复正常状态。

请将这段逻辑封装在 useCopyToClipboard 钩子中，使其返回一个元组：[copied, copyFn]。copied 布尔值负责驱动界面反馈，copyFn 接受要复制的文本。该钩子会在内部处理异步写入和任何错误，从而让组件保持简洁。

在钩子内部，复制成功后设置 setCopied(true)，并通过 setTimeout(() => setCopied(false), 2000) 安排重置。请保存超时 ID，并在 useEffect 的清理函数中清除它，以防组件卸载后仍更新状态。这样可以避免出现“无法更新已卸载组件上的状态”警告。

较旧的浏览器和非 HTTPS 页面不支持剪贴板接口。旧版备用方案会创建一个临时的 textarea，设置其值，将它附加到文档主体，调用 document.execCommand('copy')，然后移除该元素。这种方法是同步的，几乎在所有环境中都能运行，但已经被弃用。

使用剪贴板接口之前，请检查：navigator.clipboard && typeof navigator.clipboard.writeText === 'function'。如果不可用，请改用旧版的 execCommand 方案。这项防御性检查可以避免在不支持该接口的环境中出现运行时错误。

读取剪贴板需要通过权限接口获得用户许可。您可以查询当前状态：navigator.permissions.query({ name: 'clipboard-read' }) 会返回一个 PermissionStatus，其 state 为 granted、denied 或 prompt。调用 readText() 时，浏览器会自动提示用户。

剪贴板接口仅在安全上下文（HTTPS 或 localhost）中可用。在 HTTP 页面上，navigator.clipboard 是 undefined。这是出于安全限制，因为剪贴板内容可能包含敏感信息。请始终先检查接口是否可用，再引用其方法，以避免出现空引用错误。

jsdom（由 Jest 使用）未实现剪贴板接口。请在测试设置中对其进行模拟：Object.assign(navigator, { clipboard: { writeText: jest.fn().mockResolvedValue(undefined) } })。这样，您无需真实的浏览器环境，就可以测试组件是否使用正确的参数调用 writeText。

在浏览器中，何时可以安全地调用 navigator.clipboard.writeText()？

在点击处理函数中使用 navigator.clipboard.writeText() 来复制文本。构建一个返回 [copied, copyFn] 并带有定时重置功能的 useCopyToClipboard 钩子。始终检查接口是否可用，为较旧的浏览器提供 execCommand 回退方案，并在 Jest 测试中模拟 navigator.clipboard。