VueUse：为 Vue 3 Composition API 赋能的实用工具集 – wiki基地

---

VueUse：为 Vue 3 Composition API 注入强大动能的实用工具集

引言：Vue 3 与 Composition API 的新时代

Vue.js 作为前端开发领域备受欢迎的框架，其 3.0 版本的发布标志着一个重要的里程碑。Vue 3 不仅仅是性能上的巨大提升和内部架构的重塑，更核心的是引入了 Composition API（组合式 API）。这一全新的 API 范式旨在解决 Vue 2 中 Options API 在大型、复杂应用中遇到的逻辑组织、复用和 TypeScript 支持等方面的痛点。

Composition API 提供了更灵活、更强大的代码组织方式。开发者可以将相关的逻辑（如状态 ref、reactive，计算属性 computed，生命周期钩子 onMounted, onUnmounted 等）聚合在独立的、可复用的函数（通常称为 “Composables” 或 “组合式函数”）中。这极大地提高了代码的可读性、可维护性，并使得逻辑的提取和跨组件共享变得前所未有的简单。

然而，尽管 Composition API 本身设计精良，但在实际开发中，开发者很快会发现许多常见的模式和需求是重复出现的。例如：

• 监听浏览器窗口大小变化。
• 与 localStorage 或 sessionStorage 进行交互并保持响应性。
• 处理用户输入时的防抖（Debounce）或节流（Throttle）。
• 跟踪鼠标位置或设备方向。
• 管理页面标题或 Favicon。
• 与 Intersection Observer 或 Resize Observer 等现代浏览器 API 交互。

为每一个这样的需求从头编写 Composition API 逻辑，虽然可行，但无疑会增加开发者的负担，产生大量样板代码，并且难以保证所有实现都达到高质量和最佳实践。这时，一个专注于提供高质量、可复用组合式函数的工具集就显得尤为重要。

VueUse 的诞生：应运而生的 Composition API 军火库

正是在这样的背景下，VueUse 应运而生。它由 Vue 核心团队成员 Anthony Fu 发起并主要维护，是一个基于 Composition API 的、庞大且持续增长的实用工具函数集合。VueUse 的核心目标是：将常用的 Web 开发模式和浏览器 API 封装成简洁、易用、类型安全且与 Vue 响应式系统无缝集成的组合式函数，从而极大地简化开发流程，提升开发效率和代码质量。

可以把 VueUse 想象成 Vue 3 Composition API 的“瑞士军刀”或“终极插件库”。它不是一个框架，而是一个精心策划的函数库，开发者可以按需挑选、独立使用其中的任何函数，而无需引入整个库。

VueUse 的核心特性与优势

VueUse 之所以能在短时间内获得广泛关注和应用，离不开其诸多显著的特性和优势：

1. 全面的功能覆盖：VueUse 提供了超过 200+ 个精心设计的函数，涵盖了状态管理、传感器、浏览器 API、DOM 操作、动画、网络、工具类等多个方面。几乎所有你能想到的与浏览器环境、用户交互、状态管理相关的常见任务，都能在 VueUse 中找到现成的解决方案。
2. 无缝集成 Vue 响应式系统：VueUse 的所有函数都深度利用了 Vue 的 ref、reactive、watch 等核心响应式 API。这意味着你从 VueUse 函数中获取的数据（如鼠标坐标 useMouse().x、网络状态 useNetwork().isOnline）都是响应式的，可以直接在模板中使用或在 computed、watch 中依赖，当底层数据变化时，UI 会自动更新。
3. 按需引入与 Tree-Shaking：VueUse 遵循现代 JavaScript 的模块化设计，每个函数都是独立的、可导出的。结合现代构建工具（如 Vite、Webpack），你可以只引入你需要的函数，未使用的函数会在打包过程中被 Tree-Shaking 机制移除，从而最大程度地减小最终产物体积。
4. TypeScript 支持：VueUse 是用 TypeScript 编写的，并提供了完备的类型定义。这对于使用 TypeScript 的 Vue 3 项目来说是一个巨大的福音，能够提供强大的类型检查、自动补全和更好的开发体验，有效减少运行时错误。
5. 高质量与最佳实践：每个 VueUse 函数都经过精心设计和社区测试，遵循了 Composition API 的最佳实践。例如，许多与事件监听或订阅相关的函数（如 useEventListener, useIntersectionObserver）都会自动处理生命周期，在组件卸载时清理副作用（移除监听器、取消订阅等），避免内存泄漏。
6. 易于使用和学习：函数命名直观，API 设计简洁。通常只需要导入函数并调用即可。良好的文档和示例也大大降低了学习成本。同时，阅读 VueUse 的源码本身也是学习高级 Composition API 用法和 JavaScript 技巧的绝佳途径。
7. 非侵入式：VueUse 不强制任何特定的架构或模式，它只是提供工具。你可以自由地将其与其他状态管理库（如 Pinia、Vuex）、UI 库或你自己的组合式函数结合使用。
8. 活跃的社区与维护：VueUse 拥有一个活跃的社区和积极的维护团队，不断有新的函数被添加，现有函数也在持续优化和修复 bug。

深入探索 VueUse 的核心功能分类

为了更好地理解 VueUse 的强大之处，我们来深入探讨其主要的几个功能分类和代表性函数：

1. 传感器 (Sensors)

这类函数用于与设备的物理传感器或浏览器的状态传感器交互，并将数据转化为响应式引用。

• useMouse(): 实时跟踪鼠标在页面或特定元素内的坐标 (x, y)。
• useScroll(): 监听窗口或可滚动元素的滚动位置 (x, y)，以及滚动状态（是否正在滚动 isScrolling，滚动方向 directions）。
• useDevicePixelRatio(): 获取设备的物理像素与 CSS 像素的比率，对高清屏适配有用。
• useNetwork(): 监测网络连接状态 (isOnline)、类型 (type)、有效类型 (effectiveType) 等信息。
• useGeolocation(): 获取设备的地理位置信息（经纬度 coords、时间戳 timestamp），并处理权限请求。
• useMediaQuery(): 响应式地匹配 CSS 媒体查询，常用于响应式布局判断。
• useIdle(): 检测用户是否处于空闲状态（无鼠标移动、键盘输入等）。
• useElementVisibility(): 判断一个元素是否在视口内可见。

示例：使用 useMouse 获取鼠标位置

“`vue

“`

2. 状态 (State)

这类函数专注于简化状态管理，尤其是在持久化、历史记录、全局共享等方面。

• useLocalStorage(key, initialValue) / useSessionStorage(key, initialValue): 创建一个与 localStorage 或 sessionStorage 同步的响应式 ref。当 ref 改变时，存储会自动更新；反之，当存储被其他标签页修改时，ref 也会同步更新（可选）。
• useRefHistory(ref): 为一个 ref 或 reactive 对象提供撤销 (undo) 和重做 (redo) 的能力，自动记录状态变更历史。
• createGlobalState(() => { ... }): 创建可在多个组件实例间共享的全局响应式状态，避免了 prop drilling 或复杂的 store 设置。
• useDebouncedRef(ref, delay) / useThrottledRef(ref, delay): 为输入 ref 创建一个防抖或节流的版本，常用于优化输入框搜索、窗口 resize 等高频触发场景。
• useStorageAsync(key, initialValue, storage): useLocalStorage/useSessionStorage 的异步版本，允许使用 IndexedDB 等异步存储。

示例：使用 useLocalStorage 持久化用户偏好

“`vue

“`

3. 元素 (Elements)

这类函数主要用于与 DOM 元素进行交互或获取元素信息。

• useEventListener(target, event, listener, options): 以响应式和自动清理的方式添加事件监听器。target 可以是 ref<Element>、window、document 等。
• useIntersectionObserver(target, callback, options): 封装 IntersectionObserver API，用于检测元素何时进入或离开视口（或另一个元素），常用于图片懒加载、无限滚动等。
• useResizeObserver(target, callback, options): 封装 ResizeObserver API，用于监听元素的尺寸变化。
• useElementSize(target): 获取元素的实时尺寸 (width, height)。
• useDraggable(target, options): 让一个元素变得可拖拽，提供拖拽过程中的位置信息。
• onClickOutside(target, handler): 当用户点击指定元素外部时触发回调。常用于关闭下拉菜单、模态框等。

示例：使用 useEventListener 监听窗口大小变化

“`vue

“`

4. 浏览器 (Browser)

这类函数提供了与浏览器本身功能交互的便捷封装。

• useTitle(title): 响应式地设置页面标题 (document.title)。传入 ref 或 computed 时，标题会随其变化而自动更新。
• useClipboard(): 提供了复制文本到剪贴板 (copy)、读取剪贴板内容 (text) 以及检查剪贴板权限 (isSupported) 的功能。
• useFavicon(url): 响应式地设置页面的 Favicon。
• usePermission(name): 查询或请求浏览器权限（如 ‘geolocation’, ‘notifications’, ‘camera’）。
• useShare(): 使用 Web Share API 分享内容。
• useUrlSearchParams(): 提供方便的方式来读取和修改当前 URL 的查询参数，并保持响应性。

示例：使用 useTitle 动态设置页面标题

“`vue

“`

5. 动画 (Animation)

提供与动画、定时器相关的工具。

• useTransition(source, options): 对一个数值 ref 或 computed 的变化应用缓动效果，输出一个平滑过渡的响应式值。非常适合创建流畅的数字动画或样式过渡。
• useIntervalFn(callback, interval) / useTimeoutFn(callback, delay): setInterval 和 setTimeout 的响应式、可控（暂停 pause, 恢复 resume）且自动清理的版本。
• useRafFn(callback): requestAnimationFrame 的响应式、可控版本，用于创建高性能动画循环。
• useInterval(interval): 创建一个每隔指定时间自增 1 的响应式计数器。

示例：使用 useTransition 创建数字缓动动画

“`vue

“`

6. 工具类 (Utilities)

包含各种通用的辅助函数，简化常见开发模式。

• useVModel(props, name, emit): 简化在组合式函数中实现 v-model 的逻辑。
• watchDebounced(source, callback, options) / watchThrottled(source, callback, options): 带有防抖或节流功能的 watch。
• tryOnMounted(fn) / tryOnUnmounted(fn): 安全地执行生命周期钩子，即使在组件已经挂载或卸载后调用也不会报错。
• syncRef(left, right) / syncRefs(source, targets): 在多个 ref 之间双向同步数据。
• computedAsync(asyncCalculation, initialValue): 创建一个处理异步计算的 computed，并管理加载状态和错误。

VueUse 的生态系统与社区

VueUse 不仅仅是一个库，它还拥有一个不断发展的生态系统：

• Add-ons: 除了 @vueuse/core 核心库，还有针对特定库或框架的集成插件，如 @vueuse/head (用于管理 <head> 标签)、@vueuse/motion (声明式动画库)、@vueuse/firebase (集成 Firebase)、@vueuse/router (增强 Vue Router 功能) 等。
• 文档与示例: 官方文档（vueuse.org）非常详尽，每个函数都有清晰的说明、参数解释、返回值类型和交互式示例。这是学习和使用 VueUse 的宝贵资源。
• 社区贡献: VueUse 是一个开源项目，鼓励社区贡献新的函数、改进现有函数或修复问题。这种开放性保证了库的活力和广泛适用性。

使用 VueUse 的最佳实践

1. 按需导入: 永远只导入你实际使用的函数，以利用 Tree-Shaking 优化。
   “`typescript
   // 好:
   import { useMouse, useLocalStorage } from ‘@vueuse/core’

   // 不好 (可能导致打包体积增大):
   import * as VueUse from ‘@vueuse/core’
   “`
   2. 理解原理: 虽然 VueUse 封装了复杂性，但了解其背后所使用的 Composition API 和浏览器 API 原理，有助于更好地使用和调试。
   3. 阅读源码: 当遇到疑问或想深入学习时，直接查看 VueUse 在 GitHub 上的源码是非常有益的。其代码风格清晰，是学习 Composition API 实践的优秀范例。
   4. 组合使用: VueUse 的函数本身也是 Composables，可以像积木一样组合使用，创建更复杂的自定义组合式函数。

结论：赋能 Vue 3 开发的必备利器

VueUse 已经成为 Vue 3 生态中不可或缺的一部分。它通过提供一套丰富、高质量、类型安全且与 Vue 响应式系统深度集成的实用工具函数，极大地赋能了 Composition API。使用 VueUse，开发者可以：

• 显著提升开发效率: 避免重复编写常见模式的样板代码，专注于核心业务逻辑。
• 提高代码质量与健壮性: 使用经过社区测试和优化的实现，减少 bug 和内存泄漏风险。
• 改善代码组织与可维护性: 将复杂逻辑封装在语义化的函数调用中，使代码更清晰、更易于理解。
• 拥抱最佳实践: VueUse 本身就是 Composition API 最佳实践的体现，使用它有助于引导开发者写出更符合规范的代码。
• 降低学习曲线: 对于刚接触某些 Web API 或复杂模式的开发者，VueUse 提供了一个易于上手的入口。

总而言之，VueUse 不仅仅是一个工具库，更是 Vue 3 Composition API 开发体验的一次巨大升级。它让开发者能够更轻松、更高效、更优雅地构建功能丰富、性能卓越的 Vue.js 应用程序。如果你正在使用 Vue 3，尤其是 Composition API，那么深入了解和拥抱 VueUse，无疑将为你的开发工作带来巨大的价值。它真正体现了 Composition API 的核心思想——让逻辑复用和代码组织变得简单而强大。

---