vueuse-functions

VueUse 函数

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

适用时机

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

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

函数

下方列出的所有函数均属于 VueUse 库；每个章节按函数功能分类。

IMPORTANT：每个函数条目都包含简短的 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	创建可用于访问和修改 LocalStorage 或 SessionStorage 的响应式 ref	AUTO
useStorageAsync	支持异步操作的响应式存储	AUTO
useThrottledRefHistory	useRefHistory 的简写形式，使用节流筛选器	AUTO

元素

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

浏览器

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
useCssSupports	兼容 SSR 且具备响应性的 CSS.supports	AUTO
useCssVar	操作 CSS 变量	AUTO
useDark	响应式深色模式，并自动持久化数据	AUTO
useEventListener	轻松使用 EventListener	AUTO
useEyeDropper	响应式 EyeDropper API	AUTO
useFavicon	响应式 favicon	AUTO
useFileDialog	轻松打开文件对话框	AUTO
useFileSystemAccess	使用 FileSystemAccessAPI 创建、读取和写入本地文件	AUTO
useFullscreen	响应式 Fullscreen API	AUTO
useGamepad	为 Gamepad API 提供响应式绑定	AUTO
useImage	在浏览器中响应式加载图像	AUTO
useLiveAnnouncer	以无障碍方式向屏幕阅读器用户播报消息（ARIA live 区域）	AUTO
useMediaControls	为 audio 和 video 元素提供响应式媒体控件	AUTO
useMediaQuery	响应式 Media Query	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
useWebMCP	注册 WebMCP 工具，并将其生命周期与当前 Vue 作用域绑定	AUTO
useWebNotification	响应式 Notification	AUTO
useWebWorker	简单注册 Web Workers 并进行通信	AUTO
useWebWorkerFn	运行耗时函数而不阻塞 UI	AUTO

Sensors

Function	Description	Invocation
onClickOutside	监听元素外部的点击	AUTO
onElementRemoval	当该元素或包含它的任何元素从 DOM 中移除时触发	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	在指定时间后变为 true 的响应式值	AUTO
useTimeoutFn	带控制功能的 setTimeout 封装	AUTO
useTimestamp	响应式当前时间戳	AUTO
useTransition	值之间的过渡	AUTO

组件

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

监听

功能	描述	调用方式
until	等待变化的一次性监听	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

响应性

Function	Description	Invocation
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	双向同步 refs	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	响应式倒计时器，单位为秒	AUTO
useDateFormat	根据传入的令牌字符串获取格式化后的日期	AUTO
useTemporalNow	响应式 Temporal API，支持时区转换和日历系统	AUTO
useTimeAgo	响应式相对时间	AUTO
useTimeAgoIntl	支持国际化的响应式相对时间	AUTO

工具

Function	Description	Invocation
createDisposableDirective	用于编写可释放指令的工具	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

Function	Description	Invocation
useIpcRenderer	提供 ipcRenderer 及其所有 API，并支持 Vue 响应式	EXTERNAL
useIpcRendererInvoke	响应式的 ipcRenderer.invoke API 结果	EXTERNAL
useIpcRendererOn	轻松使用 ipcRenderer.on，并在组件卸载时自动调用 ipcRenderer.removeListener	EXTERNAL
useZoomFactor	响应式的 WebFrame 缩放系数	EXTERNAL
useZoomLevel	响应式的 WebFrame 缩放级别	EXTERNAL

@Firebase

Function	Description	Invocation
useAuth	响应式的 Firebase Auth 绑定	EXTERNAL
useFirestore	响应式的 Firestore 绑定	EXTERNAL
useRTDB	响应式的 Firebase Realtime Database 绑定	EXTERNAL

@Head

Function	Description	Invocation
createHead	创建 head 管理器实例。	EXTERNAL
useHead	响应式更新 head 元标签。	EXTERNAL

@Integrations

Function	Description	Invocation
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

Function	Description	Invocation
createGenericProjection	createProjection 的通用版本	EXTERNAL
createProjection	在两个域之间进行响应式数值投影	EXTERNAL
logicAnd	针对 refs 的 AND 条件	EXTERNAL
logicNot	针对 ref 的 NOT 条件	EXTERNAL
logicOr	针对 refs 的 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

Function	描述	调用方式
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

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

@Sound

Function	描述	调用方式
useSound	响应式地播放音效。	EXTERNAL