vueuse-functions

VueUse 函数

本技能是一份面向 Vue.js / Nuxt 项目的 VueUse 组合式函数决策与实现指南。它将需求映射到最合适的 VueUse 函数，采用正确的用法，并优先使用基于组合式函数的方案，而非定制代码，以保持实现简洁、易维护且高效。

适用场景

• 在协助用户进行 Vue.js / Nuxt 开发时，应用本技能。
• 始终先检查是否可以使用 VueUse 函数实现需求。
• 优先使用 VueUse 组合式函数，而非自定义代码，以提高可读性、可维护性和性能。
• 将需求映射到最合适的 VueUse 函数，并遵循该函数的调用规则。
• 请参阅下方函数表中的 Invocation 字段。例如：
  • AUTO：适用时自动使用。
  • EXTERNAL：仅当用户已安装所需的外部依赖时使用；否则重新考虑，并仅在确实需要时询问用户是否安装。
  • EXPLICIT_ONLY：仅在用户明确要求时使用。

  注意 提示词或 AGENTS.md 中的用户指示可能会覆盖函数默认的 Invocation 规则。

函数

下方列出的所有函数均属于 VueUse 库，各小节按功能对函数进行分类。

重要：每个函数条目都包含简短的 Description 和详细的 Reference。使用任何函数时，务必查阅 ./references 中对应的文档，了解用法详情和类型声明。

状态

函数	描述	调用方式
createGlobalState	将状态保存在全局作用域，以便在多个 Vue 实例间复用	AUTO
createInjectionState	创建可注入组件的全局状态	AUTO
createSharedComposable	使组合式函数可供多个 Vue 实例使用	AUTO
injectLocal	扩展 inject，支持调用 provideLocal 在同一组件中提供值	AUTO
provideLocal	扩展 provide，支持调用 injectLocal 在同一组件中获取值	AUTO
useAsyncState	响应式异步状态	AUTO
useDebouncedRefHistory	为 useRefHistory 提供防抖筛选器的简写形式	AUTO
useLastChanged	记录上次变更的时间戳	AUTO
useLocalStorage	响应式 LocalStorage	AUTO
useManualRefHistory	在使用者调用 commit() 时，手动跟踪 ref 的变更历史	AUTO
useRefHistory	跟踪 ref 的变更历史	AUTO
useSessionStorage	响应式 SessionStorage	AUTO
useStorage	创建响应式 ref，用于访问和修改 LocalStorage 或 SessionStorage	AUTO
useStorageAsync	支持异步操作的响应式存储	AUTO
useThrottledRefHistory	为 useRefHistory 提供节流筛选器的简写形式	AUTO

元素

功能	描述	调用方式
useActiveElement	响应式 document.activeElement	AUTO
useDocumentVisibility	响应式跟踪 document.visibilityState	AUTO
useDraggable	使元素可拖动	AUTO
useDropZone	创建可放置文件的区域	AUTO
useElementBounding	HTML 元素的响应式边界框	AUTO
useElementSize	HTML 元素的响应式尺寸	AUTO
useElementVisibility	跟踪元素在视口中的可见性	AUTO
useIntersectionObserver	检测目标元素的可见性	AUTO
useMouseInElement	与元素相关的响应式鼠标位置	AUTO
useMutationObserver	监听 DOM 树的变化	AUTO
useParentElement	获取给定元素的父元素	AUTO
useResizeObserver	报告元素内容尺寸或边框盒尺寸的变化	AUTO
useWindowFocus	通过 window.onfocus 和 window.onblur 事件响应式跟踪窗口焦点	AUTO
useWindowScroll	响应式窗口滚动状态	AUTO
useWindowSize	响应式窗口尺寸	AUTO

浏览器

Function	Description	Invocation
useBluetooth	响应式 Web Bluetooth API	AUTO
useBreakpoints	响应式视口断点	AUTO
useBroadcastChannel	响应式 BroadcastChannel API	AUTO
useBrowserLocation	响应式浏览器位置	AUTO
useClipboard	响应式 Clipboard API	AUTO
useClipboardItems	响应式 Clipboard API	AUTO
useColorMode	响应式颜色模式（深色／浅色／自定义），并自动持久化数据	AUTO
useCssVar	操作 CSS 变量	AUTO
useDark	响应式深色模式，并自动持久化数据	AUTO
useEventListener	轻松使用 EventListener	AUTO
useEyeDropper	响应式 EyeDropper API	AUTO
useFavicon	响应式网站图标	AUTO
useFileDialog	轻松打开文件对话框	AUTO
useFileSystemAccess	使用 FileSystemAccessAPI 创建、读取和写入本地文件	AUTO
useFullscreen	响应式 Fullscreen API	AUTO
useGamepad	为 Gamepad API 提供响应式绑定	AUTO
useImage	响应式加载浏览器中的图像	AUTO
useMediaControls	为 audio 和 video 元素提供响应式媒体控件	AUTO
useMediaQuery	响应式 媒体查询	AUTO
useMemory	响应式内存信息	AUTO
useObjectUrl	表示对象的响应式 URL	AUTO
usePerformanceObserver	监测性能指标	AUTO
usePermission	响应式 Permissions API	AUTO
usePreferredColorScheme	响应式 prefers-color-scheme 媒体查询	AUTO
usePreferredContrast	响应式 prefers-contrast 媒体查询	AUTO
usePreferredDark	响应式深色主题偏好	AUTO
usePreferredLanguages	响应式 Navigator Languages	AUTO
usePreferredReducedMotion	响应式 prefers-reduced-motion 媒体查询	AUTO
usePreferredReducedTransparency	响应式 prefers-reduced-transparency 媒体查询	AUTO
useScreenOrientation	响应式 Screen Orientation API	AUTO
useScreenSafeArea	响应式 env(safe-area-inset-*)	AUTO
useScriptTag	创建 script 标签	AUTO
useShare	响应式 Web Share API	AUTO
useSSRWidth	用于设置全局视口宽度，以便在渲染依赖视口宽度的 SSR 组件时使用，例如 useMediaQuery 或 useBreakpoints	AUTO
useStyleTag	在 head 中注入响应式 style 元素	AUTO
useTextareaAutosize	根据内容自动更新 textarea 的高度	AUTO
useTextDirection	响应式元素文本的 dir 属性	AUTO
useTitle	响应式文档标题	AUTO
useUrlSearchParams	响应式 URLSearchParams	AUTO
useVibrate	响应式 Vibration API	AUTO
useWakeLock	响应式 Screen Wake Lock API	AUTO
useWebNotification	响应式 Notification	AUTO
useWebWorker	简单注册 Web Workers 并进行通信	AUTO
useWebWorkerFn	运行开销较大的函数而不阻塞 UI	AUTO

Sensors

Function	Description	Invocation
onClickOutside	监听元素外部的点击	AUTO
onElementRemoval	当元素或任何包含它的元素被移除时触发	AUTO
onKeyStroke	监听键盘按键	AUTO
onLongPress	监听对元素的长按	AUTO
onStartTyping	用户开始在不可编辑元素上输入时触发	AUTO
useBattery	响应式 Battery Status API	AUTO
useDeviceMotion	响应式 DeviceMotionEvent	AUTO
useDeviceOrientation	响应式 DeviceOrientationEvent	AUTO
useDevicePixelRatio	响应式追踪 window.devicePixelRatio	AUTO
useDevicesList	响应式 enumerateDevices 列表，显示可用的输入/输出设备	AUTO
useDisplayMedia	响应式 mediaDevices.getDisplayMedia 流媒体	AUTO
useElementByPoint	根据点响应式获取元素	AUTO
useElementHover	元素的响应式悬停状态	AUTO
useFocus	用于追踪或设置 DOM 元素焦点状态的响应式工具	AUTO
useFocusWithin	用于追踪元素或其后代是否获得焦点的响应式工具	AUTO
useFps	响应式 FPS（每秒帧数）	AUTO
useGeolocation	响应式 Geolocation API	AUTO
useIdle	追踪用户是否处于非活动状态	AUTO
useInfiniteScroll	元素的无限滚动	AUTO
useKeyModifier	响应式 Modifier State	AUTO
useMagicKeys	按键按下状态的响应式追踪	AUTO
useMouse	响应式鼠标位置	AUTO
useMousePressed	响应式鼠标按下状态	AUTO
useNavigatorLanguage	响应式 navigator.language	AUTO
useNetwork	响应式 Network status	AUTO
useOnline	响应式在线状态	AUTO
usePageLeave	用于显示鼠标是否离开页面的响应式状态	AUTO
useParallax	轻松创建视差效果	AUTO
usePointer	响应式 pointer state	AUTO
usePointerLock	响应式 pointer lock	AUTO
usePointerSwipe	基于 PointerEvents 的响应式滑动检测	AUTO
useScroll	响应式滚动位置和状态	AUTO
useScrollLock	锁定元素的滚动	AUTO
useSpeechRecognition	响应式 SpeechRecognition	AUTO
useSpeechSynthesis	响应式 SpeechSynthesis	AUTO
useSwipe	基于 TouchEvents 的响应式滑动检测	AUTO
useTextSelection	基于 Window.getSelection 响应式追踪用户的文本选择	AUTO
useUserMedia	响应式 mediaDevices.getUserMedia 流媒体	AUTO

网络

函数	描述	调用方式
useEventSource	EventSource 或 Server-Sent-Events 实例会与 HTTP 服务建立持久连接	AUTO
useFetch	响应式 Fetch API，支持中止请求	AUTO
useWebSocket	响应式 WebSocket 客户端	AUTO

动画

函数	描述	调用方式
useAnimate	响应式 Web Animations API	AUTO
useInterval	响应式计数器，每个间隔递增一次	AUTO
useIntervalFn	带控制功能的 setInterval 封装	AUTO
useNow	响应式当前 Date 实例	AUTO
useRafFn	每次 requestAnimationFrame 时调用函数	AUTO
useTimeout	在指定时间后更新值，并提供控制功能	AUTO
useTimeoutFn	带控制功能的 setTimeout 封装	AUTO
useTimestamp	响应式当前时间戳	AUTO
useTransition	在不同值之间过渡	AUTO

组件

函数	描述	调用方式
computedInject	结合 computed 和 inject	AUTO
createReusableTemplate	在组件作用域内定义并复用模板	AUTO
createTemplatePromise	将模板作为 Promise	AUTO
templateRef	将 ref 绑定到模板元素的简写形式	AUTO
tryOnBeforeMount	安全的 onBeforeMount	AUTO
tryOnBeforeUnmount	安全的 onBeforeUnmount	AUTO
tryOnMounted	安全的 onMounted	AUTO
tryOnScopeDispose	安全的 onScopeDispose	AUTO
tryOnUnmounted	安全的 onUnmounted	AUTO
unrefElement	从 Vue ref 或组件实例中获取底层 DOM 元素	AUTO
useCurrentElement	以 ref 形式获取当前组件的 DOM 元素	AUTO
useMounted	以 ref 形式表示挂载状态	AUTO
useTemplateRefsList	将 refs 绑定到 v-for 中的模板元素和组件的简写形式	AUTO
useVirtualList	轻松创建虚拟列表	AUTO
useVModel	v-model 绑定的简写形式	AUTO
useVModels	props v-model 绑定的简写形式	AUTO

监听

函数	描述	调用方式
until	等待变化的一次性 Promise 监听	AUTO
watchArray	监听数组的新增和移除	AUTO
watchAtMost	限制 watch 的触发次数	AUTO
watchDebounced	防抖监听	AUTO
watchDeep	以 {deep: true} 监听值的简写形式	AUTO
watchIgnorable	可忽略的监听	AUTO
watchImmediate	以 {immediate: true} 监听值的简写形式	AUTO
watchOnce	以 { once: true } 监听值的简写形式	AUTO
watchPausable	可暂停的监听	AUTO
watchThrottled	节流监听	AUTO
watchTriggerable	可手动触发的监听	AUTO
watchWithFilter	带有额外 EventFilter 控制的 watch	AUTO
whenever	监听值为真值的简写形式	AUTO

响应性

函数	描述	调用方式
computedAsync	用于异步函数的计算属性	AUTO
computedEager	不进行惰性求值的即时计算属性	AUTO
computedWithControl	显式定义计算属性的依赖项	AUTO
createRef	根据 deep 参数返回 deepRef 或 shallowRef	AUTO
extendRef	为 Ref 添加额外属性	AUTO
reactify	将普通函数转换为响应式函数	AUTO
reactifyObject	对对象应用 reactify	AUTO
reactiveComputed	计算得到的响应式对象	AUTO
reactiveOmit	响应式地忽略响应式对象中的字段	AUTO
reactivePick	响应式地选取响应式对象中的字段	AUTO
refAutoReset	一段时间后自动重置为默认值的 ref	AUTO
refDebounced	对 ref 值的执行进行防抖	AUTO
refDefault	为 ref 应用默认值	AUTO
refManualReset	创建带有手动重置功能的 ref	AUTO
refThrottled	对 ref 值的变更进行节流	AUTO
refWithControl	对 ref 及其响应性进行精细控制	AUTO
syncRef	双向 ref 同步	AUTO
syncRefs	使目标 refs 与源 ref 保持同步	AUTO
toReactive	将 ref 转换为响应式对象	AUTO
toRef	将值/ref/getter 规范化为 ref 或 computed	EXPLICIT_ONLY
toRefs	扩展版 toRefs，还接受对象的 refs	AUTO

数组

函数	描述	调用方式
useArrayDifference	响应式获取两个数组的差集	AUTO
useArrayEvery	响应式 Array.every	AUTO
useArrayFilter	响应式 Array.filter	AUTO
useArrayFind	响应式 Array.find	AUTO
useArrayFindIndex	响应式 Array.findIndex	AUTO
useArrayFindLast	响应式 Array.findLast	AUTO
useArrayIncludes	响应式 Array.includes	AUTO
useArrayJoin	响应式 Array.join	AUTO
useArrayMap	响应式 Array.map	AUTO
useArrayReduce	响应式 Array.reduce	AUTO
useArraySome	响应式 Array.some	AUTO
useArrayUnique	响应式唯一数组	AUTO
useSorted	响应式数组排序	AUTO

时间

函数	描述	调用方式
useCountdown	useIntervalFn 的封装，提供倒计时功能	AUTO
useDateFormat	根据传入的令牌字符串获取格式化后的日期	AUTO
useTimeAgo	响应式相对时间	AUTO
useTimeAgoIntl	支持国际化的响应式相对时间	AUTO

实用工具

函数	描述	调用方式
createEventHook	用于创建事件钩子的实用工具	AUTO
createUnrefFn	创建一个可接受 ref 和原始值作为参数的普通函数	AUTO
get	访问 ref.value 的简写	EXPLICIT_ONLY
isDefined	用于 Ref 的非空类型守卫	AUTO
makeDestructurable	让对象和数组同时支持解构	AUTO
set	ref.value = x 的简写	EXPLICIT_ONLY
useAsyncQueue	按顺序执行每个异步任务，并将当前任务的结果传递给下一个任务	AUTO
useBase64	响应式地转换为 base64	AUTO
useCached	使用自定义比较器缓存 ref	AUTO
useCloned	ref 的响应式克隆	AUTO
useConfirmDialog	创建事件钩子，以支持模态框和确认对话框链	AUTO
useCounter	带实用函数的基础计数器	AUTO
useCycleList	循环遍历列表中的项目	AUTO
useDebounceFn	对函数的执行进行防抖	AUTO
useEventBus	基础事件总线	AUTO
useMemoize	根据参数缓存函数结果并保持响应性	AUTO
useOffsetPagination	响应式偏移分页	AUTO
usePrevious	保存 ref 的上一个值	AUTO
useStepper	提供用于构建多步骤向导界面的辅助工具	AUTO
useSupported	兼容 SSR 的 isSupported	AUTO
useThrottleFn	对函数的执行进行节流	AUTO
useTimeoutPoll	使用超时轮询某项内容	AUTO
useToggle	带实用函数的布尔切换器	AUTO
useToNumber	响应式地将字符串 ref 转换为数字	AUTO
useToString	响应式地将 ref 转换为字符串	AUTO

@Electron

函数	描述	调用方式
useIpcRenderer	提供 ipcRenderer 及其所有 API	EXTERNAL
useIpcRendererInvoke	响应式的 ipcRenderer.invoke API 结果	EXTERNAL
useIpcRendererOn	便捷地使用 ipcRenderer.on，并在卸载时自动调用 ipcRenderer.removeListener	EXTERNAL
useZoomFactor	响应式的 WebFrame 缩放因子	EXTERNAL
useZoomLevel	响应式的 WebFrame 缩放级别	EXTERNAL

@Firebase

函数	描述	调用方式
useAuth	响应式 Firebase Auth 绑定	EXTERNAL
useFirestore	响应式 Firestore 绑定	EXTERNAL
useRTDB	响应式 Firebase Realtime Database 绑定	EXTERNAL

@Head

函数	描述	调用方式
createHead	创建 head 管理器实例。	EXTERNAL
useHead	响应式更新 head 元标签。	EXTERNAL

@Integrations

函数	描述	调用方式
useAsyncValidator	async-validator 的封装	EXTERNAL
useAxios	axios 的封装	EXTERNAL
useChangeCase	change-case 的响应式封装	EXTERNAL
useCookies	universal-cookie 的封装	EXTERNAL
useDrauu	drauu 的响应式实例	EXTERNAL
useFocusTrap	focus-trap 的响应式封装	EXTERNAL
useFuse	使用 Fuse.js 通过组合式函数轻松实现模糊搜索	EXTERNAL
useIDBKeyval	idb-keyval 的封装	EXTERNAL
useJwt	jwt-decode 的封装	EXTERNAL
useNProgress	nprogress 的响应式封装	EXTERNAL
useQRCode	qrcode 的封装	EXTERNAL
useSortable	sortable 的封装	EXTERNAL

@Math

函数	描述	调用方式
createGenericProjection	createProjection 的通用版本	EXTERNAL
createProjection	在一个定义域到另一个定义域之间进行响应式数值投影	EXTERNAL
logicAnd	ref 的 AND 条件	EXTERNAL
logicNot	ref 的 NOT 条件	EXTERNAL
logicOr	ref 的 OR 条件	EXTERNAL
useAbs	响应式 Math.abs	EXTERNAL
useAverage	响应式地获取数组的平均值	EXTERNAL
useCeil	响应式 Math.ceil	EXTERNAL
useClamp	响应式地将一个值限制在另外两个值之间	EXTERNAL
useFloor	响应式 Math.floor	EXTERNAL
useMath	响应式 Math 方法	EXTERNAL
useMax	响应式 Math.max	EXTERNAL
useMin	响应式 Math.min	EXTERNAL
usePrecision	响应式地设置数字的精度	EXTERNAL
useProjection	在一个定义域到另一个定义域之间进行响应式数值投影	EXTERNAL
useRound	响应式 Math.round	EXTERNAL
useSum	响应式地获取数组的总和	EXTERNAL
useTrunc	响应式 Math.trunc	EXTERNAL

@Motion

函数	描述	调用方式
useElementStyle	将响应式对象同步到目标元素的 CSS 样式	EXTERNAL
useElementTransform	将响应式对象同步到目标元素的 CSS 变换。	EXTERNAL
useMotion	让组件动起来。	EXTERNAL
useMotionProperties	访问目标元素的 Motion 属性。	EXTERNAL
useMotionVariants	处理变体状态和选择。	EXTERNAL
useSpring	弹簧动画。	EXTERNAL

@Router

函数	描述	调用方式
useRouteHash	响应式 route.hash 的简写	EXTERNAL
useRouteParams	响应式 route.params 的简写	EXTERNAL
useRouteQuery	响应式 route.query 的简写	EXTERNAL

@RxJS

函数	描述	调用方式
from	RxJS 的 from() 和 fromEvent() 的封装，使其能够接受 ref	EXTERNAL
toObserver	将 ref 转换为 RxJS Observer 的便捷函数	EXTERNAL
useExtractedObservable	使用从一个或多个组合式函数中提取的 RxJS Observable	EXTERNAL
useObservable	使用 RxJS Observable	EXTERNAL
useSubject	将 RxJS Subject 绑定到 ref，并双向传播值变化	EXTERNAL
useSubscription	使用 RxJS Subscription，无需担心取消订阅或造成内存泄漏	EXTERNAL
watchExtractedObservable	监视从一个或多个组合式函数中提取的 RxJS Observable 的值	EXTERNAL

@SchemaOrg

函数	描述	调用方式
createSchemaOrg	创建 schema.org 管理器实例。	EXTERNAL
useSchemaOrg	响应式更新 schema.org。	EXTERNAL

@Sound

函数	描述	调用方式
useSound	响应式播放音效。	EXTERNAL