配置

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

配置

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

事件过滤器

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

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

// 更改将以 1 秒的节流频率写入 localStorage
const storage = useLocalStorage('my-key', { foo: 'bar' }, { eventFilter: throttleFilter(1000) })

// 鼠标位置将在鼠标闲置 100 毫秒后更新
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()
// 运动更新已暂停
motionControl.resume()
// 运动更新已恢复

响应式时间

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,
  () => {
    // 安全访问更新后的 DOM
  },
  { flush: 'post' },
)

flush 选项（默认值：'pre'）

'pre'：在同一个 “tick” 中缓冲无效的副作用并在渲染前刷新它们。
'post'：像 'pre' 一样异步，但在组件更新后触发，因此你可以访问更新后的 DOM。
'sync'：强制副作用始终同步触发。

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

可配置的全局依赖项

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

import { useMouse } from '@vueuse/core'

// 访问父级上下文
const parentMousePos = useMouse({ window: window.parent })

const iframe = document.querySelector('#my-iframe')
// 访问子级上下文
const childMousePos = useMouse({ window: iframe.contentWindow })

// 测试
const mockWindow = { /* ... */ }
const { x, y } = useMouse({ window: mockWindow })

最佳实践

组件

可组合函数的无渲染组件版本