最佳实践

🌐 Best Practice

解构

🌐 Destructuring

VueUse 中的大多数函数返回一个 refs 对象，你可以使用 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() 来解包 ref。例如：

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

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

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 函数的参数也可以接受 ref，因为 ref 是响应式的。

🌐 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

你可以将一个 ref 传入 useTitle，而不是使用返回的 ref。

🌐 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 起，我们引入了一种新的约定，用于将“响应式 getter”作为参数传递，这在响应式对象和 Reactivity Transform 中效果非常好。

🌐 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!')

最佳实践 ​

解构 ​

副作用清理 ​

反应式参数 ​

非反应式参数 ​

参考参数 ​