VueUse：Vue3 开发提速神器-马育民老师

# 介绍

VueUse 是基于 Vue 组合式 API 的**实用工具函数集合库**，由 Vue 核心团队成员 Anthony Fu 主导维护，提供 200+ 开箱即用的组合式函数（Composables），核心目标是**复用逻辑、简化开发、避免重复造轮子**。

### 核心定位
- 适配 Vue 3（主推）与 Vue 2.7+（兼容版），基于 Composition API 设计。
- 把**浏览器 API、DOM 操作、状态管理、业务逻辑**等封装为响应式函数，统一以 `use` 开头（如 `useMouse`、`useStorage`）。

### 核心特点
- **TypeScript 优先**：全量类型定义，代码提示完善，减少类型错误。
- **按需引入（Tree-shaking）**：仅打包用到的函数，不增加冗余体积。
- **SSR 友好**：多数函数兼容 Nuxt 等服务端渲染场景。
- **自动清理副作用**：内部自动移除事件监听、清除定时器，避免内存泄漏。
- **灵活可配置**：支持 ref 传参、自定义事件过滤器、多目标绑定。
- **CDN 可用**：无需打包器，直接通过 CDN 引入使用。

### 优点
1. **大幅提升开发效率**：避免重复编写监听、存储、请求等逻辑。
2. **统一响应式范式**：所有函数遵循 Vue 响应式设计，学习成本低。
3. **轻量高性能**：按需引入，自动清理副作用，不污染环境。
4. **文档完善**：每个函数都有在线演示与详细参数说明。

### 缺点

1. **函数数量多**：200+ 函数需要时间熟悉，易遗漏实用功能。
2. **依赖 Vue 版本**：Vue 2 需单独安装兼容版，部分新函数不支持 Vue 2。
3. **定制化深度有限**：复杂场景可能仍需原生 API 或自定义逻辑。

# 安装

### npm安装

```bash
npm i @vueuse/core
```

### pnpm安装

```
pnpm add @vueuse/core
```

# 引入方式

### 按需引入（推荐）
```javascript
import { useMouse, useStorage } from '@vueuse/core'
```
### 全量引入（不推荐）
```javascript
import * as VueUse from '@vueuse/core'
```
### CDN 引入

```html
<script src="https://unpkg.com/@vueuse/core"></script>
```

# 功能分类

### 1. 状态与响应式

- `useState`：轻量响应式状态
- `useStorage`：本地存储（localStorage/sessionStorage）响应式绑定
- `useGlobalState`：全局状态共享
- `useCounter`：计数器（增减、重置）
- `useToggle`：布尔值切换

### 2. 浏览器 API

- `useMouse`：鼠标位置、按键状态
- `useWindowSize`：窗口宽高响应式
- `useMediaQuery`：媒体查询（如暗黑模式）
- `useClipboard`：剪贴板读写
- `useOnline`：网络状态监听
- `useDocumentVisibility`：页面可见性

### 3. DOM 与元素

- `useElementSize`：元素宽高监听
- `useIntersectionObserver`：交叉观察器（懒加载）
- `useResizeObserver`：元素尺寸变化
- `useClickOutside`：点击元素外部触发
- `useFocus`：元素焦点状态

### 4. 异步与请求

- `useFetch`：响应式网络请求
- `useAsyncState`：异步状态管理
- `useTimeout`：定时器（自动清理）
- `useInterval`：间隔定时器

### 5. 动画与过渡

- `useTransition`：数值过渡动画
- `useSpring`：弹性动画
- `useMotion`：元素运动控制

### 6. 表单与验证

- `useForm`：表单状态管理
- `useField`：表单字段绑定
- `useVModel`：双向绑定简化

### 7. 工具类

- `useDebounce`：防抖
- `useThrottle`：节流
- `useClone`：响应式克隆
- `useDeepClone`：深拷贝
- `useId`：生成唯一 ID

# 常用函数示例

### 1. useMouse（鼠标位置）
```javascript
import { useMouse } from '@vueuse/core'
const { x, y, left, right, middle } = useMouse()
// 模板：{{ x }}, {{ y }} 实时显示鼠标坐标
```
### 2. useStorage（本地存储）
```javascript
import { useStorage } from '@vueuse/core'
// 绑定 localStorage 中的 'token'，默认值 ''
const token = useStorage('token', '')
token.value = 'xxx' // 自动同步到 localStorage
```
### 3. useWindowSize（窗口大小）
```javascript
import { useWindowSize } from '@vueuse/core'
const { width, height } = useWindowSize()
// 窗口缩放时，width/height 自动更新
```
### 4. useClickOutside（点击外部关闭）
```html
<template>
  <div ref="target" v-if="show">弹窗</div>
</template>
<script>
import { ref } from 'vue'
import { useClickOutside } from '@vueuse/core'
export default {
  setup() {
    const show = ref(true)
    const target = ref(null)
    useClickOutside(target, () => {
      show.value = false
    })
    return { show, target }
  }
}
</script>
```
### 5. useFetch（网络请求）
```javascript
import { useFetch } from '@vueuse/core'
const { data, isLoading, error } = useFetch('https://api.example.com/data').json()
// 自动请求，data 响应式，isLoading 加载状态
```
# 高级用法

### 1. 自定义组合式函数
基于 VueUse 封装业务逻辑：
```javascript
import { useStorage, useToggle } from '@vueuse/core'
export function useTheme() {
  const isDark = useStorage('dark-mode', false)
  const toggleDark = useToggle(isDark)
  return { isDark, toggleDark }
}
```
### 2. 配置默认选项
```javascript
import { setConfig } from '@vueuse/core'
setConfig({
  eventFilter: 'passive' // 全局事件过滤器
})
```
### 3. 服务端渲染（SSR）适配
多数函数自动适配 SSR，如需手动控制：
```javascript
import { useWindowSize, configurableWindow } from '@vueuse/core'
// SSR 时使用模拟 window
const { width } = useWindowSize({ window: configurableWindow })
```

# 生态与扩展
- **官方插件**：支持 Vue Router、Firebase、RxJS、Electron 等集成。
- **Nuxt 模块**：`@vueuse/nuxt` 一键集成到 Nuxt 项目。
- **组件库**：`@vueuse/components` 提供封装好的组件（如 `<UseMouse>`）。

# 总结

VueUse 是 Vue 生态的**必备工具库**，尤其适合 Vue 3 项目。它把繁琐的通用逻辑封装为简洁的响应式函数，兼顾开发效率、代码质量与性能，是中大型项目的**逻辑复用首选方案**。

原文出处：http://www.malaoshi.top/show_1GW3L260Xj5Q.html