VueUse工具库 常用api

简介：

 VueUse不是Vue.use， VueUse 为 Vue 2和Vue3 服务的一套Vue Composition API的常用工具集，，它提供了一系列的 hooks 和工具函数，帮助我们更方便地使用 Vue Composition API。

通俗的来说，这就是一个工具函数包支持了更好的逻辑分离，它可以帮助你快速实现一些常见的功能，免得你自己去写，解决重复的工作内容。以及进行了机遇 Composition API 的封装。

安装：

npm install -D @vueuse/core

或者
pnpm add @vueuse/core

State

createGlobalState

提供了全局的状态管理，类似于简化版的pinia

createInjectionState

扩展了vue默认的provide和inject功能，可以更方便的对数据进行注入和修改

createSharedComposable

将一个函数在多个vue实例之间共享，从而减少对事件的监听。官方的示例便是将CompA.vue中对于鼠标移动的监听方法共享给CompB.vue，在CompB.vue中不会注册新的鼠标移动监听事件。

useAsyncState

异步更新状态，不会阻塞页面渲染，而是会在异步调用完成后更新数据。
解构出来的数据是响应式的，在js中获取值时要加.value。

useRefHistory

提供了历史记录的功能，通过history查看历史记录的数组，通过undo和redo来实现撤销和重做功能。

参数

deep

对于object类型的数据，需要提供 deep: true 选项来实现监听，并且只能使用 ref 实现响应式而不能使用 reactive。

dump

默认使用 JSON.parse(JSON.stringify(x)) 进行拷贝，通过传入参数 dump 可自定义拷贝方法。

parse

通过传入parse参数可以自定义反序列化的方法，如果不需要将序列化的对象字符串再反序列化，这将非常有用。

capacity

用于设置历史记录的容量

sync

将数据更改方式变为同步
参考commit，相当于每进行一次修改就commit一次，而不是在一次绘tick中只保存一次

方法

clear

清空历史记录

commit

主动添加一条历史记录
vue对于一次tick中多次数据变更，会缓存结果防止多次刷新页面，从而只会保存最后一次的状态
通过commit可以保存过程中的变更
有可能出现重复的记录

batch

在使用sync时，由于每次修改都会保存一次历史记录，可以使用batch将多次修改合并为一次历史记录
同时，batch也可以解决数组的splice方法会产生三条历史记录的问题，这是因为splice会产生三次原子操作

useManualRefHistory

跟useRefHistory类似，但必须手动调用commit方法才会生成快照

useDebouncedRefHistory

useRefHistory的防抖方法，可以指定debounce参数表示多长时间后才触发保存历史记录的操作

useThrottledRefHistory

useRefHistory的节流方法，通过指定hrottle参数控制多长时间内只执行一次

useLastChanged

记录某个变量上次修改的时间，精确到毫秒

useStorage

用于数据存储，默认采用localStorage。我们可以使用useStorage来实现我们的localStorage功能。

返回一个响应式的数据，通过设置 .value=null 可以删除存储的数据

useStorage()将要用于引用的键名作为第一个参数传递，将要保存的值作为第二个参数传递。

值的保存、获取、删除

localStorage设置setItem()来保存值，用getItem()来获取值，用removeItem来删除值如下：

<script setup >
   import {ref} from "vue";
 
   const counter = ref('消息')
   //保存值
   localStorage.setItem('counter',counter.value)
   //获取值
   const data = localStorage.getItem('counter')
   console.log('data',data)
   //删除值
   localStorage.removeItem('counter')
</script>

而useStorage()只需要一个就可以进行值的保存和获取，如下，用法：

const storedValue = useStorage('key', value)

例子

 const msg = ref('你好')
   //保存值
   useStorage('msg',msg.value)
   //获取值
   const msgData = useStorage('msg')
   console.log('msgData',msgData.value)
   //删除
   const clear = () => {
     msg.value = null
   }

参数

以下参数均作为options传入第四个参数中，需要显式指定第三个参数是localStorage还是sessionStorage，或者指定undefined

mergeDefaults

当键名存在时，该方法不会合并对象，也意味着提供的默认对象中之前不存在的键值不会保存到存储中去。
可以通过指定该参数为true合并对象，将原本不存在的键名保存到数据中。
该参数也可以是一个函数，将调用自定义的合并方法合并对象。

serializer -useStorage()自定义序列化

用于自定义序列化和反序列化的方法
可以传入内置的方法，例如StorageSerializers.object
当useStorage的默认值是null时，请务必指定该参数防止出错

默认情况下，useStorage将根据提供的默认值的数据类型智能地使用相应的序列化程序。例如，JSON.stringify/JSON.parse将用于对象，Number.toString/parseFloat用于数字等

import { useStorage } from '@vueuse/core'
 
useStorage(
  'key',
  {},
  undefined,
  {
    serializer: {
      read: (v: any) => v ? JSON.parse(v) : null,
      write: (v: any) => JSON.stringify(v),
    },
  },
)

useLocalStorage

useStorage的简化写法，使用localStorage。

useSessionStorage

useStorage的简化写法，使用localStorage。

useStorageAsync

useStorage的异步方法

---

Elements

useActiveElement

获取当前激活的元素

useDocumentVisibility

当前窗口是否显示，取值为 visible 和 hidden

useDraggable

获取可拖拽的位置，对应的元素必须指定 position: fixed

useDropZone

将元素变为可拖拽文件区域，当文件被拖拽到元素上时，会调用方法，方法的参数是文件信息

useElementBounding

获取元素的边界信息，包括x,y,width,height,top,left,right,bottom

useElementSize

获取元素的大小

useElementVisibility

判断元素是否在视口中显示

useIntersectionObserver

在局部滚动中，判断元素是否显示

useMouseInElement

判断鼠标是否在当前元素中

useMutationObserver

监听DOM元素的修改，包括style，class等

useResizeObserver

监听元素的大小变化

useWindowFocus

判断当前页面是否获取了焦点，当点击窗口外部时，会失去焦点

useWindowScroll

监听窗口滚动

useWindowSize

监听窗口大小变化

---

Browser

useBluetooth

调用蓝牙API

useBreakpoints

判断当前窗口的大小节点，默认使用Tailwind提供的规则，可以自定义。
提供了一系列的方法用以判断各种不同的大小情况。

useBroadcastChannel

频道广播，用于向同一域名下的其他页面广播内容。

useBrowserLocation

获取页面地址信息

useClipboard

提供了对剪贴板的支持

usePreferredColorScheme

查询 prefers-color-scheme，确定明暗主题

usePreferredDark

判断是否启用了暗色主题

useDark

提供了对明暗主题的支持。
使用usePreferredDark获取主题类型，使用useStorage进行持久化，默认的键为：vueuse-color-scheme
当启用暗色模式时，默认会在html上添加dark类名。可以通过自定义对象或者回调函数的形式修改这一设置。

useColorMode

颜色模式，除了dark和light以外，可以自定义其他的模式

useCssVar

获取元素的css变量

useEventListener

在mounted时调用addEventListener，在unmounted时调用removeEventListener。

useEyeDropper

使用滴管工具，可以点击获取选择像素的颜色。

useFavicon

用于改变网站图标

useFileDialog

打开文件选择窗口

useFileSystemAccess

提供了对读写本地文件的支持

useFullscreen

浏览器全屏

useGamepad

响应游戏手柄

useImage

判断图片是否加载完成

useMediaControls

音视频播放控制

useMediaQuery

获取媒体查询的值，可以自己指定查询内容

useMemory

内存信息查询

useObjectUrl

为浏览器本地选择的文件生成一个url

usePermission

查询设备权限

usePreferredContrast

查询对比度

usePreferredLanguages

查询语言首选项

usePreferredReducedMotion

浏览器是否开启了减少动画功能

useScreenOrientation

屏幕方向

useScreenSafeArea

屏幕安全区间，多用于不规则的移动设备

useScriptTag

加载脚本，可定义在脚本加载完成后执行的操作
可以指定manual: true手动控制加载

useShare

调用浏览器自带的分享功能

useStyleTag

向head中动态插入样式

useTextareaAutosize

提供了自动控制大小的多行文本框支持

useTextDirection

控制文字方向

useTitle

控制网页标题

useUrlSearchParams

获取当前路由的参数

useVibrate

设备震动

useWakeLock

锁定屏幕，防止息屏

useWebNotification

显示系统通知

useWebWorker

useWebWorkerFn

提供了对WebWorker的支持

---

Sensors

onClickOutside

监听元素外点击

onKeyStroke

监听键盘敲击

onLongPress

监听鼠标长按

onStartTyping

在不可以输入内容的元素上敲击键盘时，将焦点定位到某元素

useBattery

监听电池的电量信息

useDeviceMotion

监听设备的位置变化

useDeviceOrientation

监听设备方向

useDevicePixelRatio

监听屏幕放大

useDevicesList

设备列表：耳机、麦克、摄像头

useDisplayMedia

媒体播放

useElementByPoint

根据鼠标指向选定容器

useElementHover

根据hover选定容器

useFocus

提供了对焦点状态的判断，以及选择焦点的功能

useFocusWithin

判断焦点是属于某个元素的子元素

useFps

获取刷新率

useGeolocation

获取地理位置

useIdle

判断用户是否处于活动状态，这仅可以判断鼠标是否有操作

useInfiniteScroll

无限滚动

useKeyModifier

判断某些键盘按键是否按下

useMagicKeys

判断某些键盘按键是否是按下状态，支持组合

useMouse

监听鼠标当前位置

<template>
  <div>
    <p>X: {{ mouse.x }}, Y: {{ mouse.y }}</p>
  </div>
</template>
 
<script>
import { useMouse } from '@vueuse/core';
 
export default {
  setup() {
    const mouse = useMouse();
 
    return {
      mouse,
    };
  },
};
</script>

useMousePressed

监听鼠标按键，支持区域判断

useNavigatorLanguage

获取当前浏览器语言

useNetwork

获取网络状态

useOnline

获取网络是否联通的状态

usePageLeave

判断鼠标是否离开了当前页面

useParallax

创建视差效果

usePointer

获取鼠标状态

usePointerSwipe

监听鼠标滑动

useScroll

监听滚动条

useScrollLock

监听滚动条是否锁定

useSpeechRecognition

语音识别

useSpeechSynthesis

语音合成，即文字转语音

useSwipe

触摸屏滑动

useTextSelection

文字选择

useUserMedia

多媒体播放

---

Network

useEventSource

打开到http服务器的持久连接，用于使用文本或者流的形式发送数据

useFetch

对fetch功能的封装，提供了取消请求，监听url变化自动请求等功能

useWebSocket

对websocket功能的封装

---

Animation

useInterval

提供了一个根据指定执行间隔自增的计数器

useIntervalFn

对setInterval方法的封装

useNow

响应性的获取当前时间

useRafFn

根据屏幕刷新间隔执行方法，提供了暂停和继续的功能

useTimeout

在指定时间结束以后，修改ready属性的值

useTimeoutFn

对setTimeout方法的封装，提供了开始和停止的功能

useTimestamp

动态的获取当前的时间戳

useTransition

用于处理状态过渡，可以在几种不同的过渡之间切换

---

Component

computedInject

对计算和注入属性的封装，使得可以直接计算注入的属性

templateRef

对ref绑定元素的简写

tryOnBeforeMount

如果在组件内部，会在onBeforeMount生命周期调用，否则直接调用该函数

tryOnBeforeUnmount

如果在组件内部，会在onBeforeUnmount生命周期调用，否则直接调用该函数

tryOnMounted

如果在组件内部，会在onBeforeMounted生命周期调用，否则直接调用该函数

tryOnScopeDispose

如果在组件内部，会在onBeforeMounted生命周期调用，否则直接调用该函数

tryOnScopeDispose

当在一个作用域内部时，会在onScopeDispose调用，否则什么都不做

tryOnUnmounted

如果在组件内部，会在onUnmounted生命周期调用，否则直接调用该函数

unrefElement

取得ref真实的dom

useCurrentElement

取得当前组件的元素

useMounted

判断组件是否加载完成

useTemplateRefsList

通过循环的方式，取得一系列的ref元素

useVirtualList

创建虚拟列表

useVModel

修改props的属性的简写

在使用useVModel之前，实现双向数据绑定
父组件传一个变量值，用v-model去传，v-model="isChecked"默认传的是modelValue，如果想要改变传的变量名，可以用在v-model后面加:变量名—v-model:变量名="isChecked"
在子组件可以使用props来接收父组件传过来的值，且默认定义为modelValue（如果父组件定义了变量名，这里要用父组件定义的变量名接收变量），然后在watch来侦听数据，将接收过来的值 props.变量名 赋给子组件定义的变量，当这个变量发生改变的时候，emit('update:变量名', newVal)

// 使用useVModel实现双向数据绑定v-model指令

使用props接收modelValue
使用useVModel来包装props中的modelValue属性数据
再使用checked.value就是使用父组件数据
再使用checked.value = ‘数据’ 赋值，自动触发emit(‘update:modelvalue’, ‘数据’)

import { useVModel } from '@vueuse/core'
export default {
  name: 'XtxCheckbox',
  props: {
    checkedVal: {
      type: Boolean,
      default: false
    }
  },
  setup (props, { emit }) {
    //  useVModel用法
    const checked = useVModel(props, 'checkedVal', emit)
    const changeChecked = () => {
      checked.value = !checked.value
    }
    return { checked, changeChecked }
  }
}

useVModels

允许批量修改props属性的简写

---

Watch

until

返回一个Promise，直到达成条件才触发，并且是一次性的

watchArray

对watch功能的扩展，支持数组

watchAtMost

监听一个变量的变动次数，直到达到某个次数触发，并且之后不再监听

watchDebounced

提供了watch防抖的功能

watchIgnorable

提供了ignoreUpdates，可以忽略监听某一次变动

watchOnce

只监听一次变化

watchPausable

可以暂停和重启的watch

watchThrottled

提供了watch的节流功能

watchTriggerable

可以手动触发watch中的函数

watchWithFilter

拥有过滤器的watch，可以提供节流、防抖等功能

whenever

当观察的值为真时，才触发

---

Reactivity

computedAsync

异步返回值的计算操作

computedEager

当一个值不经常变化时，使用它代替computed，可以减少计算和渲染的次数
通常用于布尔值

computedWithControl

显式定义computed的依赖，相当于watch一个值，然后计算

extendRef

在ref包裹的数据上，添加其他的键值对，并且可以实现响应式

reactify

将一个函数变成响应式的函数，函数的返回值也是响应式的，类似于computed

reactifyObject

将一个对象变成响应式的，在调用对象的方法获取响应式对象值时，不需要加.value

reactiveComputed

computed默认返回ref方法实现的响应式对象，使用reactiveComputed可以变成reactive的响应式对象

reactiveOmit

从响应式对象中去除某些属性

reactivePick

与上面的方法相反，从响应式对象中取出某些属性形成一个新的响应式对象

refAutoReset

一个响应式对象，在一段时间后，它将会变回默认值

refDebounced

防抖的响应式对象，在其监听的值变化一段时间后才触发变化

refDefault

为响应式对象提供默认值，当响应式对象返回的值为undefined时，会使用默认值

refThrottled

节流的响应式对象

refWithControl

细粒度的响应式控制，当使用set false时，值本身会变化，但不会触发诸如computed之类的监听

resolveRef

将提供的值变成响应式的，支持多种参数

resolveUnref

取得各种响应式类型的返回值

syncRef

同步两个响应式对象的值

syncRefs

一个响应式的值根据另一个关联的响应式的值变化而变化，但其本身的变化却不会触发关联对象的变化

toReactive

将ref变成reactive

toRefs

使响应式对象解构出来的值仍然时响应式的

---

Array

useArrayEvery

响应式的every，当数组变化时，结果也会变化

useArrayFilter

响应式的filter，当数组变化时，结果也会变化

useArrayFind

响应式的find，当数组变化时，结果也会变化

useArrayFindIndex

响应式的findIndex，当数组变化时，结果也会变化

useArrayJoin

响应式的join，当数组变化时，结果也会变化

useArrayMap

响应式的map，当数组变化时，结果也会变化

useArrayReduce

响应式的reduce，当数组变化时，结果也会变化

useArraySome

响应式的some，当数组变化时，结果也会变化

---

Time

useDateFormat

格式化时间

useTimeAgo

格式化时间差

---

Utilities

useCounter

默认的计数器，提供了加、减、设置、重置功能。可以自定义初始值及最大最小值，加减可以设置步长。
set方法可以无视最大最小值的限制。

useToggle

提供了对响应式Boolean类型的变量支持。
默认返回一个value和一个toggle方法，如果提供一个ref参数，则仅返回一个toggle方法。

<template>
  <div>
    <button @click="toggle">Toggle</button>
    <p>{{ isToggled }}</p>
  </div>
</template>
 
<script>
import { useToggle } from '@vueuse/core';
 
export default {
  setup() {
    const { isToggled, toggle } = useToggle(false);
 
    return {
      isToggled,
      toggle,
    };
  },
};
</script>

createEventHook

为函数创建事件钩子

createUnrefFn

创建一个函数，可以接收响应式参数

get

ref.value的简写

isDefined

用来判断一个响应式的值是否时undefined

makeDestructurable

可以同时使用对象解构和数组解构的方式处理数据

set

ref.value = x 的简写

useAsyncQueue

按顺序执行一系列异步方法，并将前一个方法的结果作为下一个方法的参数，最终返回所有的执行结果

useBase64

响应式的Base64方法

useCached

用自定义比较器缓存一个引用

useCloned

拷贝一个对象的值，可以使用sync方法恢复到原对象的状态

useConfirmDialog

为一系列的确认对话框创建钩子

useCycleList

创建一个循环的列表

useDebounceFn

方法防抖

useEventBus

一个简单的发布订阅模式

useMemoize

缓存函数的执行结果，可以缓存异步函数
注意内存泄漏

useOffsetPagination

根据传入的数据总数和单页条数生成分页信息

useStepper

对多步骤的表单提供支持

useSupported

判断是否支持某些特性

useThrottleFn

函数节流

promiseTimeout

提供了类似于sleep的异步方法

useTimeoutPoll

在函数执行完之后再调用该函数

useToNumber

将响应式字符串转换为响应式的数字

useToString

转换为响应式的字符串