Vue3常用组合式API精解：10大核心函数全掌握

Vue3的组合式API（Composition API）为前端开发带来了革命性的变化，通过逻辑复用和更灵活的代码组织方式，显著提升了大型应用的开发效率。本文将系统梳理Vue3中最常用的10个组合式API，从基础响应式到高级状态管理，通过代码示例和最佳实践帮助开发者深入理解其核心机制。

一、响应式基础：reactive与ref

1. reactive：深度响应式对象

reactive()是Vue3响应式系统的核心API，用于创建深度响应式的对象。其内部通过Proxy实现数据劫持，能够递归追踪对象内部所有嵌套属性的变化。

import { reactive } from 'vue'
const state = reactive({
  count: 0,
  user: {
    name: 'John',
    age: 30
  }
})
// 修改嵌套属性自动触发更新
function increment() {
  state.count++
  state.user.age++
}

关键特性：

• 自动解包：在模板中直接使用state.count无需.value
• 深度响应：所有嵌套属性都会被追踪
• 不可变限制：不能解构或展开，否则会失去响应性

适用场景：管理组件内部复杂状态对象，特别是包含多层嵌套的数据结构。

2. ref：通用响应式容器

ref()通过创建包含.value属性的响应式对象，解决了reactive()的局限性，适用于基本类型和需要解构的场景。

import { ref } from 'vue'
const count = ref(0)
const items = ref(['a', 'b', 'c'])
// 解构后保持响应性（需配合toRefs）
const { count: aliasCount } = toRefs({ count })
function update() {
  count.value++ // 必须通过.value修改
  items.value.push('d')
}

最佳实践：

• 优先使用ref处理基本类型
• 在<script setup>中模板自动解包，无需.value
• 配合computed和watch使用更高效

二、计算与监听：computed与watch

3. computed：响应式计算属性

computed()创建的派生状态会自动缓存，仅在依赖变化时重新计算，显著提升性能。

import { computed, ref } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
const fullName = computed(() => {
  return `${firstName.value} ${lastName.value}`
})
// 带setter的计算属性
const number = computed({
  get: () => count.value * 2,
  set: (val) => { count.value = val / 2 }
})

性能优化：

• 避免在计算属性中执行异步操作
• 复杂计算考虑拆分为多个计算属性
• 使用shallowRef优化大型对象计算

4. watch与watchEffect：响应式监听

watch()和watchEffect()提供了强大的副作用控制能力，区别在于依赖追踪方式。

import { watch, watchEffect, ref } from 'vue'
const count = ref(0)
const user = reactive({ name: 'John' })
// 显式指定依赖
watch(
  () => count.value,
  (newVal, oldVal) => {
    console.log(`count changed from ${oldVal} to ${newVal}`)
  }
)
// 自动追踪依赖
watchEffect(() => {
  console.log(`user name is ${user.name}`)
  // 自动追踪user.name的变化
})

选择策略：

• 需要知道旧值时使用watch
• 依赖关系复杂时优先watchEffect
• 立即执行副作用添加{ immediate: true }
• 清理副作用使用onInvalidate

三、生命周期与组件通信

5. onMounted等生命周期钩子

组合式API通过onXXX系列函数统一管理生命周期，支持条件式调用和多次注册。

import { onMounted, onUpdated, onUnmounted } from 'vue'
export default {
  setup() {
    onMounted(() => {
      console.log('组件已挂载')
      window.addEventListener('resize', handleResize)
    })
    onUnmounted(() => {
      window.removeEventListener('resize', handleResize)
    })
    function handleResize() { /* ... */ }
  }
}

优势：

• 逻辑按功能组织而非生命周期阶段
• 可在异步组件中精确控制执行时机
• 配合<script setup>语法更简洁

6. provide与inject：跨层级状态传递

provide/inject实现了祖先组件向后代组件的深度状态共享，避免props逐层传递。

// 祖先组件
import { provide, ref } from 'vue'
const theme = ref('dark')
provide('theme', theme)
// 后代组件
import { inject } from 'vue'
const theme = inject('theme', 'light') // 默认值

响应式处理：

• 传递ref或reactive对象保持响应性
• 使用readonly防止后代组件意外修改
• 结合provide/inject实现主题切换等全局功能

四、高级状态管理

7. toRefs与toRef：解构响应式对象

toRefs()将响应式对象的每个属性转为独立的ref，保持解构后的响应性。

import { reactive, toRefs } from 'vue'
const state = reactive({
  x: 0,
  y: 0
})
// 解构后保持响应性
const { x, y } = toRefs(state)
function move(dx, dy) {
  x.value += dx
  y.value += dy
}

典型场景：

• 从setup()返回响应式对象时解构
• 与TypeScript类型系统配合使用
• 避免直接解构reactive对象导致的响应性丢失

8. shallowRef与shallowReactive：浅层响应

对于大型不可变数据或第三方库实例，浅层响应可显著提升性能。

import { shallowRef, shallowReactive } from 'vue'
const largeData = shallowRef({ /* 大型对象 */ })
const externalLib = shallowReactive({ /* 第三方实例 */ })
// 仅顶层属性变化触发更新
function update() {
  largeData.value = newLargeData // 替换整个ref值触发更新
  // largeData.value.prop = newValue 不会触发更新
}

性能考量：

• 避免深层嵌套对象使用浅层响应
• 监控性能瓶颈时考虑替换为浅层响应
• 与triggerRef强制更新配合使用

五、实用工具API

9. customRef：自定义响应式引用

customRef提供了完全控制响应式行为的机制，适用于防抖、节流等特殊场景。

import { customRef } from 'vue'
function useDebouncedRef(value, delay = 200) {
  let timeout
  return customRef((track, trigger) => {
    return {
      get() {
        track()
        return value
      },
      set(newValue) {
        clearTimeout(timeout)
        timeout = setTimeout(() => {
          value = newValue
          trigger()
        }, delay)
      }
    }
  })
}
// 使用
const debouncedText = useDebouncedRef('')

高级用法：

• 实现输入框防抖
• 创建懒加载引用
• 封装第三方库的响应式适配

10. readonly与markRaw：控制响应性

readonly()创建只读响应式对象，markRaw()标记对象永远不转为响应式。

import { reactive, readonly, markRaw } from 'vue'
const original = reactive({ count: 0 })
const copy = readonly(original)
// copy.count++ // 警告：Set operation on key "count" failed...
const staticObj = markRaw({ foo: 'bar' })
const state = reactive({
  static: staticObj // 不会转为响应式
})

应用场景：

• 暴露只读状态给子组件
• 避免第三方库实例被Vue转换
• 优化大型静态数据结构性能

最佳实践总结

1. 响应式选择策略：基本类型用ref，对象用reactive，大型不可变数据用shallowRef
2. 计算属性优化：避免在计算属性中执行副作用，复杂计算拆分为多个属性
3. 监听器清理：始终在onUnmounted或watch回调中清理事件监听和定时器
4. 状态共享：简单场景用provide/inject，复杂状态考虑Pinia
5. 性能监控：使用Vue Devtools分析不必要的响应式转换

通过系统掌握这10个核心组合式API，开发者能够更高效地组织Vue3组件代码，实现更可维护和性能优化的前端应用。组合式API的灵活性特别适合中大型项目开发，其逻辑复用能力相比Options API具有显著优势。建议开发者从简单组件开始实践，逐步掌握高级用法。