useClipboard

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

useClipboard 提供了一个简单的接口，用于通过 Clipboard API 读写系统剪贴板。它返回一个包含最近复制文本和 copy 函数的元组。该 hook 内部处理权限检查，适用于支持 Clipboard API 的所有现代浏览器。

使用场景

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

注意事项

  • SSR 安全：在服务端渲染期间返回空字符串和空操作函数。服务端不会访问 navigator。
  • 浏览器支持：需要 Clipboard API（所有现代浏览器均支持）。在旧版浏览器中会优雅降级。
  • 权限：部分浏览器需要用户授权才能访问剪贴板。可配合 usePermission 检查 clipboard-read 和 clipboard-write 的状态。

Usage

Live Editor

function Demo() {
  const [value, setValue] = useState("");
  const [text, copy] = useClipboard();
  const permissionRead = usePermission("clipboard-read");
  const permissionWrite = usePermission("clipboard-write");
  return (
    <div>
      <p>
        剪贴板权限: 读取 <b>{permissionRead}</b> | 写入&nbsp;
        <b>{permissionWrite}</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>]: 返回只读元组.

Arguments