useClipboard

一个剪贴板操作 Hook，提供剪贴板读取和写入功能，支持现代 Clipboard API 和旧版后备方案。自动处理权限请求和错误处理。

基础用法

📋 文本复制

⚠️ 当前浏览器不支持剪贴板操作

🔒 剪贴板 API 需要在安全上下文（HTTPS）中使用

显示代码

代码复制示例

💻 代码片段复制

Vue 3 组件

<template>
  <div>{{ message }}</div>
</template>

<script setup>
const message = ref('Hello Vue 3!');
</script>

JavaScript 函数

function debounce(func, wait) {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
}

显示代码

API 参考

参数

参数	类型	默认值	说明
options	UseClipboardOptions	{}	配置选项

UseClipboardOptions

属性	类型	默认值	说明
legacy	boolean	true	是否启用旧版后备方案
onCopy	(text: string) => void	-	复制成功回调
onError	(error: Error) => void	-	复制失败回调
onRead	(text: string) => void	-	读取成功回调
onReadError	(error: Error) => void	-	读取失败回调

返回值

useClipboard 返回一个数组，包含以下元素：

const [text, copy, read, isSupported, isSecureContext] = useClipboard(options);

索引	名称	类型	说明
0	text	Ref<string>	剪贴板文本内容
1	copy	(text: string) => Promise<boolean>	复制文本到剪贴板
2	read	() => Promise<string>	读取剪贴板内容
3	isSupported	ComputedRef<boolean>	是否支持剪贴板操作
4	isSecureContext	ComputedRef<boolean>	是否在安全上下文中

类型定义

export interface UseClipboardOptions {
  legacy?: boolean;
  onCopy?: (text: string) => void;
  onError?: (error: Error) => void;
  onRead?: (text: string) => void;
  onReadError?: (error: Error) => void;
}

export type CopyFunction = (text: string) => Promise<boolean>;
export type ReadFunction = () => Promise<string>;

export type UseClipboardReturn = [Ref<string>, CopyFunction, ReadFunction, ComputedRef<boolean>, ComputedRef<boolean>];

使用场景

1. 代码复制 - 复制代码片段到剪贴板
2. 文本分享 - 复制链接、文本等内容
3. 表单操作 - 复制表单数据或结果
4. 内容管理 - 复制文章、评论等内容
5. 开发工具 - 复制配置、命令等

浏览器兼容性

现代 Clipboard API

• Chrome 66+
• Firefox 63+
• Safari 13.1+
• Edge 79+

旧版后备方案

• 使用 document.execCommand('copy')
• 支持更多旧版浏览器
• 需要用户交互触发

安全限制

1. HTTPS 要求 - 现代 Clipboard API 需要在安全上下文中使用
2. 用户权限 - 读取剪贴板需要用户授权
3. 用户交互 - 复制操作需要用户交互触发
4. 跨域限制 - 不能访问其他域的剪贴板内容

注意事项

1. 在 HTTP 环境下可能无法使用现代 Clipboard API
2. 读取剪贴板可能需要用户授权
3. 复制操作必须在用户交互事件中触发
4. 旧版后备方案的兼容性更好但功能有限
5. 建议提供用户反馈，告知操作结果