前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载导读本文深入剖析 VueUse 3.x 中基于 Clipboard API 的响应式工具函数useClipboardItems。与只能复制纯文本的useClipboard不同useClipboardItems以 Web 平台标准的 ClipboardItem 对象为核心可以一次携带多种 MIME 类型文本、图片、HTML 等的数据写入系统剪贴板并支持监听 copy/cut 事件、异步读取剪贴板内容。读完本文你将掌握该函数的完整配置项、返回的响应式状态、权限约束机制以及它和useClipboard在实现层面的差异与选型依据。一、函数定位响应式封装下的 Clipboard APIuseClipboardItems属于 VueUse 的 Browser 类别参见 packages/core/useClipboardItems/index.ts 与官方文档 index.md它的职责是对浏览器的 Clipboard API 做响应式封装使开发者可以在 Vue 组件中响应剪贴板命令cut、copy、paste异步从系统剪贴板读取数据异步向系统剪贴板写入数据。它的底层能力完全来自浏览器原生接口因此一个关键前提是访问剪贴板内容受 Permissions API 门控。没有用户授权浏览器不允许读取或修改剪贴板内容这一点在官方文档中有明确说明也是所有基于 Clipboard API 的工具函数共同的安全边界。从源码结构来看packages/core/useClipboardItems/index.ts该函数通过useSupported(() (navigator clipboard in navigator))检测当前环境是否支持 Clipboard API将其结果包装成响应式的isSupported随后用shallowRef维护content剪贴板数据与copied复制成功标记并通过useTimeoutFn来自vueuse/shared实现copied的自动复位。二、与 useClipboard 的本质区别文本专用 vs 多类型数据官方文档在 Difference fromuseClipboard 一节中给出了二者的定位差异useClipboard是text-only函数内部只处理text/plain字符串useClipboardItems是ClipboardItem 驱动的函数可以复制任何被ClipboardItem支持的内容。对比两者的源码可以看得更清楚useClipboard/index.ts 内部用createClipboardItem把字符串包装成new ClipboardItem({ text/plain: value })只能产出文本类型的 ClipboardItem并额外提供了legacy选项在 Clipboard API 不可用时回退到document.execCommand(copy)。useClipboardItems/index.ts 直接把开发者构造好的ClipboardItems即ClipboardItem[]交给navigator.clipboard.write(value)不做任何 MIME 层面的假设因此天然支持图片、HTML、RTF 等多类型数据。简而言之useClipboard为你包办文本场景并保留旧浏览器兜底useClipboardItems把灵活性完全交给你用标准的ClipboardItem表达任意剪贴板载荷。三、快速上手完整可运行的示例官方文档给出的是一个开箱即用的 Vue 单文件组件示例。这里保留其完整结构并补充类型说明script setup langts import { useClipboardItems } from vueuse/core const mime text/plain const source ref([ new ClipboardItem({ [mime]: new Blob([plain text], { type: mime }), }) ]) const { content, copy, copied, isSupported } useClipboardItems({ source }) /script template div v-ifisSupported button clickcopy(source) !-- by default, copied will be reset in 1.5s -- span v-if!copiedCopy/span span v-elseCopied!/span /button p Current copied: code{{ content || none }}/code /p /div p v-else Your browser does not support Clipboard API /p /template示例中的关键点source是一个ref包裹的ClipboardItem[]每个ClipboardItem由{ [mime]: Blob }形式构造即一个 MIME 类型对应一个 Blob 数据块copy(source)接受参数执行复制此时copied会短暂变为true并在默认1.5s后自动复位可配置content保存最近一次读到的剪贴板内容未读取时为空数组isSupported用于决定是否渲染复制 UI避免在不支持 Clipboard API 的浏览器上报错。四、Options 参数详解依据类型声明packages/core/useClipboardItems/index.tsuseClipboardItems接受如下配置Option类型默认值说明readbooleanfalse是否启用剪贴板读取开启后在 copy/cut 事件触发时自动刷新contentsourceMaybeRefOrGetterClipboardItems—copy()无参数调用时使用的默认复制源copiedDuringnumber1500copied状态保持为true的毫秒数超时后自动复位为falsenavigatorNavigatordefaultNavigator自定义navigator实例继承自ConfigurableNavigator见 packages/core/_configurable.ts可用于 iframe 或测试环境注入其中source的类型为MaybeRefOrGetterClipboardItems即它既可以是一个普通数组、一个ref/computed也可以是一个返回数组的 getter 函数。copy()内部通过toValue(source)取值useClipboardItems/index.ts因此可以响应式地获取最新数据源。五、返回值详解useClipboardItems的返回值结构useClipboardItems/index.ts如下属性类型说明isSupportedComputedRefboolean当前环境是否支持 Clipboard API继承自Supportable见 packages/core/types.tscontentReadonlyRefClipboardItems当前剪贴板内容ClipboardItem[]写入或读取后更新copiedReadonlyShallowRefboolean复制成功后为truecopiedDuring毫秒后自动复位copy(content?: ClipboardItems) Promisevoid将ClipboardItems写入剪贴板未传参时使用sourceread() void手动触发一次剪贴板读取更新content值得注意的两点实现细节当传入了source即调用useClipboardItems({ source })时重载类型将copy的参数标记为可选的(content?: ClipboardItems) Promisevoid未传source时copy要求显式传入ClipboardItems。这一设计体现在函数的重载声明上useClipboardItems/index.ts。content与copied均通过shallowReadonly暴露外部只能读取不能直接改写保证状态变更统一经过copy/read内部逻辑。六、读取剪贴板手动 read 与自动监听源码中读取逻辑的核心是updateContentuseClipboardItems/index.tsfunction updateContent() { if (isSupported.value) { navigator!.clipboard.read().then((items) { content.value items }) } }它直接调用navigator.clipboard.read()把读到的ClipboardItem[]存入content。读取有两种触发方式手动触发调用返回的read()函数自动监听当read: true时函数内部通过useEventListener([copy, cut], updateContent, { passive: true })监听 copy/cut 事件事件发生时自动刷新content。由于navigator.clipboard.read()返回的是ClipboardItem[]你无法直接从模板中把内容当字符串渲染。VueUse 官方演示packages/core/useClipboardItems/demo.vue给出了标准处理范式遍历content中的每个ClipboardItem调用item.getType(text/plain)取出 Blob再通过blob.text()还原成字符串effect(() { Promise.all(content.value.map(item item.getType(text/plain))) .then(async (blobs) { computedMimeType.value blobs.map(blob blob.type).join(, ) computedText.value (await Promise.all(blobs.map(blob blob.text()))).join(, ) }) })七、权限模型Permissions API 是关键前置官方文档强调读取或改写剪贴板内容必须获得用户授权这是浏览器安全模型的一部分。VueUse 的演示组件用usePermission直观地展示了这一约束demo.vueconst permissionRead usePermission(clipboard-read) const permissionWrite usePermission(clipboard-write)clipboard-write权限通常在用户触发的手势如点击按钮中会被自动授予这也是为什么复制操作必须由copy()这种用户事件回调发起clipboard-read权限需要浏览器弹出授权提示用户拒绝后将无法读取剪贴板此时content不会更新。对比 useClipboard/index.ts 中的实现可见useClipboard会用isAllowed()status granted || status prompt主动检查权限状态并决定是否回退到 legacy 模式而useClipboardItems不做这种兜底直接依赖 Clipboard API因此它对浏览器支持度的要求更高。八、能力支持检测useSupported 的响应式封装useClipboardItems通过useSupported见 packages/core/useSupported/index.ts将能力检测变成响应式值const isSupported useSupported(() (navigator clipboard in navigator))useSupported内部与useMounted联动返回ComputedRefboolean在组件挂载后会重新求值从而在服务端渲染SSR环境中安全地返回false避免在无navigator的运行时抛错。这就是模板中v-ifisSupported分支能够可靠工作、并在不支持的环境中优雅降级显示 Your browser does not support Clipboard API的原因。九、实战复制图片等非文本数据useClipboardItems的核心价值在于突破纯文本限制。只要目标 MIME 类型被ClipboardItem支持就可以一次性携带多个数据表示const item new ClipboardItem({ text/plain: new Blob([hello], { type: text/plain }), text/html: new Blob([bhello/b], { type: text/html }), image/png: imageBlob, // 例如从 canvas.toBlob() 或 fetch 得到 }) const { copy } useClipboardItems() await copy([item])在组件内通过按钮触发配合copied状态即可给出用户反馈。需要注意的是复制操作应在用户手势click的调用栈内同步发起否则浏览器可能因缺少用户激活而拒绝写入。十、选型建议何时用 useClipboard何时用 useClipboardItems结合二者源码与文档可以给出清晰的选型依据只需要复制/读取纯文本优先使用 useClipboard。它类型更简单MaybeRefOrGetterstring、自带legacy回退兼容性更好还有copyPending等额外状态适合绝大多数业务场景。需要复制图片、HTML、RTF 等多类型数据选择useClipboardItems。它不预设 MIME 类型把构造ClipboardItem的自由交给开发者是浏览器原生剪贴板能力的完整透传。对旧浏览器有强兼容需求useClipboardItems没有 legacy 兜底应搭配能力检测isSupported做降级 UI或改用useClipboard({ legacy: true })。十一、类型重载与导出useClipboardItems的类型设计采用重载useClipboardItems/index.tsexport function useClipboardItems(options?: UseClipboardItemsOptionsundefined): UseClipboardItemsReturnfalse export function useClipboardItems(options: UseClipboardItemsOptionsMaybeRefOrGetterClipboardItems): UseClipboardItemsReturntrue不传sourceOptional泛型为falsecopy必须显式传参传入sourceOptional为truecopy参数变为可选。该函数通过 packages/core/index.ts 的export * from ./useClipboardItems从vueuse/core统一导出与useClipboard等函数并列开发者只需import { useClipboardItems } from vueuse/core即可使用。结语useClipboardItems是 VueUse 在浏览器剪贴板领域对原生 Clipboard API 的响应式透传它以ClipboardItem为数据载体覆盖任意 MIME 类型的复制与读取同时通过useSupported、useEventListener、useTimeoutFn提供能力检测、事件监听与状态自动复位。与纯文本的useClipboard互为补充构成了 VueUse 剪贴板工具的完整矩阵。掌握二者的差异与权限约束即可在真实业务中安全、高效地实现多类型剪贴板交互。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐VueUse useClipboardItems 实战指南基于 ClipboardItem 的响应式剪贴板操作VueUse useClipboardItems 实战指南基于 ClipboardItem 的响应式剪贴板操作 在 Vue 3 应用中直接操作系统剪贴板往往要前端VueUse useClipboard 完全指南在 Vue 3 中响应式读写系统剪贴板VueUse useClipboard 完全指南在 Vue 3 中响应式读写系统剪贴板 导读 useClipboard 是 VueUse 对浏览器 Clipb前端Warp TUI 剪贴板复制修复基于 arboard 原生剪贴板与 OSC 52 双通道传输的实现解析Warp TUI 剪贴板复制修复基于 arboard 原生剪贴板与 OSC 52 双通道传输的实现解析 导读 Warp 的无头 TUIheadless te桌面应用开发者工具人工智能AI 应用AI Agent代码智能体上一篇老 Mac 如何装最新 macOSOpenCore Legacy Patcher 从零到能用完整实操下一篇如何快速上手BERT-large-cased问答模型从安装到部署的10个步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考