# @custom-react-hooks/use-clipboard 中文文档

规范地址：https://npmcn.com/package/%40custom-react-hooks/use-clipboard/

版本：1\.6\.0
npm 元数据更新时间：2025-09-13T16:55:13.433Z
中文译文更新时间：2026-11-11T09:13:30.266Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40custom-react-hooks/use-clipboard
原文对照：https://npmcn.com/package/%40custom-react-hooks/use-clipboard/?lang=original
项目主页：https://custom-react-hooks-live.vercel.app/
源码仓库：https://github.com/djkepa/custom-react-hooks

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：23.1 kB，8 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=16
- 首次发布：2023-12-01T23:42:00.889Z
- 最新版本发布：2025-09-13T16:55:13.231Z
- 近 30 天下载量：2515（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

`useClipboard` 是反应钩子,为剪贴板操作提供全面的接口。 它提供诸如自动剪贴板内容读取、更改检测和投票能力等先进功能,使之适合建造精密的

## 安装

```sh
npm install @custom-react-hooks/use-clipboard
```

也可以使用：`pnpm add @custom-react-hooks/use-clipboard`、`yarn add @custom-react-hooks/use-clipboard`、`bun add @custom-react-hooks/use-clipboard`

## README

# `useClipboard` 钩子

`useClipboard` 是反应钩子,为剪贴板操作提供全面的接口。 它提供诸如自动剪贴板内容读取、更改检测和投票能力等高级功能,使它能完美地构建复杂的剪贴板-意识应用程序.

## 特征

-   **复制并粘贴**: 提供将文本复制到剪贴板并粘贴文本的方法.
-   **剪贴板内容读取**: 自动读取并跟踪有实时更新的剪贴板内容.
-   **内容更改检测**: 检测剪贴板内容更改时并提供回调.
-   **投票支助**: 可选投票以持续监控剪贴板的更改.
-   **智能州管理**: 跟踪剪贴板内容、装入状态和操作状态.
-   **同步 API**:使用基于承诺的Clipboard API方法进行非屏蔽操作.
-   **现状和错误报告**: 返回剪贴板操作和任何错误消息的状态.
-   **服务器- Side 渲染兼容性**:检查Clippboard API的可用性,确保钩子不会在服务器侧渲染上下文中断开.
-   **内存效率**: 自动清理间隔并妥善管理资源.

## 安装

选择并安装适合您项目需要的单个钩子, 或安装整个收藏, 用于全套公用事业 .

### 只安装当前钩

```bash
npm install @custom-react-hooks/use-clipboard
```

或者说

```bash
yarn add @custom-react-hooks/use-clipboard
```

### 安装全部钩

```sh
npm install @custom-react-hooks/all
```

或者说

```sh
yarn add @custom-react-hooks/all
```

## 导入虎克

这个 `useClipboard` 钩必须使用下列命名的导入方式导入:

**已命名的导入 :**

```javascript
import { useClipboard } from '@custom-react-hooks/use-clipboard';
```

这种方法确保了钩子无缝地融入到您的项目中,在您如何使用我们的包时保持一致性和可预测性.

## 使用量

### 基本用途

```typescript
import React, { useState } from 'react';
import { useClipboard } from '@custom-react-hooks/use-clipboard';

const BasicClipboardComponent = () => {
  const { 
    copyToClipboard, 
    pasteFromClipboard, 
    state, 
    clipboardContent, 
    hasContent,
    isReading 
  } = useClipboard();
  
  const [textToCopy, setTextToCopy] = useState('');

  const handleCopy = async () => {
    await copyToClipboard(textToCopy);
  };

  const handlePaste = async () => {
    const text = await pasteFromClipboard();
    console.log('Pasted:', text);
  };

  return (
    <div>
      <div>
        <input
          type="text"
          value={textToCopy}
          onChange={(e) => setTextToCopy(e.target.value)}
          placeholder="Text to copy"
        />
        <button onClick={handleCopy} disabled={!textToCopy.trim()}>
          Copy to Clipboard
        </button>
      </div>

      <div>
        <button 
          onClick={handlePaste} 
          disabled={!hasContent || isReading}
        >
          {isReading ? 'Reading...' : `Paste${hasContent ? ` (${clipboardContent.substring(0, 20)}...)` : ' (Empty)'}`}
        </button>
      </div>

      <div>
        <p>Clipboard Content: {clipboardContent || 'Empty'}</p>
        <p>Has Content: {hasContent ? 'Yes' : 'No'}</p>
      </div>

      {state.success && <p style={{ color: 'green' }}>Operation successful!</p>}
      {state.error && <p style={{ color: 'red' }}>Error: {state.error}</p>}
    </div>
  );
};

export default BasicClipboardComponent;
```

### 带有选项的高级使用

```typescript
import React, { useState } from 'react';
import { useClipboard } from '@custom-react-hooks/use-clipboard';

const AdvancedClipboardComponent = () => {
  const [changeLog, setChangeLog] = useState<string[]>([]);

  const { 
    copyToClipboard, 
    clipboardContent, 
    hasContent,
    refreshClipboard,
    clearClipboard,
    state 
  } = useClipboard({
    readOnMount: true,
    pollingInterval: 2000, // Poll every 2 seconds
    onClipboardChange: (content) => {
      setChangeLog(prev => [...prev, `Changed to: "${content}" at ${new Date().toLocaleTimeString()}`]);
    }
  });

  return (
    <div>
      <h3>Advanced Clipboard Monitor</h3>
      
      <div>
        <p>Current Clipboard: {clipboardContent || 'Empty'}</p>
        <p>Has Content: {hasContent ? 'Yes' : 'No'}</p>
      </div>

      <div>
        <button onClick={() => copyToClipboard('Hello World!')}>
          Copy "Hello World!"
        </button>
        <button onClick={() => copyToClipboard(new Date().toISOString())}>
          Copy Current Time
        </button>
        <button onClick={refreshClipboard}>
          Refresh Clipboard
        </button>
        <button onClick={clearClipboard} disabled={!hasContent}>
          Clear Clipboard
        </button>
      </div>

      <div>
        <h4>Change Log:</h4>
        <ul style={{ maxHeight: '200px', overflow: 'auto' }}>
          {changeLog.map((log, index) => (
            <li key={index}>{log}</li>
          ))}
        </ul>
      </div>

      {state.error && <p style={{ color: 'red' }}>Error: {state.error}</p>}
    </div>
  );
};

export default AdvancedClipboardComponent;
```

### 智能按钮示例( 处理 GitHub 注释)

```typescript
import React from 'react';
import { useClipboard } from '@custom-react-hooks/use-clipboard';

const SmartPasteButton = () => {
  const { pasteFromClipboard, clipboardContent, hasContent, isReading } = useClipboard();

  const handlePaste = async () => {
    if (hasContent) {
      const content = await pasteFromClipboard();
      // Do something with the pasted content
      console.log('Pasted:', content);
    }
  };

  return (
    <button 
      onClick={handlePaste}
      disabled={!hasContent || isReading}
      style={{
        opacity: hasContent ? 1 : 0.5,
        cursor: hasContent ? 'pointer' : 'not-allowed'
      }}
    >
      {isReading 
        ? 'Reading clipboard...' 
        : hasContent 
          ? `Paste "${clipboardContent.substring(0, 15)}${clipboardContent.length > 15 ? '...' : ''}"`
          : 'Clipboard is empty'
      }
    </button>
  );
};

export default SmartPasteButton;
```

## API 参考

### 参数

这个 `useClipboard` 钩子接受可选配置对象 :

```typescript
interface UseClipboardOptions {
  /**
   * Whether to automatically read clipboard content on mount
   * @default true
   */
  readOnMount?: boolean;
  
  /**
   * Polling interval in milliseconds to check for clipboard changes
   * Set to 0 to disable polling
   * @default 0
   */
  pollingInterval?: number;
  
  /**
   * Callback fired when clipboard content changes
   */
  onClipboardChange?: (content: string) => void;
}
```

### 回返

钩子返回具有以下属性和方法的对象:

```typescript
{
  // Methods
  copyToClipboard: (text: string) => Promise<void>;
  pasteFromClipboard: () => Promise<string>;
  refreshClipboard: () => Promise<string>;
  clearClipboard: () => Promise<void>;
  
  // State
  state: {
    success: boolean;
    error: string | null;
  };
  clipboardContent: string;
  hasContent: boolean;
  isReading: boolean;
}
```

#### 方法

-   **`copyToClipboard(text: string)`**: 将所提供的文本复制到剪贴板并更新本地状态.
-   **`pasteFromClipboard()`**: 从剪贴板读取并返回文本, 更新本地状态 .
-   **`refreshClipboard()`**: 手动刷新剪贴板内容而不执行粘贴操作.
-   **`clearClipboard()`**:通过复制空格字符来清除剪贴板.

#### 状态属性

-   **`state.success`**:布尔表示上次操作是否成功.
-   **`state.error`**: 如果操作失败, 含有错误消息的字符串, 或 `null` 如果没有错误.
-   **`clipboardContent`**: 剪贴板作为字符串的当前内容.
-   **`hasContent`**:布尔表示剪贴板是否包含非空内容.
-   **`isReading`**: boolean 表示当前钩是否正在从剪贴板读取.

## 使用大小写

-   **智能粘贴按钮**:按照 GitHub 注释中的建议,根据剪贴板内容创建启用/失效的按钮.
-   **剪贴板监视**: 监视安全应用程序或生产力工具的剪贴板修改.
-   **复制到剪贴板**: 将文本复制到剪贴板上, 如 URL, 代码, 或用户生成的内容 .
-   **从剪贴板粘贴**:从剪贴板获取和使用数据,在窗体字段或数据导入中有用.
-   **编辑器中的剪贴板集成**: 在文本编辑器或记事应用程序中用于增强剪贴板互动.
-   **共享内容**: 使用户能够轻松地将共享内容或链接复制到剪贴板上.
-   **数据导出/导入**:简化应用程序内进出口业务的复制和粘贴数据.
-   **剪贴板历史**:通过跟踪剪贴板随时间推移的变化来构建剪贴板历史特性.
-   **内容验证**: 在允许粘贴操作前验证剪贴板内容 .
-   **跨标签同步**: 将剪贴板内容同步到多个浏览器标签或窗口.

## 业绩考量

-   **投票影响**: 少用会影响表现的民调. 考虑对大多数使用的案例使用较长的间隔(2-5秒).
-   **权限处理**: 钩子优雅地处理剪贴板权限拒绝而不丢出错误 .
-   **内存管理**:自动清理间隔和事件收听器防止内存出漏.
-   **调试**:考虑在高频假想中解开剪贴板操作.

## 捐款

我们鼓励捐款加强 `useClipboard`。对于错误,特性请求,或拖取请求,请通过项目寄存器联系.

## 常见问题

### @custom-react-hooks/use-clipboard 是什么？

useClipboard 是反应钩子,为剪贴板操作提供全面的接口。 它提供诸如自动剪贴板内容读取、更改检测和投票能力等先进功能,使之适合建造精密的

### 如何安装 @custom-react-hooks/use-clipboard？

在项目目录运行 npm install @custom-react-hooks/use-clipboard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @custom-react-hooks/use-clipboard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @custom-react-hooks/use-clipboard 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @custom-react-hooks/use-clipboard 可以商用吗？

@custom-react-hooks/use-clipboard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @custom-react-hooks/use-clipboard 的下载量有多少？

根据 npm 官方下载统计，@custom-react-hooks/use-clipboard 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,515 次，日均约 84 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @custom-react-hooks/use-clipboard 还在维护吗？

最新版本 1\.6\.0 发布于 2025/09/14（1\.2 年前）；至今共发布 10 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/12/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。