Vue 3 组合式 API 与 <script setup>、TypeScript 集成及代码组织模式的最佳实践。
版本兼容性
本技能面向 Vue 3.3+，部分功能需要更高的次版本号：
| 特性 | 最低版本 | 参考 |
|---|---|---|
defineOptions | 3.3+ | script-setup |
toValue() | 3.3+ | script-setup |
defineModel | 3.4+ | script-setup |
watch 搭配 once 选项 | 3.4+ | reactivity |
useTemplateRef() | 3.5+ | script-setup |
useId() | 3.5+ | script-setup |
onWatcherCleanup() | 3.5+ | reactivity |
快速决策表
| 问题 | 参考阅读 |
|---|---|
我的 <script setup> 很乱，难以浏览 | SFC 代码组织 |
| 某个功能的逻辑分散在很多行中 | useXxx 函数模式 |
| 相同逻辑在多个组件中重复 | 功能提取 |
| 两个功能相互影响，但不知道正确的处理模式 | 跨功能依赖 |
Props/emits 类型安全、defineModel 使用 | script setup 最佳实践 |
| 在 hooks/工具函数/插件中无法访问 Store | 组件外 Store 访问 |
| 如何组织新的组合式函数文件 | 组合式函数设计模式 |
| 页面感觉慢，可能是响应性问题 | 响应性与性能 |
| 如何测试组合式函数 | 组合式函数测试 |
类型安全的 provide/inject | script setup - Provide/Inject |
代码组织
- SFC 代码缺乏清晰的组织结构 → 参见 sfc-code-organization
- 功能逻辑分散在脚本各处 → 参见 use-function-pattern
- 需要将可复用逻辑提取为组合式函数 → 参见 feature-extraction
- 跨功能依赖导致混乱 → 参见 cross-feature-dependencies
TypeScript 与 Script Setup
- 需要 script setup 的 TypeScript 最佳实践 → 参见 script-setup-best-practices
Store 集成
- 在 Vue 组件外部访问 Pinia store → 参见 store-without-pattern
组合式函数设计
- 设计健壮、可复用的组合式函数 → 参见 composable-design-patterns
响应性与性能
- 优化响应性以获得更好性能 → 参见 reactivity-performance
测试
- 使用 Vitest 测试组合式函数 → 参见 composable-design-patterns
速查表
SFC 代码组织顺序（11 步）
1. defineOptions → 组件名称
2. defineProps → Props 类型声明
3. defineModel → 双向绑定（3.4+）
4. inject → 注入依赖
5. defineEmits → 事件类型声明
6. Store 声明 → useXxxStore()
7. 外部 hooks → useI18n()、useDesign() 等
8. 功能声明 → const { ... } = useFeature()
9. provide → 提供依赖
10. defineExpose → 暴露公共 API
11. 功能实现 → function useFeature() {}
响应式 API 选择
基本类型 → ref
需要深层响应 → ref
大型对象/动态组件 → shallowRef
不需要重新赋值 → reactive（谨慎使用）
永不响应式 → markRaw + shallowRef
Store 访问规则
组件内 (<script setup>) → useAppStore()
组件外 (hooks/utils/plugins) → useAppStoreWithOut()
解构保持响应式 → storeToRefs(store)
反模式 TOP 5
| # | 反模式 | 正确做法 |
|---|---|---|
| 1 | 解构 props → 丢失响应式 | toRefs(props) 或直接用 props.xxx |
| 2 | 组件外用 useXxxStore() | 用 useXxxStoreWithOut() |
| 3 | ref 用于动态组件/大对象 | 用 shallowRef |
| 4 | 混用 Options API + script setup | 只选一种风格 |
| 5 | 事件监听不清理 | onUnmounted 中移除 / 使用 VueUse 的 useEventListener |
依赖模式速查
| 场景 | 推荐模式 |
|---|---|
| 父子组件通信 | Props + Emits |
| 兄弟功能交互 | 回调参数（onXxxChange） |
| 跨层级多对多 | 事件总线（useEmitt） |
| 共享状态 | Store 桥接组合式函数 |
| 功能编排 | 组合式函数编排模式 |