配置

🌐 Configurations

这些显示了 VueUse 中大多数函数的通用配置。

🌐 These show the general configurations for most of the functions in VueUse.

事件过滤器

🌐 Event Filters

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

🌐 From v4.0, we provide the Event Filters system to give the flexibility to control when events will get triggered. For example, you can use throttleFilter and debounceFilter to control the event trigger rate:

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 暂时暂停某些事件。

🌐 Moreover, you can utilize pausableFilter to temporarily pause some events.

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

反应式计时

🌐 Reactive Timing

VueUse 的函数在可能的情况下遵循 Vue 的响应式系统默认的刷新时机。

🌐 VueUse's functions follow Vue's reactivity system defaults for flush timing where possible.

对于类似 watch 的可组合项（例如 watchPausable、whenever、useStorage、useRefHistory），默认值是 { flush: 'pre' }。这意味着它们会缓冲被无效化的效果，并异步刷新它们。这可以避免在同一“时刻”发生多个状态突变时的不必要重复调用。

🌐 For watch-like composables (e.g. watchPausable, whenever, useStorage, useRefHistory) the default is { flush: 'pre' }. Which means they will buffer invalidated effects and flush them asynchronously. This avoids unnecessary duplicate invocation when there are multiple state mutations happening in the same "tick".

和使用 watch 一样，VueUse 允许你通过传递 flush 选项来配置时间：

🌐 In the same way as with watch, VueUse allows you to configure the timing by passing the flush option:

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

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

刷新选项（默认值：'pre'）

• 'pre'：在同一“帧”中使缓冲区失效的效果，并在渲染前刷新它们
• 'post'：异步类似 'pre'，但在组件更新后触发，因此你可以访问更新后的 DOM
• 'sync'：强制效果始终同步触发

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

全局依赖

🌐 Global Dependencies

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

🌐 From v4.0, functions that access the browser APIs will provide an option fields for you to specify the global dependencies (e.g. window, document and navigator). It will use the global instance by default, so for most of the time, you don't need to worry about it. This configure is useful when working with iframes and testing environments.

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

自定义调度器

🌐 Custom Scheduler

从 v14.1.0 开始，VueUse 引入了一个自定义调度器系统，允许你控制基于时间的函数在内部的更新方式。例如，可以用于与 useRafFn 对齐、减缓更新速度，或在 Web Worker 中运行。

🌐 From v14.1.0, VueUse introduces a custom scheduler system that allows you to control how time-based functions update internally. For example, to align with useRafFn, slow down updates, or run inside a Web Worker.

当一个可组合项支持计时（例如 useNow、useCountdown 等）时，你可以在其选项中传递 scheduler 函数。scheduler 接收一个回调，并负责安排其重复执行。

🌐 When a composable supports timing (such as useNow, useCountdown, etc.), you can pass a scheduler function in its options. The scheduler receives a callback and is responsible for scheduling its repeated execution.

import { useNow, useRafFn } from '@vueuse/core'

const { now, pause, resume } = useNow({
  controls: true,
  scheduler: cb => useRafFn(cb),
})