配置

这里展示了 VueUse 中大多数函数的通用配置。

事件过滤器

从 v4.0 版本开始，我们提供了事件过滤器系统，以便更灵活地控制事件触发的时机。例如，你可以使用 throttleFilter 和 debounceFilter 来控制事件触发频率

import { debounceFilter, throttleFilter, useLocalStorage, useMouse } from '@vueuse/core'

// changes will write to localStorage with a throttled 1s
const storage = useLocalStorage('my-key', { foo: 'bar' }, { eventFilter: throttleFilter(1000) })

// mouse position will be updated after mouse idle for 100ms
const { x, y } = useMouse({ eventFilter: debounceFilter(100) })

此外，你可以使用 pausableFilter 临时暂停某些事件。

import { pausableFilter, useDeviceMotion } from '@vueuse/core'

const motionControl = pausableFilter()

const motion = useDeviceMotion({ eventFilter: motionControl.eventFilter })

motionControl.pause()
// motion updates paused

motionControl.resume()
// motion updates resumed

响应式时序

VueUse 的函数尽可能遵循 Vue 响应式系统的默认刷新时序。

对于类似 watch 的组合式函数（例如 pausableWatch、whenever、useStorage、useRefHistory），默认值为 { flush: 'pre' }。这意味着它们会缓冲无效的 effect 并在之后异步刷新。这避免了在同一个 “tick” 中发生多个状态突变时，不必要的重复调用。

与 watch 相同，VueUse 允许你通过传递 flush 选项来配置时序

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

const counter = ref(0)
const { pause, resume } = pausableWatch(
  counter,
  () => {
    // Safely access updated DOM
  },
  { flush: 'post' },
)

flush 选项 (默认值: 'pre')

• 'pre': 在同一个 “tick” 中缓冲无效的 effect，并在渲染前刷新它们
• 'post': 类似于 'pre' 的异步方式，但在组件更新后触发，因此你可以访问更新后的 DOM
• 'sync': 强制 effect 始终同步触发

注意：对于类似 computed 的组合式函数（例如 syncRef, controlledComputed），当 flush 时序可配置时，默认值更改为 { flush: 'sync' }，以使其与 Vue 中计算 ref 的工作方式保持一致。

可配置的全局依赖项

从 v4.0 版本开始，访问浏览器 API 的函数将提供选项字段，供你指定全局依赖项（例如 window、document 和 navigator）。默认情况下它将使用全局实例，因此在大多数情况下，你无需担心它。此配置在处理 iframes 和测试环境时非常有用。

import { useMouse } from '@vueuse/core'

// accessing parent context
const parentMousePos = useMouse({ window: window.parent })

const iframe = document.querySelector('#my-iframe')

// accessing child context
const childMousePos = useMouse({ window: iframe.contentWindow })

// testing
const mockWindow = { /* ... */ }

const { x, y } = useMouse({ window: mockWindow })