Vue3组合式API精解：十大核心函数详解与实践指南

Vue3的组合式API（Composition API）以其灵活的代码组织和强大的逻辑复用能力，成为现代前端开发的重要范式。本文将系统梳理10个最常用的组合式API，通过原理剖析、应用场景和代码示例，帮助开发者深入理解其设计哲学与最佳实践。

一、响应式控制：reactive与ref

1. reactive：深度响应式对象

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

import { reactive } from 'vue'
const state = reactive({
  count: 0,
  user: {
    name: 'John',
    age: 30
  }
})
// 响应式更新
state.count++
state.user.name = 'Doe' // 嵌套属性同样响应式

适用场景：需要管理复杂状态对象时，如组件状态、全局状态管理等。

注意事项：

• 仅对对象类型有效，基本类型需使用ref
• 解构会丢失响应性，需配合toRefs使用
• 数组变化需使用变异方法（push/pop等）

2. ref：基本类型响应式

ref()通过包装基本类型值为响应式对象，解决了reactive对基本类型的限制。其.value属性提供响应式访问接口。

import { ref } from 'vue'
const count = ref(0)
console.log(count.value) // 0
function increment() {
  count.value++ // 必须通过.value修改
}

类型扩展：在TypeScript中可通过泛型指定类型：

const message = ref<string>('')

最佳实践：

• 模板中自动解包，无需.value
• 组合函数中优先使用ref保持一致性
• 复杂对象建议嵌套在reactive中

二、计算与监听：computed与watch

3. computed：派生状态计算

computed()创建基于响应式依赖的缓存计算值，仅在依赖变化时重新计算。

import { computed, ref } from 'vue'
const a = ref(1)
const b = ref(2)
const sum = computed(() => a.value + b.value)
console.log(sum.value) // 3

高级用法：

• 读写计算属性：

  const count = ref(1)
  const doubled = computed({
  get: () => count.value * 2,
  set: (val) => { count.value = val / 2 }
  })

性能优化：适合处理复杂计算，避免在模板中直接编写复杂表达式。

4. watch：异步数据监听

watch()提供对响应式数据的异步监听能力，支持深度监听和立即执行选项。

import { watch, ref } from 'vue'
const user = ref({ name: 'John' })
// 深度监听对象变化
watch(
  () => user.value,
  (newVal, oldVal) => {
    console.log('User changed:', newVal)
  },
  { deep: true }
)
// 立即执行版本
watch(
  () => user.value.name,
  (newName) => {
    console.log('Name changed:', newName)
  },
  { immediate: true }
)

多数据源监听：

const x = ref(0)
const y = ref(0)
watch([x, y], ([newX, newY]) => {
  console.log(`Coordinates: ${newX}, ${newY}`)
})

三、生命周期：onMounted等

5. 生命周期钩子

Vue3将生命周期钩子转化为组合式API，提供更灵活的控制方式。常用钩子包括：

import { onMounted, onUpdated, onUnmounted } from 'vue'
export default {
  setup() {
    onMounted(() => {
      console.log('组件已挂载')
      // 初始化第三方库
      initChart()
    })
    onUnmounted(() => {
      console.log('组件卸载')
      // 清理资源
      disposeChart()
    })
  }
}

执行顺序：

1. onBeforeMount
2. onMounted
3. onBeforeUpdate
4. onUpdated
5. onBeforeUnmount
6. onUnmounted

四、依赖注入：provide与inject

6. provide/inject：跨层级状态共享

这对API实现了组件树间的依赖注入，适合主题、用户信息等全局状态管理。

// 父组件
import { provide, ref } from 'vue'
export default {
  setup() {
    const theme = ref('dark')
    provide('theme', theme)
  }
}
// 深层子组件
import { inject } from 'vue'
export default {
  setup() {
    const theme = inject('theme', 'light') // 默认值
    return { theme }
  }
}

Symbol键名优化：

// 定义常量
const ThemeSymbol = Symbol()
// 提供方
provide(ThemeSymbol, 'dark')
// 注入方
const theme = inject(ThemeSymbol)

五、实用工具：其他核心API

7. toRefs：解构响应式对象

将reactive对象的属性转换为独立的ref对象，保持响应性。

import { reactive, toRefs } from 'vue'
const state = reactive({
  x: 1,
  y: 2
})
// 解构保持响应性
const { x, y } = toRefs(state)

8. readonly：创建只读响应式

防止内部状态被意外修改，适用于props或全局配置。

import { reactive, readonly } from 'vue'
const config = reactive({
  apiUrl: 'https://api.example.com'
})
const readOnlyConfig = readonly(config)
// readOnlyConfig.apiUrl = 'new' // 警告！

9. 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)
      }
    }
  })
}

10. Suspense：异步组件协调

处理异步组件的加载和错误状态。

// 父组件
<Suspense>
  <template #default>
    <AsyncComponent />
  </template>
  <template #fallback>
    <div>Loading...</div>
  </template>
</Suspense>
// AsyncComponent.vue
import { defineAsyncComponent } from 'vue'
const AsyncComp = defineAsyncComponent(() =>
  import('./HeavyComponent.vue')
)

最佳实践总结

1. 状态管理：简单状态用ref，复杂对象用reactive
2. 计算优化：复杂计算使用computed缓存结果
3. 副作用控制：watch用于异步操作，watchEffect用于即时响应
4. 生命周期：将相关逻辑按生命周期阶段组织
5. 代码组织：使用自定义组合函数（composables）实现逻辑复用

组合式API的强大之处在于其灵活的组合能力，开发者应根据具体场景选择合适的API组合。例如，表单验证可以组合ref、computed和watch实现实时反馈，而全局主题管理则适合provide/inject模式。

通过系统掌握这10个核心API，开发者能够更高效地构建可维护、可测试的Vue3应用，充分发挥组合式编程的优势。建议结合Vue Devtools进行调试，深入理解响应式系统的运作机制。