Back to Details

vueuse

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

VueUse

VueUse

Collection of essential Vue Composition utilities. Check VueUse before writing custom composables - most patterns already implemented.
Current stable: VueUse 14.x for Vue 3.5+
Vue组合式API实用工具集合。在编写自定义组合式函数前先查看VueUse——大多数模式都已实现。
当前稳定版本： VueUse 14.x 适用于 Vue 3.5+

Installation

安装

Vue 3:
bash
pnpm add @vueuse/core
Nuxt:
bash
pnpm add @vueuse/nuxt @vueuse/core
ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
})
Nuxt module auto-imports composables - no import needed.
Vue 3：
bash
pnpm add @vueuse/core
Nuxt：
bash
pnpm add @vueuse/nuxt @vueuse/core
ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@vueuse/nuxt'],
})
Nuxt模块会自动导入组合式函数——无需手动导入。

Categories

分类

CategoryExamples
StateuseLocalStorage, useSessionStorage, useRefHistory
ElementsuseElementSize, useIntersectionObserver, useResizeObserver
BrowseruseClipboard, useFullscreen, useMediaQuery
SensorsuseMouse, useKeyboard, useDeviceOrientation
NetworkuseFetch, useWebSocket, useEventSource
AnimationuseTransition, useInterval, useTimeout
ComponentuseVModel, useVirtualList, useTemplateRefsList
WatchwatchDebounced, watchThrottled, watchOnce
ReactivitycreateSharedComposable, toRef, toReactive
ArrayuseArrayFilter, useArrayMap, useSorted
TimeuseDateFormat, useNow, useTimeAgo
UtilitiesuseDebounce, useThrottle, useMemoize
分类示例
状态管理useLocalStorage, useSessionStorage, useRefHistory
元素操作useElementSize, useIntersectionObserver, useResizeObserver
浏览器APIuseClipboard, useFullscreen, useMediaQuery
传感器useMouse, useKeyboard, useDeviceOrientation
网络操作useFetch, useWebSocket, useEventSource
动画useTransition, useInterval, useTimeout
组件相关useVModel, useVirtualList, useTemplateRefsList
监听工具watchDebounced, watchThrottled, watchOnce
响应式处理createSharedComposable, toRef, toReactive
数组操作useArrayFilter, useArrayMap, useSorted
时间处理useDateFormat, useNow, useTimeAgo
通用工具useDebounce, useThrottle, useMemoize

Quick Reference

快速参考

Load composable files based on what you need:
Working on...Load file
Finding a composablereferences/composables.md
Specific composable
composables/<name>.md
根据需求加载组合式函数相关文件：
正在进行...加载文件
查找组合式函数references/composables.md
特定组合式函数详情
composables/<name>.md

Loading Files

文件加载建议

Consider loading these reference files based on your task:
  • references/composables.md - if searching for VueUse composables by category or functionality
DO NOT load all files at once. Load only what's relevant to your current task.
根据你的任务考虑加载以下参考文件：
  • references/composables.md - 若按分类或功能搜索VueUse组合式函数
请勿一次性加载所有文件。 仅加载与当前任务相关的文件。

Common Patterns

常见使用模式

State persistence:
ts
const state = useLocalStorage('my-key', { count: 0 })
Mouse tracking:
ts
const { x, y } = useMouse()
Debounced ref:
ts
const search = ref('')
const debouncedSearch = refDebounced(search, 300)
Shared composable (singleton):
ts
const useSharedMouse = createSharedComposable(useMouse)
状态持久化：
ts
const state = useLocalStorage('my-key', { count: 0 })
鼠标追踪：
ts
const { x, y } = useMouse()
防抖响应式变量：
ts
const search = ref('')
const debouncedSearch = refDebounced(search, 300)
共享组合式函数（单例）：
ts
const useSharedMouse = createSharedComposable(useMouse)

SSR Gotchas

SSR注意事项

Many VueUse composables use browser APIs unavailable during SSR.
Check with 
isClient
:
ts
import { isClient } from '@vueuse/core'

if (isClient) {
  // Browser-only code
  const { width } = useWindowSize()
}
Wrap in onMounted:
ts
const width = ref(0)

onMounted(() => {
  // Only runs in browser
  const { width: w } = useWindowSize()
  width.value = w.value
})
Use SSR-safe composables:
ts
// These check isClient internally
const mouse = useMouse() // Returns {x: 0, y: 0} on server
const storage = useLocalStorage('key', 'default') // Uses default on server
@vueuse/nuxt
auto-handles SSR - composables return safe defaults on server.
许多VueUse组合式函数使用了SSR期间不可用的浏览器API。
使用
isClient
检查：
ts
import { isClient } from '@vueuse/core'

if (isClient) {
  // 仅在浏览器中运行的代码
  const { width } = useWindowSize()
}
包裹在onMounted中：
ts
const width = ref(0)

onMounted(() => {
  // 仅在浏览器中运行
  const { width: w } = useWindowSize()
  width.value = w.value
})
使用支持SSR的组合式函数：
ts
// 这些函数内部会自动检查isClient
const mouse = useMouse() // 在服务端返回{x: 0, y: 0}
const storage = useLocalStorage('key', 'default') // 在服务端使用默认值
@vueuse/nuxt
会自动处理SSR - 组合式函数在服务端会返回安全的默认值。

Target Element Refs

目标元素引用

When targeting component refs instead of DOM elements:
ts
import type { MaybeElementRef } from '@vueuse/core'

// Component ref needs .$el to get DOM element
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef) // ❌ Won't work

// Use MaybeElementRef pattern
import { unrefElement } from '@vueuse/core'

const el = computed(() => unrefElement(compRef)) // Gets .$el
const { width } = useElementSize(el) // ✅ Works
Or access 
$el
directly:
ts
const compRef = ref<ComponentInstance>()

onMounted(() => {
  const el = compRef.value?.$el as HTMLElement
  const { width } = useElementSize(el)
})
当目标是组件引用而非DOM元素时：
ts
import type { MaybeElementRef } from '@vueuse/core'

// 组件引用需要通过.$el获取DOM元素
const compRef = ref<ComponentInstance>()
const { width } = useElementSize(compRef) // ❌ 无法正常工作

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

const el = computed(() => unrefElement(compRef)) // 获取.$el
const { width } = useElementSize(el) // ✅ 可以正常工作
或者直接访问
$el
：
ts
const compRef = ref<ComponentInstance>()

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