vueuse

用途

VueUse 是 Vue Composition API 的核心实用工具集合。在编写自定义 composable 之前建议先查阅 VueUse，因为大多数常见模式已经实现。当前稳定版本为 VueUse 14.x，适用于 Vue 3.5+。

安装

Vue 3 项目：

pnpm add @vueuse/core

Nuxt 项目：

pnpm add @vueuse/nuxt @vueuse/core

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
})

Nuxt 模块会自动导入 composables，无需手动 import。

主要能力（分类与示例）

• State（状态）：useLocalStorage、useSessionStorage、useRefHistory
• Elements（元素）：useElementSize、useIntersectionObserver、useResizeObserver
• Browser（浏览器）：useClipboard、useFullscreen、useMediaQuery
• Sensors（传感器）：useMouse、useKeyboard、useDeviceOrientation
• Network（网络）：useFetch、useWebSocket、useEventSource
• Animation（动画）：useTransition、useInterval、useTimeout
• Component（组件）：useVModel、useVirtualList、useTemplateRefsList
• Watch（侦听）：watchDebounced、watchThrottled、watchOnce
• Reactivity（响应式）：createSharedComposable、toRef、toReactive
• Array（数组）：useArrayFilter、useArrayMap、useSorted
• Time（时间）：useDateFormat、useNow、useTimeAgo
• Utilities（工具）：useDebounce、useThrottle、useMemoize

使用方式

按需加载 composable 参考文件：查找 composable 时加载 references/composables.md；查看具体 composable 时加载 composables/<name>.md。不要一次性加载全部文件，只加载与当前任务相关的内容。

常见模式

状态持久化：

const state = useLocalStorage('my-key', { count: 0 })

鼠标追踪：

const { x, y } = useMouse()

防抖 ref：

const search = ref('')
const debouncedSearch = refDebounced(search, 300)

共享 composable（单例）：

const useSharedMouse = createSharedComposable(useMouse)

目标元素引用

当目标是组件 ref 而非 DOM 元素时：

import type { MaybeElementRef } from '@vueuse/core'

// 组件 ref 需要 .$el 才能拿到 DOM 元素
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef) // ❌ Won't work

// 使用 MaybeElementRef 模式
import { unrefElement } from '@vueuse/core'

const el = computed(() => unrefElement(compRef)) // Gets .$el
const { width } = useElementSize(el) // ✅ Works

或直接访问 $el：

const compRef = ref<ComponentInstance>()

onMounted(() => {
  const el = compRef.value?.$el as HTMLElement
  const { width } = useElementSize(el)
})

适用场景

Vue 3 与 Nuxt 项目中，需要快速接入鼠标/键盘/设备方向等传感器、本地或会话存储状态、剪贴板与全屏等浏览器能力、WebSocket 与 EventSource 等网络通信、防抖节流与共享单例等通用逻辑时，可直接使用对应 composable，避免重复造轮子。

限制（SSR 注意事项）

许多 VueUse composable 使用了 SSR 期间不可用的浏览器 API。可通过 isClient 判断：

import { isClient } from '@vueuse/core'

if (isClient) {
  // Browser-only code
  const { width } = useWindowSize()
}

或包裹在 onMounted 中：

const width = ref(0)

onMounted(() => {
  // Only runs in browser
  const { width: w } = useWindowSize()
  width.value = w.value
})

也可使用本身 SSR 安全的 composable：

// 这些内部会检查 isClient
const mouse = useMouse() // Returns {x: 0, y: 0} on server
const storage = useLocalStorage('key', 'default') // Uses default on server

@vueuse/nuxt 会自动处理 SSR，composable 在服务端返回安全默认值。

暂未提供

关于该工具的收费、价格方案与具体平台支持范围，当前资料未提供。