hooks
hooks copied to clipboard
feat:Add `useClipboard` hook with clipboard management and tests
🤔 这个变动的性质是?
- [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,支持结构化复制/粘贴并在不支持场景优雅降级;提供 isSupported 与 hasPermission;补充完整 Vitest 测试。无破坏性变更。 |
☑️ 请求合并前的自查清单
-
[x] 文档已补充或无须补充
-
[x] 代码演示已提供或无须提供
-
[x] TypeScript 定义已补充或无须补充
-
[x] Changelog 已提供或无须提供