useClipboard

将文本复制到用户的剪贴板

useClipboard 提供了一个简单的接口，用于通过 Clipboard API 读写系统剪贴板。它返回最近复制的文本、copy 函数，以及 Clipboard API 是否可用。Clipboard API 不可用时，复制会降级到 document.execCommand("copy")；copy 和 cut 事件会读取当前文本选区。

使用场景

  • 为代码片段、URL 或分享链接添加”复制到剪贴板”按钮
  • 在表单或编辑器中构建从剪贴板粘贴的功能
  • 在数据表格或仪表板中实现复制功能

注意事项

  • SSR 安全：在服务端渲染期间返回空字符串、复制函数和 false。服务端不会访问 navigator。
  • 浏览器支持：isSupported 只表示 navigator.clipboard 是否可用。没有 Clipboard API 时，复制仍会尝试使用 document.execCommand("copy") 降级。
  • 权限：部分浏览器需要用户授权才能访问 Clipboard API。可配合 usePermission 检查 clipboard-read 和 clipboard-write 的状态。

Usage

Live Editor
function Demo() {
  const [value, setValue] = useState("");
  const [text, copy, isSupported] = useClipboard();
  const permissionRead = usePermission("clipboard-read");
  const permissionWrite = usePermission("clipboard-write");
  return (
    <div>
      <p>
        剪贴板权限: 读取 <b>{permissionRead}</b> | 写入&nbsp;
        <b>{permissionWrite}</b>
      </p>
      <p>
        Clipboard API 支持: <b>{isSupported ? "是" : "否"}</b>
      </p>
      <p>
        当前复制内容: <code>{text || "无"}</code>
      </p>
      <input
        value={value}
        onChange={(event) => {
          setValue(event.currentTarget.value);
        }}
      />
      <button onClick={() => copy(value)}>复制</button>
    </div>
  );
};
Result

API

useClipBoard

Returns

readonly [string, (txt: string) => Promise<void>, boolean]: 返回包含剪贴板文本、复制函数和支持状态的只读元组.

Arguments