Vue3 Composition API 实战：从 Options API 迁移的完整步骤与案例

Vue 3 引入了 Composition API，它提供了更灵活、可复用的代码组织方式，相比传统的 Options API，能更好地处理复杂逻辑。本指南将帮助你逐步迁移现有项目，从 Options API 过渡到 Composition API，并附上一个完整案例。迁移的核心在于使用 setup() 函数替代 data、methods 等选项，提升代码可读性和维护性。

为什么迁移到 Composition API？

• Options API 的局限性：在大型项目中，逻辑分散在 data、methods、computed 等选项中，导致代码难以复用和测试。
• Composition API 的优势：通过 ref、reactive、computed 等函数，将相关逻辑聚合在 setup() 中，支持逻辑复用（如自定义 hooks），并提升 TypeScript 支持。
• 迁移收益：代码更简洁、性能优化更易实现，尤其适合中大型应用。

完整迁移步骤

迁移过程需逐步进行，避免一次性重写整个项目。以下是通用步骤，适用于大多数 Vue 组件：

1. 准备工作：

   • 确保项目使用 Vue 3（版本 ≥ 3.0），安装依赖：npm install vue@next。
   • 备份原有代码，使用版本控制（如 Git）。
   • 分析组件：识别哪些组件适合优先迁移（例如，逻辑复杂的组件）。

2. 重构组件结构：

   • 移除 Options API 的 data、methods、computed 等选项。
   • 引入 setup() 函数作为组件的入口点。
   • 使用 ref 或 reactive 定义响应式状态：
     • ref 用于基本类型（如数字、字符串）。
     • reactive 用于对象或数组。
   • 将方法定义为普通函数，并在 setup() 中返回。

3. 处理生命周期钩子：

   • Options API 的钩子（如 mounted、updated）迁移为 Composition API 的 onMounted、onUpdated 等。
   • 在 setup() 中调用这些钩子函数。

4. 迁移计算属性和侦听器：

   • 使用 computed 函数替代 computed 选项。
   • 使用 watch 或 watchEffect 替代 watch 选项，处理依赖跟踪。

5. 处理 Props 和 Emits：

   • 在 setup() 的参数中接收 props 和 context（包含 emit）。
   • 使用 toRefs 解构 props 以保持响应性。

6. 测试和迭代：

   • 逐步迁移组件，运行测试（如 Jest 或 Vitest）确保功能正常。
   • 优化逻辑：将可复用代码提取为自定义 hooks（类似 React hooks）。

迁移案例：计数器组件

下面是一个简单计数器组件的迁移示例。原始版本使用 Options API，迁移后使用 Composition API。案例展示核心变化，便于理解。

原始 Options API 代码 (Counter.vue)：

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="increment">Increment</button>
    <button @click="reset">Reset</button>
  </div>
</template>

<script>
export default {
  data() {
    return {
      count: 0
    };
  },
  methods: {
    increment() {
      this.count++;
    },
    reset() {
      this.count = 0;
    }
  }
};
</script>

迁移后的 Composition API 代码 (Counter.vue)：

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button @click="increment">Increment</button>
    <button @click="reset">Reset</button>
  </div>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    // 使用 ref 定义响应式状态
    const count = ref(0);
    
    // 定义方法
    const increment = () => {
      count.value++;
    };
    
    const reset = () => {
      count.value = 0;
    };
    
    // 返回状态和方法，供模板使用
    return {
      count,
      increment,
      reset
    };
  }
};
</script>

案例解析：

• 状态管理：data 中的 count 迁移为 ref(0)，通过 count.value 访问（模板中自动解包，无需 .value）。
• 方法迁移：methods 中的函数直接定义为箭头函数，并在 setup() 中返回。
• 响应式更新：Composition API 使用 ref 确保状态变化触发视图更新，与 Options API 行为一致。
• 好处：代码更集中，易于扩展（例如，添加新逻辑时直接在 setup() 中添加函数）。

迁移注意事项

• 渐进式迁移：大型项目建议逐个组件迁移，使用 mixins 或 provide/inject 临时桥接。
• 性能优化：Composition API 支持更细粒度的响应式控制，避免不必要的渲染（如使用 shallowRef）。
• 工具支持：利用 Vue Devtools 调试，IDE 插件（如 Volar）提升开发体验。
• 常见坑点：
  • ref vs reactive：优先 ref 用于基本类型，避免直接修改 reactive 对象（使用函数更新）。
  • 生命周期钩子：确保在 setup() 中正确调用，如 onMounted(() => { ... })。

总结

迁移到 Vue 3 Composition API 能显著提升代码质量和可维护性。通过本指南的步骤和案例，你可以平滑过渡：从分析组件开始，重构为 setup() 函数，并逐步测试。实践表明，迁移后组件逻辑更清晰，尤其适合团队协作和长期维护。建议从简单组件入手，积累经验后再处理复杂场景。