---
title: "useCopyToClipboard – Browser Hook 使用方法与示例 (useClipboard 的别名)"
description: "useCopyToClipboard 是 useClipboard 的别名，使用相同的实现，返回已复制的文本、复制函数和 Clipboard API 支持状态。"
canonical: https://reactuse.com/zh-Hans/browser/usecopytoclipboard/
---

# useCopyToClipboard

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

:::info
`useCopyToClipboard` 是 [`useClipboard`](/zh-Hans/browser/useclipboard) 的别名。它使用相同的实现，返回 `[text, copy, isSupported]`；完整的 Clipboard API 和旧版复制降级行为请参阅 `useClipboard`。
:::

`useCopyToClipboard` 通过与 `useClipboard` 相同的实现封装 [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API)，返回已复制的文本、`copy` 函数和 `isSupported` 状态。

### 使用场景

- 当你偏好 `useCopyToClipboard` 命名约定时，添加"复制到剪贴板"功能
- 从使用此命名模式的其他 hook 库迁移
- 通过这个关联的 hook 名称使用 `useClipboard` 的行为

### 注意事项

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

## 用法

```tsx live
function Demo() {
  const [value, setValue] = useState("");
  const [text, copy, isSupported] = useCopyToClipboard();
  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>
  );
};

```

%%API%%