Vue 3 组合式 API 实战教程：docs-next-zh-cn 中的 5 个实用案例解析

【免费下载链接】docs-next-zh-cn :cn: Chinese translation for v3.vuejs.org 项目地址: https://gitcode.com/gh_mirrors/do/docs-next-zh-cn

Vue 3 组合式 API 是 Vue.js 框架的重大升级，它提供了更灵活、更强大的代码组织方式，帮助开发者构建可维护性更高的应用。本文将通过 docs-next-zh-cn 项目中的 5 个实用案例，详细解析 Vue 3 组合式 API 的核心用法和最佳实践，让你快速掌握这一强大工具。

1. setup 函数：组合式 API 的入口点

setup 函数是组合式 API 的入口，它在组件创建之前、props 解析之后执行。通过 setup 函数，我们可以定义响应式数据、方法，并将它们暴露给模板使用。

<template>
  <div>{{ readersNumber }} {{ book.title }}</div>
</template>

<script>
import { ref, reactive } from 'vue'

export default {
  setup() {
    const readersNumber = ref(0)
    const book = reactive({ title: 'Vue 3 Guide' })

    // 暴露给模板
    return {
      readersNumber,
      book
    }
  }
}
</script>

在这个案例中，我们使用 ref 创建了一个响应式的 readersNumber 变量，使用 reactive 创建了一个响应式的 book 对象。然后将它们返回，使模板能够访问这些数据。

setup 函数还可以接收两个参数：props 和 context。props 是组件接收的属性，context 包含了 attrs、slots、emit 等对象，用于与父组件通信。

详细内容可以参考官方文档：src/api/composition-api.md

2. 生命周期钩子：掌握组件的生命周期

组合式 API 提供了一系列 onX 函数来注册生命周期钩子，让我们能够在组件的不同阶段执行特定的逻辑。

import { onMounted, onUpdated, onUnmounted } from 'vue'

const MyComponent = {
  setup() {
    onMounted(() => {
      console.log('mounted!')
    })
    onUpdated(() => {
      console.log('updated!')
    })
    onUnmounted(() => {
      console.log('unmounted!')
    })
  }
}

这些生命周期钩子注册函数只能在 setup() 期间同步使用。它们与选项式 API 的生命周期选项有对应关系，例如 onMounted 对应 mounted 选项。

通过合理使用生命周期钩子，我们可以更好地控制组件的行为，例如在组件挂载后获取数据，在组件更新后执行 DOM 操作，在组件卸载前清理资源等。

详细内容可以参考官方文档：src/api/composition-api.md

3. 模板引用：访问 DOM 元素和组件实例

在组合式 API 中，响应式引用和模板引用的概念是统一的。我们可以通过声明 ref 并从 setup() 返回，来获得对模板内元素或组件实例的引用。

<template>
  <div ref="root">This is a root element</div>
</template>

<script>
import { ref, onMounted } from 'vue'

export default {
  setup() {
    const root = ref(null)

    onMounted(() => {
      // DOM 元素将在初始渲染后分配给 ref
      console.log(root.value) // <div>This is a root element</div>
    })

    return {
      root
    }
  }
}
</script>

在这个例子中，我们创建了一个名为 root 的 ref，并将其绑定到 div 元素的 ref 属性上。在 onMounted 钩子中，我们可以访问到这个 DOM 元素。

对于 v-for 中的元素，我们可以使用函数引用来自定义处理：

<template>
  <div v-for="(item, i) in list" :ref="el => { if (el) divs[i] = el }">
    {{ item }}
  </div>
</template>

<script>
import { ref, reactive, onBeforeUpdate } from 'vue'

export default {
  setup() {
    const list = reactive([1, 2, 3])
    const divs = ref([])

    // 确保在每次更新之前重置ref
    onBeforeUpdate(() => {
      divs.value = []
    })

    return {
      list,
      divs
    }
  }
}
</script>

详细内容可以参考官方文档：src/guide/composition-api-template-refs.md

4. Provide / Inject：组件间通信的高级方式

Provide / Inject 是一种组件间通信的方式，它允许祖先组件向其所有后代组件注入依赖，而不需要通过 props 一级一级传递。

在组合式 API 中，我们可以使用 provide 和 inject 函数来实现这一功能。

<!-- src/components/MyMap.vue -->
<template>
  <MyMarker />
</template>

<script>
import { provide, reactive, ref } from 'vue'
import MyMarker from './MyMarker.vue'

export default {
  components: {
    MyMarker
  },
  setup() {
    const location = ref('North Pole')
    const geolocation = reactive({
      longitude: 90,
      latitude: 135
    })

    provide('location', location)
    provide('geolocation', geolocation)
  }
}
</script>

<!-- src/components/MyMarker.vue -->
<script>
import { inject } from 'vue'

export default {
  setup() {
    const userLocation = inject('location', 'The Universe')
    const userGeolocation = inject('geolocation')

    return {
      userLocation,
      userGeolocation
    }
  }
}
</script>

为了增加 provide 值和 inject 值之间的响应性，我们可以使用 ref 或 reactive。同时，为了确保数据的可控性，建议对提供者的 property 使用 readonly，并提供修改数据的方法。

详细内容可以参考官方文档：src/guide/composition-api-provide-inject.md

5. 组合式函数：复用组件逻辑

组合式函数是组合式 API 的核心特性之一，它允许我们将组件逻辑提取到可重用的函数中。

例如，我们可以创建一个 useMousePosition 函数来获取鼠标位置：

import { ref, onMounted, onUnmounted } from 'vue'

export function useMousePosition() {
  const x = ref(0)
  const y = ref(0)

  function update(e) {
    x.value = e.pageX
    y.value = e.pageY
  }

  onMounted(() => {
    window.addEventListener('mousemove', update)
  })

  onUnmounted(() => {
    window.removeEventListener('mousemove', update)
  })

  return { x, y }
}

然后在组件中使用它：

<template>
  <div>Mouse position: {{ x }}, {{ y }}</div>
</template>

<script>
import { useMousePosition } from './useMousePosition'

export default {
  setup() {
    const { x, y } = useMousePosition()
    return { x, y }
  }
}
</script>

通过组合式函数，我们可以将复杂的组件逻辑分解为更小的、可重用的部分，提高代码的可维护性和复用性。

总结

Vue 3 组合式 API 为我们提供了更灵活、更强大的代码组织方式。通过 setup 函数、生命周期钩子、模板引用、Provide / Inject 和组合式函数等特性，我们可以构建出更可维护、更可复用的 Vue 应用。

希望本文介绍的 5 个实用案例能够帮助你更好地理解和应用 Vue 3 组合式 API。如果你想深入学习，可以查阅 docs-next-zh-cn 项目中的相关文档。

要开始使用这个项目，你可以通过以下命令克隆仓库：

git clone https://gitcode.com/gh_mirrors/do/docs-next-zh-cn

祝你在 Vue 3 的学习和实践中取得进步！ 🚀

【免费下载链接】docs-next-zh-cn :cn: Chinese translation for v3.vuejs.org 项目地址: https://gitcode.com/gh_mirrors/do/docs-next-zh-cn