[!info] related notes

• 所属 MOC: Vue MOC
• 响应式基础: Vue 响应式系统
• 对比: Composition API vs Options API
• SFC 语法: script setup
• 逻辑复用: [[vue-composable|Vue Composable]]

Vue Composition API

一句话定义

Composition API 不是单个 API，而是一组用于编写 Vue 组件的函数式接口，主要包括：

• Reactivity API：ref、reactive、computed、watch；
• Lifecycle Hooks：onMounted、onUnmounted 等；
• Dependency Injection：provide、inject。

它仍然建立在 Vue 的可变、细粒度响应式系统上，不等于函数式编程。

常见写法

Vue 3 的 SFC 中通常与 <script setup> 配合：

<script setup lang="ts">
import { computed, ref } from 'vue'

const count = ref(0)
const double = computed(() => count.value * 2)

function increment() {
  count.value++
}
</script>

<script setup> 是更简洁的 SFC authoring syntax；Composition API 本身也可以通过普通 setup() 使用。

它真正改变什么

核心不是“把 data/methods 换成 ref/function”。

而是把同一 feature 的：

state
computed
watch/effect
lifecycle
actions

放到一起，并可进一步抽成 composable。

Composable

例如搜索逻辑可以抽成：

useSearch()
├─ query
├─ result
├─ loading
├─ error
└─ search()

复用的是一套有状态逻辑，而不是把组件实例状态自动共享给所有调用者。

TypeScript

Composition API 主要使用普通变量、函数和 imported APIs，因此通常更贴近 TypeScript 自身的类型推导模型。

这不意味着 Options API 不支持 TypeScript；两种 API 的完整对比见 Composition API vs Options API。

适合的场景

• 中大型组件；
• feature 逻辑跨 state/computed/watch/lifecycle；
• 需要抽 composable；
• TypeScript 项目；
• 需要集成第三方有状态逻辑。

常见误区

把所有代码都塞进 script setup

Composition API 提供的是更自由的组织方式，不保证自动模块化。

组件过大时仍要拆：

• composable；
• domain function；
• child component；
• service。

把 composable 当全局 store

每次调用 composable 通常会建立自己的局部状态，除非它显式连接共享 module/store/context。

把 Composition API 当 Options API 的废弃替代

不是。两者都受 Vue 支持。

学习检查

1. Composition API 这个名称包含哪三类核心 API？
2. 它为什么不等于函数式编程？
3. script setup 与 Composition API 是什么关系？
4. composable 复用的是什么，为什么不自动共享状态？
5. 一个 feature 同时有 ref/computed/watch/onMounted 时，Composition API 的组织优势体现在哪里？
6. 什么时候应该继续拆 composable，而不是让 setup 越来越长？