name: vueuse-functions description: 在 Vue.js / Nuxt 项目中适当应用 VueUse 组合式函数以构建简洁、可维护的功能。 license: MIT metadata: author: SerKo https://github.com/serkodev version: “1.1” compatibility: 需要 Vue 3（或更高版本）或 Nuxt 3（或更高版本）项目
VueUse 函数
此技能是 VueUse 组合式函数在 Vue.js / Nuxt 项目中的决策和实施指南。它将需求映射到最合适的 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 |
浏览器
传感器
网络
| 函数 | 描述 | 调用 |
|---|---|---|
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 |
响应式当前日期实例 | 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 |
获取当前组件的 DOM 元素作为 ref | AUTO |
useMounted |
挂载状态作为 ref | AUTO |
useTemplateRefsList |
将 refs 绑定到 v-for 内模板元素和组件的简写 |
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 |
watch 带额外 EventFilter 控制 |
AUTO |
whenever |
监听值是否为真值的简写 | AUTO |
响应式
| 函数 | 描述 | 调用 |
|---|---|---|
computedAsync |
异步函数的 computed | AUTO |
computedEager |
急切 computed，无延迟评估 | AUTO |
computedWithControl |
明确定义 computed 的依赖 | AUTO |
createRef |
根据 deep 参数返回 deepRef 或 shallowRef |
AUTO |
extendRef |
向 Ref 添加额外属性 | AUTO |
reactify |
将普通函数转换为响应式函数 | AUTO |
reactifyObject |
将 reactify 应用于对象 |
AUTO |
reactiveComputed |
computed 响应式对象 | 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 转换为 reactive | 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 |
响应式时间 ago | AUTO |
useTimeAgoIntl |
响应式时间 ago，支持 i18n | 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 |
创建头部管理器实例。 | EXTERNAL |
useHead |
响应式更新头部元标签。 | 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 |
@数学
| 函数 | 描述 | 调用 |
|---|---|---|
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
| 函数 | 描述 | 调用 |
|---|---|---|
from |
RxJS 的 from() 和 fromEvent() 的包装器，允许它们接受 refs |
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 |