VueUse基于组合式的实用工具

安装

yarn add @vueuse/core || npm i @vueuse/core

vite.config.js
// vite.config.js
export default defineConfig({
  plugins: [
    AutoImport({
      //...
      imports: [
        '@vueuse/core', //基于组合式API的集合工具
        '@vueuse/head', //添加Meta的标签，更好的SEO
      ],
    })
  ]
})

核心函数

State

• createGlobalState - 将状态保存全局作用域中，以便跨Vue实例复用。
• createInjectionState - 创建可以注入到组件中的全局状态。
• createSharedComposable - 让一个钩子函数可用于多个Vue实例中。
• useAsyncState - 响应式获取异步状态。不会阻塞setup 函数，在promise完成后，将自动触发。
• useDebouncedRefHistory - useRefHistory 的简写，带有防抖过滤器。
• useLastChanged - 记录最后一次更改的时间戳
• useLocalStorage - 响应式的 LocalStorage
• useManualRefHistory - 调用 commit() 时，手动跟踪ref的更改历史，提供撤消和重做功能
• useRefHistory - 跟踪 ref 的更改历史，提供撤消和重做功能
• useSessionStorage - 响应式SessionStorage
• useStorage - 响应式 LocalStorage/SessionStorage
• useStorageAsync - 支持异步的响应式Storage
• useThrottledRefHistory - 带节流过滤器的 useRefHistory 的简写。

createGlobalState

将状态保存全局作用域中，以便跨Vue实例复用。

store.js
// store.js
import { ref,computed } from 'vue'
import { createGlobalState,useStorage } from '@vueuse/core'

//存储在内存中
export const useGlobalState = createGlobalState(
  () => {
    const count = ref(0)
    const doubleCount = computed(() => count.value * 2)
    const increment=()=>{
      count.value++
    }
    return { count, doubleCount, increment }
  }
)

createInjectionState

创建可以注入到组件中的全局状态。

createSharedComposable

让一个钩子函数可用于多个Vue实例中，且在不同的组件共享一个状态

import { createSharedComposable, useMouse } from '@vueuse/core'
const useSharedMouse = createSharedComposable(useMouse)
const { x, y } = useSharedMouse()

useAsyncState

响应式获取异步状态。不会阻塞setup 函数，在promise完成后，将自动触发

import axios from 'axios'
import { useAsyncState } from '@vueuse/core'

const { state, isReady, isLoading } = useAsyncState(
  axios.get('https://jsonplaceholder.typicode.com/todos/1').then(t => t.data),
  { id: null },
)

useDebouncedRefHistory

useRefHistory 的简写，带有防抖过滤器。

import { ref } from 'vue'
import { useDebouncedRefHistory } from '@vueuse/core'

const counter = ref(0)
// 以一秒的防抖器，当数据修改后，添加记录
const { history, undo, redo } = useDebouncedRefHistory(counter, { deep: true, debounce: 1000 })

useLastChanged

记录最后一次更改的时间戳

import { useLastChanged } from '@vueuse/core'
const a = ref(0)
const lastChanged = useLastChanged(a)

a.value = 1
console.log(lastChanged.value)

useLocalStorage

响应式的LocalStorage，用法同 useStorage

useManualRefHistory

调用 commit() 时，手动跟踪ref的更改历史，提供撤消和重做功能

import { ref } from 'vue'
import { useManualRefHistory } from '@vueuse/core'

const counter = ref(0)
// 跟踪ref数据的历史记录
const { history, commit, undo, redo } = useManualRefHistory(counter)

// 当调用commit的时候，才会添加记录
counter.value += 1
commit()

useRefHistory

跟踪 ref 的更改历史，提供撤消和重做功能

import { ref } from 'vue'
import { useRefHistory } from '@vueuse/core'

const counter = ref(0)
const { history, undo, redo } = useRefHistory(counter)

useSessionStorage

响应式SessionStorage，用法同 useStorage

useStorage

响应式 LocalStorage/SessionStorage

store.js
import { useStorage } from '@vueuse/core'

// 类似setItem 默认为localStorage
const state = useStorage('my-store', { hello: 'hi', greeting: 'Hello' })

// 指定类型 localStorage/sessionStorage
const state = useStorage('my-store', { hello: 'hi', greeting: 'hello' }, localStorage)

// 和createGlobalState同时使用作为全局持久存储
export const useGlobalState2 = createGlobalState(
  () => useStorage('vue-use-locale-storage', {
      name: 'Banana',
      color: 'Yellow',
      size: 'Medium',
    }),
)

useStorageAsync

支持异步的响应式Storage，用法同 useStorage

useThrottledRefHistory

带节流过滤器的 useRefHistory 的简写。

import { ref } from 'vue'
import { useThrottledRefHistory } from '@vueuse/core'

const counter = ref(0)
// 以一秒的节流器，当数据修改后，添加记录
const { history, undo, redo } = useThrottledRefHistory(counter, { deep: true, throttle: 1000 })

Element

• useActiveElement - 响应式 document.activeElement
• useDocumentVisibility - 响应式跟踪 document.visibilityState
• useDraggable - 使元素可拖拽。
• useDropZone - 创建一个可以放置文件的区域。
• useElementBounding - 让HTML元素的bounding box 响应式
• useElementSize - 元素尺寸大小响应式
• useElementVisibility - 跟踪元素在视口中的可见性。
• useIntersectionObserver - 响应式监听目标元素的可见性。
• useMouseInElement - 响应式获取鼠标相对于元素的位置
• useMutationObserver - 监听DOM树修改 MutationObserver MDN
• useResizeObserver - 监听元素内容和边框尺寸的变化。
• useWindowFocus - 使用 window.onfocus 和 window.onblur 事件响应式跟踪窗口焦点。
• useWindowScroll - 响应式获取窗口的滚动位置。
• useWindowSize - 响应式获取窗口尺寸

useActiveElement

响应式 document.activeElement

useDocumentVisibility

响应式跟踪 document.visibilityState

useDraggable

使元素可拖拽

<script setup lang="ts">
import { ref } from 'vue'
import { useDraggable } from '@vueuse/core'

const el = ref<HTMLElement | null>(null)

// `style` will be a helper computed for `left: ?px; top: ?px;`
const { x, y, style } = useDraggable(el, {
  initialValue: { x: 40, y: 40 },
})
</script>

<template>
  <div ref="el" :style="style" style="position: fixed">
    Drag me! I am at {{x}}, {{y}}
  </div>
</template>

useDropZone

创建一个可以放置文件的区域。

useElementBounding

让HTML元素的bounding box 响应式

useElementSize

元素尺寸大小响应式

useElementVisibility

跟踪元素在视口中的可见性。

useIntersectionObserver

响应式监听目标元素的可见性。

useMouseInElement

响应式获取鼠标相对于元素的位置

useMutationObserver

监听DOM树修改 MutationObserver MDN

useResizeObserver

监听元素内容和边框尺寸的变化。

useWindowFocus

使用 window.onfocus 和 window.onblur 事件响应式跟踪窗口焦点。

useWindowScroll

响应式获取窗口的滚动位置。

useWindowSize

响应式获取窗口尺寸

组件中的使用

Hello.vue
<script setup>
import { useCounterStore } from '@/stores/counter'
const counter = useCounterStore()
counter.count++
// 自动补全！ ✨
counter.$patch({ count: counter.count + 1 })
// 或使用 action 代替
counter.increment()
</script>
<template>
  <!-- 直接从 store 中访问 state -->
  <div>Current Count: {{ counter.count }}</div>
</template>

Browser

• useBluetooth - 响应式 Web Bluetooth API。提供连接低功耗蓝牙外设并与之交互的能力。
• useBreakpoints - 响应式获取视口断点
• useBroadcastChannel - 响应式 BroadcastChannel API
• useBrowserLocation - 响应式获取 Location
• useClipboard - 响应式 Clipboard API。剪贴板 API 提供了响应剪贴板命令（剪切、复制和粘贴）与异步读写系统剪贴板的能力。从权限 Permissions API。获取权限之后，才能访问剪贴板内容；如果用户没有授予权限，则不允许读取或更改剪贴板内容。
• useColorMode - 具有自动数据持久化的响应式颜色模式（深色/浅色/自定义）。
• useCssVar - 操作css变量
• useDark - 具有自动数据持久性的响应式暗黑模式。
  useEventListener - 轻松使用事件监听。在挂载时使用 addEventListener 注册，在卸载时自动使用removeEventListener 。
• useEyeDropper - 响应式 EyeDropper API
• useFavicon - 响应式 favicon
• useFileDialog - 轻松打开文件对话框。
• useFileSystemAccess - 创建和读写本地文件FileSystemAccessAPI
• useFullscreen - 响应式Fullscreen API。它添加了以全屏模式呈现特定元素（及其后代）的方法，并在不再需要时退出全屏模式。这使得可以使用用户的整个屏幕呈现所需的内容（例如在线游戏），从屏 - 幕上隐藏所有的浏览器用户界面以及其他应用，直到关闭全屏模式。
• useGamepad - provides reactive bindings for the Gamepad API
• useImage - 在浏览器中响应式加载图像，你可以等待结果显示或显示一个回退方案
• useMediaControls - audio 和 video 元素的响应式媒体控件。
• useMediaQuery - 响应式Media Query。创建 MediaQueryList 对象后，您可以查询结果或在结果更改时接收通知。
• useMemory - 响应式获取内存信息
• useObjectUrl - 响应式的用URL表示对象
• usePermission - 响应式 Permissions API。权限 API 提供的工具允许开发者在权限方面实现更好的用户体验。
• usePreferredColorScheme - 响应式 prefers-color-scheme
• usePreferredContrast - 响应式 prefers-contrast
• usePreferredDark - 响应式深色主题偏好
• usePreferredLanguages - 响应式 Navigator Languages。为web开发人员提供有关用户首选语言的信息。例如，这可能有助于根据用户的首选语言调整用户界面的语言，以提供更好的体验。
• usePreferredReducedMotion - 响应式prefers-reduced-motion
• useScreenOrientation - 响应式Screen Orientation API。它为web开发者提供有关用户当前屏幕方向的信息。
• useScreenSafeArea - 响应式 env(safe-area-inset-*)
• useScriptTag - 注入 script 标签
• useShare - 响应式 Web Share API。浏览器提供可以共享文本或文件内容的功能。
• useStyleTag - head上注入响应式 style 元素
• useTextareaAutosize - 根据内容自动更新文本区域的高度。
• useTextDirection - 响应式操作元素文本 方向
• useTitle - 响应式document title
• useUrlSearchParams - 响应式URLSearchParams
• useVibrate - 响应式 Vibration API
• useWakeLock - 响应式屏幕唤醒 API。提供了一种方法来防止设备在应用程序需要继续运行时调暗或锁定屏幕。
• useWebNotification - 响应式 Notification
• useWebWorker - 简单的 Web Workers 注册和通信。
• useWebWorkerFn - 使用 Promise 语法，在不阻塞 UI 的情况下运行复杂功能，运行在 alewin/ - useWorker。

Sensors

• onClickOutside - 监听元素外部的点击事件，对模态框和下拉菜单很有用。
• onKeyStroke - 监听键盘事件
• onLongPress - 监听一个元素的长按事件。
• onStartTyping - 当用户开始在不可编辑的元素上输入时触发。
• useBattery - 响应式 Battery Status API，更多时候被称之为 Battery API
• useDeviceMotion - 响应式 DeviceMotionEvent，为 web 开发者提供了关于设备的位置和方向的改变速度的信息。
• useDeviceOrientation - 响应式DeviceOrientationEvent。提供给网页开发者当设备在浏览页面时物理旋转的信息。
• useDevicePixelRatio - 响应式跟踪window.devicePixelRatio
• useDevicesList - 列出可用的输入输出设备的响应式列表
• useDisplayMedia - 响应式 mediaDevices.getDisplayMedia流
• useElementByPoint - 以坐标点响应式操作元素。
• useElementHover - 响应元素的悬停状态
• useFocus - 响应式跟踪或设置 DOM 元素的焦点状态。状态变化以反映目标元素是否是焦点元素，从外部设置响应值为 true 和 false，将分别触发 focus 和 blur 事件。
• useFocusWithin - 用于跟踪元素或其后代之一是否获取了焦点的响应式工具。匹配 :focus-within 伪类的行为。一个常见的用例是在表单元素上查看整个表单是否获取了焦点。
• useFps - 响应式 FPS（每秒帧数）。
• useGeolocation - 响应式 Geolocation API。允许用户向 web 应用程序提供他们的位置。出于隐私考虑，报告地理位置前会先请求用户许可。
• useIdle - 跟踪用户是否处于非活动状态。
• useInfiniteScroll - 元素无限滚动。
• useKeyModifier - 响应式 键盘修饰键状态。跟踪任何修饰键的状态 - 请参阅浏览器兼容性说明。
• useMagicKeys - 响应式按下状态，支持组合键。
• useMouse - 响应式获取鼠标位置
• useMousePressed - 响应式鼠标按下状态。由目标元素的 mousedown touchstart 事件触发，并由window上的 mouseup mouseleave touchend touchcancel 事件释放。
• useNavigatorLanguage - 响应式 navigator.language。
• useNetwork - 响应式 Network status。网络状态 API 可以获取到系统的网络连接信息，比如说连接方式是 WiFi 还是蜂窝。应用程序可以根据此信息为用户展现不同清晰度的内容。该 API 是由 NetworkInformation 接口和 Navigator 接口上新增的一个 connection 属性组成的。
• useOnline - 响应式在线状态，useNetwork的包装器
• usePageLeave - 响应式获取鼠标是否离开页面。
• useParallax - 轻松创建视差效果。如果不支持旋转，它会使用 useDeviceOrientation 并回退到 useMouse
• usePointer - 响应式 指针状态
• usePointerLock - 响应式 指针锁定
• usePointerSwipe - 基于PointerEvents的响应式滑动检测
• useScroll - 响应式获取滚动位置和状态。
• useScrollLock - 锁定元素的滚动。
• useSpeechRecognition - 响应式SpeechRecognition。
• useSpeechSynthesis - 响应式 SpeechSynthesis
• useSwipe - 基于 TouchEvents的响应式滑动检测
• useTextSelection - 基于 Window.getSelection 响应 - 式跟踪用户文本选择
• useUserMedia - 响应式 mediaDevices.getUserMedia流

Network

• useEventSource - 使用EventSource 或 Server-Sent-Events 实例会对 HTTP 服务开启一个持久化的连接，以 text/event-stream 格式发送事件。
• useFetch - 响应式 Fetch API，提供中止请求、在请求被触发之前拦截请求、在 url 更改时自动重新获取请求以及使用预定义选项创建您自己的 useFetch。
• useWebSocket - 响应式 WebSocket

Animation

• useInterval - 每隔一段时间响应式增加计数
• useIntervalFn - 带控件的 setInterval 包装器
• useNow - 响应式获取当前 Date 实例。
• useRafFn - 在每个 requestAnimationFrame 上调用函数。可控制暂停和恢复。
• useTimeout - 在给定时间后更新值。
• useTimeoutFn - 带控件的 setTimeout 包装器。
• useTimestamp - 响应式获取当前时间戳
• useTransition - 值之间的过度

Component

Watch

Reactivity

Array

Time

Utilities