Vue 3 Composition API 实战：从入门到精通的完整指南-是一个基于内容分享折腾笔记的网站序与诗

Vue 3 带来的 Composition API 为开发者提供了一种全新的组织组件逻辑的方式。相比于传统的 Options API，Composition API 拥有更好的逻辑复用能力、更灵活的代码组织方式，以及更友好的 TypeScript 支持。今天我们就来深入探索 Vue 3 Composition API 的核心用法与最佳实践。

什么是 Composition API？

Composition API 是 Vue 3 引入的一套新的 API 集合，它允许你用函数的方式组织组件的逻辑。你可以将相关功能的代码放在一起，而不是像 Options API 那样将代码分散到 data、methods、computed、watch 等不同选项中。

这种组织方式在处理复杂组件时尤为强大，它让你能够更容易地提取和复用逻辑片段（Composables）。

setup 函数：Composition API 的入口

Composition API 的核心是 setup 函数。它在组件实例创建之前执行，在 setup 中，你可以使用响应式 API、生命周期钩子，以及访问组件的属性。

import { ref, onMounted, computed } from "vue";

export default {
  setup() {
    const count = ref(0);
    const doubled = computed(() => count.value * 2);

    const increment = () => {
      count.value++;
    };

    onMounted(() => {
      console.log("组件已挂载，初始计数：", count.value);
    });

    return { count, doubled, increment };
  },
};

注意，在 setup 中访问响应式数据时，ref 创建的值需要通过 .value 来访问其内部的值，但在模板中会自动解包，无需使用 .value。

响应式系统：ref 与 reactive

Vue 3 提供了两个主要的响应式 API：ref 和 reactive。

ref — 基础类型的响应式

ref 用于创建基础类型（字符串、数字、布尔等）的响应式引用：

import { ref } from "vue";

const name = ref("张三");
const age = ref(28);
const isActive = ref(true);

// 修改值需要通过 .value
name.value = "李四";
console.log(name.value); // 输出：李四

reactive — 对象的响应式

reactive 用于创建深层响应式对象，适合批量管理相关状态：

import { reactive } from "vue";

const user = reactive({
  name: "张三",
  age: 28,
  address: {
    city: "北京",
    district: "朝阳区",
  },
});

// 直接修改，无需 .value
user.age = 30;
user.address.city = "上海"; // 深层响应式自动追踪

最佳实践：优先使用 ref，因为它让数据流更加清晰可见。当你需要组合多个相关值时，可以使用 reactive。

计算属性与监听器

计算属性和监听器在 Composition API 中的使用方式与 Options API 类似，但更加灵活：

import { ref, computed, watch, watchEffect } from "vue";

const firstName = ref("张");
const lastName = ref("三");

// 计算属性
const fullName = computed(() => {
  return firstName.value + lastName.value;
});

// watch — 监听特定数据变化
watch(firstName, (newVal, oldVal) => {
  console.log(`姓名从 ${oldVal}${lastName.value} 变为 ${newVal}${lastName.value}`);
});

// watchEffect — 立即执行，依赖自动追踪
watchEffect(() => {
  console.log("全名变化了：", fullName.value);
});

生命周期钩子在 Composition API 中的使用

Composition API 中的生命周期钩子需要从 Vue 中显式导入，并以回调函数的形式调用：

import {
  onMounted,
  onUpdated,
  onUnmounted,
  onBeforeMount,
  onBeforeUpdate,
  onBeforeUnmount,
} from "vue";

setup() {
  onBeforeMount(() => {
    console.log("组件即将挂载");
  });

  onMounted(() => {
    console.log("组件已挂载");
    // 适合做 DOM 操作、初始化第三方库
  });

  onUpdated(() => {
    console.log("组件已更新");
  });

  onUnmounted(() => {
    console.log("组件已卸载");
    // 适合清理定时器、取消订阅、解绑事件
  });
}

重要提示：所有生命周期钩子必须在 setup 函数内部同步调用，否则 Vue 无法正确关联到当前组件实例。

Composables：逻辑复用的新方式

Composables（组合式函数）是 Composition API 最强大的特性之一。它本质上就是一个使用 Vue 组合式 API 的函数，可以封装和复用有状态的逻辑。

// useMouse.js
export function useMouse() {
  const x = ref(0);
  const y = ref(0);

  const updatePosition = (e) => {
    x.value = e.clientX;
    y.value = e.clientY;
  };

  onMounted(() => {
    window.addEventListener("mousemove", updatePosition);
  });

  onUnmounted(() => {
    window.removeEventListener("mousemove", updatePosition);
  });

  return { x, y };
}

在组件中使用这个 Composable：

// 在任意组件中使用
import { useMouse } from "./composables/useMouse";

export default {
  setup() {
    const { x, y } = useMouse();
    return { x, y };
  },
};

这种方式比 Vue 2 中的 Mixins 更加透明和可维护，每个 Composable 都清晰地声明了它依赖和返回的内容。

与 TypeScript 的完美结合

Composition API 的 TypeScript 支持非常出色，类型推断自然流畅：

import { ref, computed } from "vue";

interface User {
  id: number;
  name: string;
  email: string;
}

// 泛型支持
const count = ref(0);
const users = ref([]);
const userMap = ref>(new Map());

// 计算属性也能获得完整的类型推断
const activeUsers = computed(() => {
  return users.value.filter((u) => u.id > 0);
});

实用技巧与最佳实践

响应式解构：使用 toRefs 可以将 reactive 对象转换为多个 ref，保持响应式的同时支持解构赋值：

import { reactive, toRefs } from "vue";

const state = reactive({ count: 0, name: "Vue" });
// 解构后每个属性仍是响应式的
const { count, name } = toRefs(state);

readonly 防止意外修改：当你希望暴露响应式数据但不希望被直接修改时，使用 readonly：

import { readonly, ref } from "vue";

const originCount = ref(0);
// 暴露给外部的版本只能读取，不能修改
const readOnlyCount = readonly(originCount);

provide/inject 跨层级通信：在 Composition API 中使用 provide 和 inject 比 Options API 更加类型安全：

// 父组件
import { provide, ref } from "vue";
const theme = ref("dark");
provide("theme", theme);

// 子组件
import { inject } from "vue";
const theme = inject("theme", "light");