最佳实践

¥Best Practice

解构

¥Destructuring

VueUse 中的大多数函数都会返回一个引用对象，你可以使用 ES6 的对象解构 语法来获取你需要的内容。例如：

¥Most of the functions in VueUse return an object of refs that you can use ES6's object destructure syntax on to take what you need. For example:

import { useMouse } from '@vueuse/core'

// "x" and "y" are refs
const { x, y } = useMouse()

console.log(x.value)

const mouse = useMouse()

console.log(mouse.x.value)

如果你更喜欢将它们用作对象属性，则可以使用 reactive() 来解开引用。例如：

¥If you prefer to use them as object properties, you can unwrap the refs by using reactive(). For example:

import { reactive } from 'vue'
import { useMouse } from '@vueuse/core'

const mouse = reactive(useMouse())

// "x" and "y" will be auto unwrapped, no `.value` needed
console.log(mouse.x)

副作用清理

¥Side-effect Clean Up

与 Vue 的 watch 和 computed 类似，组件卸载时会被处理，VueUse 的函数也会自动清除副作用。

¥Similar to Vue's watch and computed that will be disposed when the component is unmounted, VueUse's functions also clean up the side-effects automatically.

例如，当组件被卸载时，useEventListener 将调用 removeEventListener。

¥For example, useEventListener will call removeEventListener when the component is unmounted.

// will cleanup automatically
useEventListener('mousemove', () => {})

所有 VueUse 函数都遵循此约定。

¥All VueUse functions follow this convention.

为了手动处理副作用，某些函数会返回一个停止处理程序，就像 watch 函数一样。例如：

¥To manually dispose the side-effects, some functions return a stop handler just like the watch function. For example:

const stop = useEventListener('mousemove', () => {})

// ...

// unregister the event listener manually
stop()

并非所有函数都会返回 stop 处理程序，因此更通用的解决方案是使用 Vue 中的 effectScope API。

¥Not all functions return a stop handler so a more general solution is to use the effectScope API from Vue.

import { effectScope } from 'vue'

const scope = effectScope()

scope.run(() => {
  // ...

  useEventListener('mousemove', () => {})
  onClickOutside(el, () => {})
  watch(source, () => {})
})

// all composables called inside `scope.run` will be disposed
scope.stop()

你可以在 这个 RFC 中了解更多关于 effectScope 的信息。

¥You can learn more about effectScope in this RFC.

反应式参数

¥Reactive Arguments

在 Vue 中，我们使用 setup() 函数来构造数据和逻辑之间的 "连接"。为了使其灵活，大多数 VueUse 函数还接受参数的 refs，因为 refs 是反应式的。

¥In Vue, we use the setup() function to construct the "connections" between data and logic. To make it flexible, most of the VueUse functions also accept refs for the arguments because refs are reactive.

以 useTitle 为例：

¥Take useTitle as an example:

非反应式参数

¥Non-reactive Argument

useTitle 可组合项可帮助你获取和设置当前页面的 document.title 属性。

¥The useTitle composable helps you get and set the current page's document.title property.

const isDark = useDark()
const title = useTitle('Hello')

console.log(document.title) // "Hello"

watch(isDark, () => {
  title.value = isDark.value ? '🌙 Good evening!' : '☀️ Good morning!'
})

参考参数

¥Ref Argument

你可以将引用传递到 useTitle 而不是使用返回的引用。

¥You can pass a ref into useTitle instead of using the returned ref.

const isDark = useDark()
const title = computed(() => isDark.value ? '🌙 Good evening!' : '☀️ Good morning!')

useTitle(title)

反应式获取器参数

¥Reactive Getter Argument

自 VueUse 9.0 以来，我们引入了一种新的约定，用于传递 "反应式获取器" 作为参数，这对于反应式对象和 反应式性变换 非常有效。

¥Since VueUse 9.0, we introduced a new convention for passing a "Reactive Getter" as the argument, which works great with reactive objects and Reactivity Transform.

const isDark = useDark()

useTitle(() => isDark.value ? '🌙 Good evening!' : '☀️ Good morning!')