配置

这些显示了 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' }。这意味着它们将缓冲无效化的效果并异步刷新它们。当在同一个“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”中缓冲无效化的效果，并在渲染前刷新它们。
• 'post'：与“pre”类似，但组件更新后触发，因此您可以访问更新后的 DOM。
• 'sync'：强制效果始终同步触发。

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

可配置的全局依赖项

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

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 })