hooks icon indicating copy to clipboard operation
hooks copied to clipboard

feat:Add `useClipboard` hook with clipboard management and tests

Open Majmunu opened this issue 4 months ago • 1 comments

🤔 这个变动的性质是?

  • [x] 新特性提交(新增 useClipboard
  • [x] 测试用例
  • [ ] 日常 bug 修复
  • [ ] 站点、文档改进
  • [ ] 演示代码改进
  • [ ] TypeScript 定义更新
  • [ ] 包体积优化
  • [ ] 性能优化
  • [ ] 功能增强
  • [ ] 国际化改进
  • [ ] 重构
  • [ ] 代码风格优化
  • [ ] 分支合并
  • [ ] 其他改动(是关于什么的改动?)

💡 需求背景和解决方案

需求背景

  • 需要在 Web 环境中实现结构化数据的复制与粘贴:对用户展示可读的可见文本(displayText),同时在剪贴板中携带真实 JSON 数据。

解决方案:新增 Hook useClipboard

type FlexibleClipboardData<T = any> = T;

interface UseClipboard {
  copy: <T = any>(displayText: string, data: FlexibleClipboardData<T>) => Promise<void>;
  paste: <T = any>() => Promise<FlexibleClipboardData<T> | string | null>;
  isSupported: boolean;
  hasPermission: () => Promise<boolean>;
}

现代浏览器(优先):用 ClipboardItem 同时写两种 MIME:

text/plain → displayText(用户粘贴到输入框只会看到这段文字)

text/html → JSON(程序读取用,普通粘贴一般看不见)

降级方案(不支持 text/html 时):只写 text/plain,把 JSON Base64 编码后贴在末尾并打上标记:

${displayText}\n__CLIPBOARD_DATA__:${btoa(json)}

📝 更新日志

语言 更新描述
🇺🇸 英文 Add useClipboard to copy/paste structured payloads with graceful fallback. Expose isSupported and hasPermission. Provide comprehensive Vitest tests. No breaking changes.
🇨🇳 中文 新增 useClipboard,支持结构化复制/粘贴并在不支持场景优雅降级;提供 isSupportedhasPermission;补充完整 Vitest 测试。无破坏性变更。

☑️ 请求合并前的自查清单

  • [x] 文档已补充或无须补充

  • [x] 代码演示已提供或无须提供

  • [x] TypeScript 定义已补充或无须补充

  • [x] Changelog 已提供或无须提供

Majmunu avatar Aug 25 '25 06:08 Majmunu

CLA assistant check
All committers have signed the CLA.

CLAassistant avatar Aug 25 '25 06:08 CLAassistant