VueUse是 Vue 生态系统中目前最流行、功能最强大的工具函数集合Utility Functions Collection。它基于Composition API设计提供了超过 200 个开箱即用的函数涵盖了从基础状态管理、浏览器 API 调用、DOM 操作到高级动画、网络请求等几乎所有前端开发场景。它的核心理念是“将原本非响应式的浏览器 API 或复杂逻辑封装成响应式的组合式函数Composables让开发者无需重复造轮子。”一、核心优势与特点开箱即用 (Out of the Box)无需配置安装即可使用覆盖了绝大多数日常开发需求。纯 Composition API所有函数均以use开头如useMouse,useStorage完美契合 Vue 3 的逻辑复用模式。自动清理副作用内部自动处理事件监听移除、定时器清除等防止内存泄漏。TypeScript 友好提供完整的类型定义开发体验极佳。SSR 支持大多数函数都兼容服务端渲染Nuxt.js 等。按需引入支持模块化导入不会显著增加打包体积。二、主要功能分类及使用场景VueUse 的功能非常庞大以下是几类最常用的场景1. 状态管理与持久化场景需要在本地存储用户偏好、表单草稿或登录态。函数useStorage,useLocalStorage,useSessionStorage,useMemory.优势自动同步响应式数据与浏览器存储刷新页面数据不丢失。2. 浏览器信息与设备感知场景获取网络状态、电池电量、地理位置、屏幕方向、深色模式检测。函数useNetwork,useBattery,useGeolocation,useDark,useToggle.优势将异步或事件驱动的 API 转化为响应式引用Ref。3. DOM 操作与交互场景监听鼠标位置、元素尺寸变化、全屏控制、点击外部关闭弹窗。函数useMouse,useElementSize,useFullscreen,onClickOutside,useDraggable.优势省去手动添加/移除事件监听器的繁琐代码。4. 动画与过渡场景数字计数动画、列表过渡、鼠标跟随效果。函数useTransition,useRafFn,useSpring(需配合 vueuse/motion).优势轻松实现流畅的数值变化和交互动画。5. 工具与格式化场景防抖节流、日期格式化、Base64 编码、剪贴板操作。函数useDebounceFn,useThrottleFn,useDateFormat,useClipboard,useBase64.三、完整使用示例1. 安装# npmnpminstallvueuse/core# yarnyarnaddvueuse/core# pnpmpnpmaddvueuse/core提示如果你使用的是 Nuxt 3它已内置 VueUse只需在nuxt.config.ts中配置即可无需单独安装。2. 基础示例深色模式切换 本地存储这个示例展示了如何使用useDark和useToggle快速实现主题切换并自动保存到本地。script setup import { useDark, useToggle } from vueuse/core // 1. 监听系统深色模式并同步到 classdark const isDark useDark({ selector: html, // 默认就是 html可省略 valueDark: dark, valueLight: , }) // 2. 创建一个切换函数 const toggleDark useToggle(isDark) /script template div classapp-container h1当前模式{{ isDark ? 深色 : ☀️ 浅色 }}/h1 button clicktoggleDark() 切换主题 /button /div /template style /* 假设你的 CSS 变量已配置好 */ html.dark { background-color: #121212; color: #fff; } /style3. 进阶示例综合仪表盘鼠标追踪 网络状态 剪贴板这个示例模拟一个后台仪表盘的小部件展示多个功能的组合使用。script setup import { useMouse, useNetwork, useClipboard, useDateFormat, useNow, useFullscreen } from vueuse/core import { ref } from vue // --- 1. 鼠标追踪 --- const { x, y } useMouse() // --- 2. 网络状态监控 --- const network useNetwork() const networkStatus computed(() { if (!network.isOnline.value) return ❌ 离线 return ✅ 在线 (${network.downlink || ?}Mbps) }) // --- 3. 剪贴板操作 --- const inputText ref(https://vueuse.org) const { copy, copied, text } useClipboard({ source: inputText }) // --- 4. 时间格式化 --- const now useNow() const formattedTime computed(() useDateFormat(now, YYYY-MM-DD HH:mm:ss).value) // --- 5. 全屏控制 --- const { isFullscreen, toggle } useFullscreen() /script template div classdashboard p-4 border rounded shadow-lg max-w-md mx-auto mt-10 h2 classtext-xl font-bold mb-4VueUse 综合演示/h2 !-- 鼠标位置 -- div classmb-3 p classtext-sm text-gray-500鼠标位置:/p pX: {{ x }}, Y: {{ y }}/p /div !-- 网络状态 -- div classmb-3 p classtext-sm text-gray-500网络状态:/p p :classnetwork.isOnline ? text-green-600 : text-red-600 {{ networkStatus }} /p /div !-- 时间显示 -- div classmb-3 p classtext-sm text-gray-500当前服务器时间:/p p classfont-mono{{ formattedTime }}/p /div !-- 剪贴板功能 -- div classmb-3 p classtext-sm text-gray-500 mb-1复制链接:/p div classflex gap-2 input v-modelinputText classborder px-2 py-1 rounded flex-1 / button clickcopy() classbg-blue-500 text-white px-3 py-1 rounded hover:bg-blue-600 {{ copied ? 已复制! : 复制 }} /button /div /div !-- 全屏功能 -- div classmb-3 button clicktoggle classw-full bg-gray-800 text-white py-2 rounded {{ isFullscreen ? 退出全屏 : 进入全屏 }} /button /div /div /template4. 高级场景防抖搜索请求在实际开发中搜索框输入通常需要做防抖处理。script setup import { ref } from vue import { useDebounceFn } from vueuse/core const searchText ref() const results ref([]) const loading ref(false) // 定义搜索逻辑 const searchAPI async (query) { if (!query) { results.value [] return } loading.value true // 模拟 API 请求 await new Promise(resolve setTimeout(resolve, 500)) results.value [结果 1: ${query}, 结果 2: ${query}, 结果 3: ${query}] loading.value false } // 使用 useDebounceFn 创建防抖函数 (延迟 500ms) const debouncedSearch useDebounceFn((query) { searchAPI(query) }, 500) // 监听输入变化 const handleInput () { debouncedSearch(searchText.value) } /script template div input v-modelsearchText inputhandleInput placeholder输入内容搜索防抖 500ms... classborder p-2 w-full / div v-ifloading加载中.../div ul li v-foritem in results :keyitem{{ item }}/li /ul /div /template四、最佳实践建议按需导入虽然 VueUse 支持全局自动导入通过 unplugin-vue-components但在大型项目中显式导入如import { useMouse } from vueuse/core更有利于树摇Tree-shaking和代码清晰度。不要过度封装如果逻辑非常简单例如只是简单的ref不必强行使用 VueUse保持代码简洁。阅读文档VueUse 的文档非常详细每个函数都有 “Source”, “Types”, “Demo” 链接遇到问题优先查阅官方文档。组合使用VueUse 的强大在于组合。你可以将useMouse和useElementBounding结合轻松实现复杂的鼠标交互效果。五、总结VueUse 是 Vue 3 开发的瑞士军刀。它极大地减少了样板代码让开发者能专注于业务逻辑本身。无论是简单的“复制文本”、“深色模式”还是复杂的“手势识别”、“虚拟列表”VueUse 都能提供成熟、稳定且高性能的解决方案。对于任何 Vue 3 项目它都是首选的依赖库之一。官方文档地址https://vueuse.org/ (支持中文)
VueUse 功能介绍使用场景及完整使用示例
VueUse是 Vue 生态系统中目前最流行、功能最强大的工具函数集合Utility Functions Collection。它基于Composition API设计提供了超过 200 个开箱即用的函数涵盖了从基础状态管理、浏览器 API 调用、DOM 操作到高级动画、网络请求等几乎所有前端开发场景。它的核心理念是“将原本非响应式的浏览器 API 或复杂逻辑封装成响应式的组合式函数Composables让开发者无需重复造轮子。”一、核心优势与特点开箱即用 (Out of the Box)无需配置安装即可使用覆盖了绝大多数日常开发需求。纯 Composition API所有函数均以use开头如useMouse,useStorage完美契合 Vue 3 的逻辑复用模式。自动清理副作用内部自动处理事件监听移除、定时器清除等防止内存泄漏。TypeScript 友好提供完整的类型定义开发体验极佳。SSR 支持大多数函数都兼容服务端渲染Nuxt.js 等。按需引入支持模块化导入不会显著增加打包体积。二、主要功能分类及使用场景VueUse 的功能非常庞大以下是几类最常用的场景1. 状态管理与持久化场景需要在本地存储用户偏好、表单草稿或登录态。函数useStorage,useLocalStorage,useSessionStorage,useMemory.优势自动同步响应式数据与浏览器存储刷新页面数据不丢失。2. 浏览器信息与设备感知场景获取网络状态、电池电量、地理位置、屏幕方向、深色模式检测。函数useNetwork,useBattery,useGeolocation,useDark,useToggle.优势将异步或事件驱动的 API 转化为响应式引用Ref。3. DOM 操作与交互场景监听鼠标位置、元素尺寸变化、全屏控制、点击外部关闭弹窗。函数useMouse,useElementSize,useFullscreen,onClickOutside,useDraggable.优势省去手动添加/移除事件监听器的繁琐代码。4. 动画与过渡场景数字计数动画、列表过渡、鼠标跟随效果。函数useTransition,useRafFn,useSpring(需配合 vueuse/motion).优势轻松实现流畅的数值变化和交互动画。5. 工具与格式化场景防抖节流、日期格式化、Base64 编码、剪贴板操作。函数useDebounceFn,useThrottleFn,useDateFormat,useClipboard,useBase64.三、完整使用示例1. 安装# npmnpminstallvueuse/core# yarnyarnaddvueuse/core# pnpmpnpmaddvueuse/core提示如果你使用的是 Nuxt 3它已内置 VueUse只需在nuxt.config.ts中配置即可无需单独安装。2. 基础示例深色模式切换 本地存储这个示例展示了如何使用useDark和useToggle快速实现主题切换并自动保存到本地。script setup import { useDark, useToggle } from vueuse/core // 1. 监听系统深色模式并同步到 classdark const isDark useDark({ selector: html, // 默认就是 html可省略 valueDark: dark, valueLight: , }) // 2. 创建一个切换函数 const toggleDark useToggle(isDark) /script template div classapp-container h1当前模式{{ isDark ? 深色 : ☀️ 浅色 }}/h1 button clicktoggleDark() 切换主题 /button /div /template style /* 假设你的 CSS 变量已配置好 */ html.dark { background-color: #121212; color: #fff; } /style3. 进阶示例综合仪表盘鼠标追踪 网络状态 剪贴板这个示例模拟一个后台仪表盘的小部件展示多个功能的组合使用。script setup import { useMouse, useNetwork, useClipboard, useDateFormat, useNow, useFullscreen } from vueuse/core import { ref } from vue // --- 1. 鼠标追踪 --- const { x, y } useMouse() // --- 2. 网络状态监控 --- const network useNetwork() const networkStatus computed(() { if (!network.isOnline.value) return ❌ 离线 return ✅ 在线 (${network.downlink || ?}Mbps) }) // --- 3. 剪贴板操作 --- const inputText ref(https://vueuse.org) const { copy, copied, text } useClipboard({ source: inputText }) // --- 4. 时间格式化 --- const now useNow() const formattedTime computed(() useDateFormat(now, YYYY-MM-DD HH:mm:ss).value) // --- 5. 全屏控制 --- const { isFullscreen, toggle } useFullscreen() /script template div classdashboard p-4 border rounded shadow-lg max-w-md mx-auto mt-10 h2 classtext-xl font-bold mb-4VueUse 综合演示/h2 !-- 鼠标位置 -- div classmb-3 p classtext-sm text-gray-500鼠标位置:/p pX: {{ x }}, Y: {{ y }}/p /div !-- 网络状态 -- div classmb-3 p classtext-sm text-gray-500网络状态:/p p :classnetwork.isOnline ? text-green-600 : text-red-600 {{ networkStatus }} /p /div !-- 时间显示 -- div classmb-3 p classtext-sm text-gray-500当前服务器时间:/p p classfont-mono{{ formattedTime }}/p /div !-- 剪贴板功能 -- div classmb-3 p classtext-sm text-gray-500 mb-1复制链接:/p div classflex gap-2 input v-modelinputText classborder px-2 py-1 rounded flex-1 / button clickcopy() classbg-blue-500 text-white px-3 py-1 rounded hover:bg-blue-600 {{ copied ? 已复制! : 复制 }} /button /div /div !-- 全屏功能 -- div classmb-3 button clicktoggle classw-full bg-gray-800 text-white py-2 rounded {{ isFullscreen ? 退出全屏 : 进入全屏 }} /button /div /div /template4. 高级场景防抖搜索请求在实际开发中搜索框输入通常需要做防抖处理。script setup import { ref } from vue import { useDebounceFn } from vueuse/core const searchText ref() const results ref([]) const loading ref(false) // 定义搜索逻辑 const searchAPI async (query) { if (!query) { results.value [] return } loading.value true // 模拟 API 请求 await new Promise(resolve setTimeout(resolve, 500)) results.value [结果 1: ${query}, 结果 2: ${query}, 结果 3: ${query}] loading.value false } // 使用 useDebounceFn 创建防抖函数 (延迟 500ms) const debouncedSearch useDebounceFn((query) { searchAPI(query) }, 500) // 监听输入变化 const handleInput () { debouncedSearch(searchText.value) } /script template div input v-modelsearchText inputhandleInput placeholder输入内容搜索防抖 500ms... classborder p-2 w-full / div v-ifloading加载中.../div ul li v-foritem in results :keyitem{{ item }}/li /ul /div /template四、最佳实践建议按需导入虽然 VueUse 支持全局自动导入通过 unplugin-vue-components但在大型项目中显式导入如import { useMouse } from vueuse/core更有利于树摇Tree-shaking和代码清晰度。不要过度封装如果逻辑非常简单例如只是简单的ref不必强行使用 VueUse保持代码简洁。阅读文档VueUse 的文档非常详细每个函数都有 “Source”, “Types”, “Demo” 链接遇到问题优先查阅官方文档。组合使用VueUse 的强大在于组合。你可以将useMouse和useElementBounding结合轻松实现复杂的鼠标交互效果。五、总结VueUse 是 Vue 3 开发的瑞士军刀。它极大地减少了样板代码让开发者能专注于业务逻辑本身。无论是简单的“复制文本”、“深色模式”还是复杂的“手势识别”、“虚拟列表”VueUse 都能提供成熟、稳定且高性能的解决方案。对于任何 Vue 3 项目它都是首选的依赖库之一。官方文档地址https://vueuse.org/ (支持中文)
