深入理解 Vue 3 的 setup（含 Composition API）setup 是 Vue 3 Compositi

深入理解 Vue 3 的 setup（含 Composition API）

1. 为什么需要 setup？

Vue 2 的选项式 API（data、methods、computed 等）在处理小规模逻辑时清晰直观，但当组件功能复杂后，同一个逻辑关注点被分散在多个选项里（数据在 data，修改方法在 methods，副作用在 mounted），导致代码可维护性大幅下降。

Vue 3 的 Composition API 通过 setup 函数将同一个功能的所有相关代码聚合在一起，让逻辑内聚、复用更方便。简单来说：setup** 是组件内组合式逻辑的入口，在这里你可以用响应式 API 自由组织代码，不再被选项“分割”。**

2. setup 的角色与执行时机

setup 函数在组件实例创建之前、props 解析完成后立即执行。它是组件内使用 Composition API 的唯一入口，在 beforeCreate 之前调用。

执行阶段	说明
1. 解析 `props`	组件接收的属性已可用
2. 执行 `setup`	组合式逻辑在此集中运行，无法访问 `this`
3. 完成实例创建	模板编译、渲染

速记：setup 在 beforeCreate 之前跑，没有 this，专注于响应式数据和逻辑的组合。

3. setup 的基本写法（非语法糖）

接收两个参数：props 与 context，返回一个对象暴露给模板。

export default {
  props: { title: String },
  setup(props, { emit }) {
    function handleClick() {
      emit('update');
    }
    return { handleClick };
  }
};

4. `<script setup>` 语法糖（推荐）

<script setup> 是 Vue 3.2+ 提供的编译时语法糖，顶层绑定自动暴露给模板。

<script setup>
import { ref } from 'vue';
const count = ref(0);
</script>
<template>
  <p>{{ count }}</p>
</template>

普通 setup 与 <script setup> 的工作流对比：

5. 响应式核心：ref 与 reactive

API	适用类型	访问方式	本质
`ref`	任意值	`.value`（模板中自动解包）	内部将值包装为响应式对象
`reactive`	对象、数组	直接属性访问	返回 Proxy 代理

关键区别：ref 可持有原始值，在 <script> 中必须 .value 操作；reactive 不可重新整体赋值。

6. 生命周期钩子

在 setup 内不能使用 mounted 等选项式钩子，需要用带 on 前缀的函数。下面这张图展示了选项式钩子与 setup 钩子的映射关系：

具体对应关系如下表：

选项式 API	`setup` 内钩子
`beforeCreate`	不需要（`setup` 本身就是）
`created`	不需要（`setup` 本身就是）
`beforeMount`	`onBeforeMount`
`mounted`	`onMounted`
`beforeUpdate`	`onBeforeUpdate`
`updated`	`onUpdated`
`beforeUnmount`	`onBeforeUnmount`
`unmounted`	`onUnmounted`

7. 组件间的通信：defineProps 与 defineEmits

在 <script setup> 中用编译器宏声明：

<script setup>
const props = defineProps({ title: String });
const emit = defineEmits(['update']);
</script>

8. 逻辑复用：组合函数（Composables）

// useMouse.js
export function useMouse() {
  const x = ref(0), y = ref(0);
  const update = (e) => { x.value = e.pageX; y.value = e.pageY; };
  onMounted(() => window.addEventListener('mousemove', update));
  onUnmounted(() => window.removeEventListener('mousemove', update));
  return { x, y };
}

10. 常见误区

误区	真相
“setup 里能使用 `this`”	实例尚未创建，`this` 为 `undefined`
“reactive 可直接替换整个对象”	重新赋值会丢失响应性
“script setup 中需要手动 return”	顶层绑定自动暴露

11. 总结

setup 是 Vue 3 Composition API 的入口，它将相关逻辑聚合在一起，突破了选项式 API 的碎片化困境。通过 ref 和 reactive 创建响应式数据，配合生命周期钩子与 watchEffect，你可以用更函数式的方式构建组件。掌握 setup，你就掌握了 Vue 3 高效开发的核心：按功能组织代码，而不是按选项类型。

深入理解 Vue 3 的 setup（含 Composition API）