前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载在 Vue 3 应用中直接操作系统剪贴板往往要面对异步 API、权限门控和内容格式转换等繁琐细节。VueUse 提供的useClipboardItems正是面向浏览器原生 Clipboard API 的响应式封装它允许你基于ClipboardItem读写任意格式的剪贴板内容并自动维护content、copied等响应式状态让复制、读取、状态回显的整套流程开箱即用。读完本文你将掌握useClipboardItems的完整 API、与useClipboard的选型差异以及它背后的源码实现原理可以直接在项目中落地一个支持多种 MIME 类型的复制/粘贴组件。什么是 useClipboardItemsuseClipboardItems是 VueUse 核心包packages/core中面向浏览器 Clipboard API 的响应式工具函数位于 packages/core/useClipboardItems/index.ts并从packages/core/index.ts统一对外导出。它的核心能力可以概括为三点响应式读取与写入把navigator.clipboard.read()与navigator.clipboard.write()封装成可复用的响应式状态基于ClipboardItem的多格式支持可以复制图片、富文本、HTML、文本等任何浏览器ClipboardItem支持的内容权限友好剪贴板内容的读写受 Permissions API 门控没有用户授权时不允许读取或修改剪贴板内容。与 useClipboard 的区别文本专用 vs 格式通用VueUse 同时提供了两个剪贴板工具函数useClipboard 与useClipboardItems。二者的选型差异非常清晰useClipboard是纯文本函数它只处理字符串内部会构造{ text/plain: value }的ClipboardItem进行写入见 packages/core/useClipboard/index.ts并额外支持legacy选项在剪贴板 API 不可用时回退到document.execCommand(copy)useClipboardItems是ClipboardItem导向的函数它直接接收并写入ClipboardItem实例因此可以复制任何ClipboardItem支持的内容包括图片、HTML、自定义 MIME 类型等。简而言之只需要复制/粘贴文本时用useClipboard需要处理多格式内容时用useClipboardItems。快速上手一个完整的复制按钮原文档给出了一份完整的 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) !-- 默认情况下copied 会在 1.5 秒后自动重置 -- 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要点说明通过new ClipboardItem({ [mime]: new Blob([...], { type: mime }) })构造剪贴板条目mime声明内容的媒体类型isSupported用于能力检测在不支持 Clipboard API 的浏览器中渲染降级提示传入source选项后copy()可以不传参数直接使用该 source 进行复制copied是一个临时状态默认 1.5 秒后自动恢复为false很适合驱动按钮文案切换。API 详解useClipboardItems的完整类型定义在 packages/core/useClipboardItems/index.ts下面逐项拆解。选项UseClipboardItemsOptionsexport interface UseClipboardItemsOptionsSource extends ConfigurableNavigator { /** * 是否启用剪贴板读取 * * default false */ read?: boolean /** * 复制数据源 */ source?: Source /** * 重置 copied ref 状态所需的毫秒数 * * default 1500 */ copiedDuring?: number }选项类型默认值作用readbooleanfalse是否启用剪贴板读取。启用后会在用户执行copy/cut时自动更新contentsourceSource一般为ClipboardItems无复制数据源。传入后copy()可以不传参数内部通过toValue(source)解析navigatorNavigatorwindow.navigator自定义navigator实例来自ConfigurableNavigator可用于 iframe 或测试环境注入返回值UseClipboardItemsReturnexport interface UseClipboardItemsReturnOptional extends Supportable { content: ReadonlyRefClipboardItems copied: ReadonlyShallowRefboolean copy: Optional extends true ? (content?: ClipboardItems) Promisevoid : (text: ClipboardItems) Promisevoid read: () void }返回值类型说明isSupportedComputedRefboolean当前环境是否支持 Clipboard API继承自SupportablecontentReadonlyRefClipboardItems当前剪贴板内容ClipboardItem[]只读copiedReadonlyShallowRefboolean复制成功标记copiedDuring毫秒后自动重置copy(content?: ClipboardItems) Promisevoid执行复制是否可省略参数取决于是否传入sourceread() void手动触发一次剪贴板读取更新content重载签名与Optional泛型源码通过两个重载区分是否配置了 sourceexport function useClipboardItems(options?: UseClipboardItemsOptionsundefined): UseClipboardItemsReturnfalse export function useClipboardItems(options: UseClipboardItemsOptionsMaybeRefOrGetterClipboardItems): UseClipboardItemsReturntrue不传source时copy必须显式传入ClipboardItemsOptional false传入source可以是值、ref或 getter即MaybeRefOrGetterClipboardItems时copy可以省略参数Optional true内部自动解析 source。源码级原理解析useClipboardItems的实现非常精简packages/core/useClipboardItems/index.ts却完整覆盖了能力检测、写入、读取、状态复位四条链路下面逐一展开。1. 能力检测isSupportedconst isSupported useSupported(() (navigator clipboard in navigator))useSupported是 VueUse 通用的能力检测工具packages/core/useSupported/index.ts它基于useMounted的挂载状态构造一个computed仅在组件挂载后计算Boolean(callback())。这意味着isSupported在 SSR 环境下为false——因为defaultNavigator isClient ? window.navigator : undefined见 packages/core/_configurable.ts服务端没有navigator。这也是模板中用v-ifisSupported做降级渲染的原因。2. 写入链路copyasync function copy(value toValue(source)) { if (isSupported.value value ! null) { await navigator!.clipboard.write(value) content.value value copied.value true timeout.start() } }value默认取toValue(source)因此source可以是普通数组、ref或 getter写入时统一解包通过navigator.clipboard.write(value)异步写入参数是ClipboardItem[]写入成功后同步更新content与copied并启动复位计时器。3. copied 自动复位useTimeoutFnconst timeout useTimeoutFn(() copied.value false, copiedDuring, { immediate: false })useTimeoutFnpackages/shared/useTimeoutFn/index.ts是对setTimeout的控制封装{ immediate: false }表示创建时并不启动计时而是由copy()在成功后调用timeout.start()。于是copied默认保持 1.5 秒后自动归零无需手动清理。4. 读取链路updateContent 与事件监听function updateContent() { if (isSupported.value) { navigator!.clipboard.read().then((items) { content.value items }) } } if (isSupported.value read) { useEventListener([copy, cut], updateContent, { passive: true }) }read()返回值就是updateContent调用它会触发一次navigator.clipboard.read()把读到的ClipboardItem[]写入content当选项read: true时函数还会通过useEventListener监听copy与cut事件passive: true用户在系统层面执行复制/剪切操作后自动刷新content注意读取同样受权限门控未授权时clipboard.read()会失败。5. 状态实现shallowRef 与 shallowReadonlyconst content shallowRefClipboardItems([]) const copied shallowRef(false) // ... return { isSupported, content: shallowReadonly(content), copied: shallowReadonly(copied), copy, read: updateContent, }content与copied均采用shallowRef存储对外通过shallowReadonly暴露只读视图防止调用方直接篡改内部状态保证状态流转始终经由copy/read两个入口。读取剪贴板内容结合 usePermission 与 getType仓库自带的演示组件 packages/core/useClipboardItems/demo.vue 展示了读取方向的完整实践核心思路是用usePermission观察剪贴板读写权限再对content中的每个ClipboardItem调用getType(text/plain)提取 Blob 文本import { useClipboardItems, usePermission } from vueuse/core import { effect, shallowRef } from vue const { content, isSupported, copy, read } useClipboardItems() const permissionRead usePermission(clipboard-read) const permissionWrite usePermission(clipboard-write) 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(, ) }) })在模板中它同时渲染出clipboard-read与clipboard-write两个权限状态prompt/granted/denied并提供Copy与Manual read两个按钮分别触发copy([...])和read()button click() copy([createClipboardItems(input)])Copy/button button click() read()Manual read/button这套组合是读取方向的标准范式usePermission(clipboard-read)负责权限提示与状态展示read()负责拉取内容item.getType(mime)负责按 MIME 提取对应数据。注意事项权限门控剪贴板内容访问受 Permissions API 约束读取或修改前需要用户授权浏览器的权限提示授权状态可用usePermissionpackages/core/usePermission观察SSR 安全由于defaultNavigator仅在客户端存在isClient ? window.navigator : undefined服务端渲染时isSupported恒为false务必用v-ifisSupported或客户端挂载后执行相关逻辑降级分支模板中的v-else分支用于不支持 Clipboard API 的浏览器此时应提供替代方案如需文本复制可考虑useClipboard的legacy回退读取需要read: true默认不监听剪贴板事件如需在用户复制/剪切后自动同步content需显式开启read: true选项content是ClipboardItem[]直接渲染到页面通常需要像 demo 那样通过getType()提取并解析为文本或图片 URL 后再展示。小结useClipboardItems以极小的实现成本核心仅约 40 行逻辑把浏览器 Clipboard API 的读写、权限、事件监听与响应式状态管理整合为一个声明式接口sourcecopy()解决写入readcontent解决读取copiedDuring自动管理复制反馈isSupported兜底能力降级。对于需要复制图片、富文本或自定义 MIME 内容的 Vue 3 应用它是比useClipboard更贴合ClipboardItem能力的方案。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐VueUse useClipboard 完全指南在 Vue 3 中响应式读写系统剪贴板VueUse useClipboard 完全指南在 Vue 3 中响应式读写系统剪贴板 导读 useClipboard 是 VueUse 对浏览器 Clipb前端PhotoGIMP 安装教程3 步让免费开源的 GIMP 长出 Photoshop 的手感PhotoGIMP 安装教程3 步让免费开源的 GIMP 长出 Photoshop 的手感 PhotoGIMP 是一款完全免费的 GIMP 3.0 补丁包CAT 进阶调优指南采样策略、路由容灾与海量监控数据性能优化技巧CAT 进阶调优指南采样策略、路由容灾与海量监控数据性能优化技巧 CAT 是美团点评开源的实时应用监控平台支持 Java、C/C、Node.js、Pyt可观测性指标监控告警APM后端链路追踪上一篇mousetrap 源码解读用一行 API 识别在资源管理器里双击启动的 Windows CLI 进程下一篇基于 AWS SDK for C 的 Hello Rekognition 入门示例编译、运行与 ListCollections 调用解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考