配置

¥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 类可组合项（例如 pausableWatch、whenever、useStorage useRefHistory ，默认值为 { flush: 'pre' }。这意味着它们将缓冲无效的效果并异步刷新它们。当同一个 "tick" 中发生多个状态突变时，这可以避免不必要的重复调用。

¥For watch-like composables (e.g. pausableWatch, 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 { ref } from 'vue'
import { pausableWatch } from '@vueuse/core'

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

冲洗选项（默认值：'pre'）

¥flush option (default: 'pre')

• 'pre'：缓冲同一个 'tick' 中无效的效果并在渲染前刷新它们

  ¥'pre': buffers invalidated effects in the same 'tick' and flushes them before rendering

• 'post'：像 'pre' 一样异步，但在组件更新后触发，以便你可以访问更新的 DOM

  ¥'post': async like 'pre' but fires after component updates so you can access the updated DOM

• 'sync'：强制效果始终同步触发

  ¥'sync': forces the effect to always trigger synchronously

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

¥Note: For computed-like composables (e.g. syncRef controlledComputed), when flush timing is configurable, the default is changed to { flush: 'sync' } to align them with the way computed refs works in Vue.

可配置的全局依赖

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