Vue 3 常用 API 技术速查指南

⚡ Vue 3 常用 API 技术速查指南

在 Vue 3 组合式 API（<script setup>）开发中，高频使用的核心 API 可分为以下五大类。

---

一、 响应式核心 API（基础必备）

用于将普通 JavaScript 数据转化为支持视图更新的响应式数据。

1. ref()

• 适用场景：基本数据类型（String, Number, Boolean）、数组或单个对象。
• 特点：在 <script> 中读写必须加 .value，在 <template> 模板中可直接使用。

import { ref } from 'vue'

const count = ref(0)
const updateCount = () => {
  count.value++ // 必须通过 .value 修改
}

2. reactive()

• 适用场景：复杂的引用数据类型（多层嵌套的对象、表单数据）。
• 特点：不需要加 .value。
• ⚠️ 避坑：绝对不能直接重新赋值整个对象，否则会丢失响应式。若要清空或重置，应使用 Object.assign()。

import { reactive } from 'vue'

const userInfo = reactive({ name: '张三', age: 18 })

// ❌ 错误做法：userInfo = { name: '李四' } (失去响应式)
//  正确做法：
Object.assign(userInfo, { name: '李四', age: 20 })

3. computed()

• 适用场景：基于现有响应式数据进行二次计算（如：过滤列表、计算总价）。
• 特点：具备缓存机制。只有依赖的数据变化时，才会重新计算。

import { ref, computed } from 'vue'

const price = ref(10)
const quantity = ref(5)
const totalPrice = computed(() => price.value * quantity.value)

---

二、 数据侦听 API（状态监控）

1. watch()

• 特点：显式指定监听源。可以获取到新值（newValue）和旧值（oldValue）。默认是惰性的（初次加载不执行）。

import { ref, watch } from 'vue'

const searchKeyword = ref('')
watch(searchKeyword, (newVal, oldVal) => {
  console.log(`搜索词从 ${oldVal} 变为了 ${newVal}`)
  // 这里可以触发网络请求
})

2. watchEffect()

• 特点：立即执行一次。无需手动指定监听谁，自动追踪函数内部用到的所有响应式变量，只要其中一个变了就会重新执行。

import { ref, watchEffect } from 'vue'

const userId = ref(1)
// 初始化时立即执行，后续 userId 改变时也会自动执行
watchEffect(() => {
  console.log(`当前用户ID是: ${userId.value}`)
})

---

三、 常用的生命周期钩子

Vue 3 组合式 API 中，生命周期钩子需要加上 on 前缀，并以回调函数形式调用。

钩子名称	触发时机	常见用途
onMounted()	组件挂载到 DOM 完成时	发送网络请求（Axios）、获取 DOM 节点
onUpdated()	数据更新且虚拟 DOM 重新渲染后	处理 DOM 更新后的边界副作用
onUnmounted()	组件销毁（卸载）完成时	清除定时器、移除全局事件监听防内存泄漏

import { onMounted, onUnmounted } from 'vue'

let timer = null

onMounted(() => {
  console.log('组件已挂载，启动定时器')
  timer = setInterval(() => { /* 执行逻辑 */ }, 1000)
})

onUnmounted(() => {
  console.log('组件已销毁，清理资源')
  clearInterval(timer) // 及时清理
})

---

四、 跨组件通信 API

1. toRefs()

• 用途：将一个 reactive 对象解构为多个独立的 ref。
• 解决痛点：直接对 reactive 对象进行解构（如 const { name } = userInfo）会丢失响应式。用 toRefs 可以保持响应式连接。

2. provide() / inject()（依赖注入）

• 用途：实现祖先组件向子孙组件跨级传递数据，彻底告别 Props 层层传递（Props Hell）。

// 祖先组件
import { provide, ref } from 'vue'
const themeColor = ref('dark')
provide('theme', themeColor) // 广播数据

// 子孙组件
import { inject } from 'vue'
const theme = inject('theme') // 接收数据

---

五、 <script setup> 编译器宏（无需导入）

在 <script setup> 语法糖中，这三个 API 不需要 import 引入，可以直接在代码中使用。

1. defineProps()

• 用途：在子组件中声明和接收父组件传递过来的属性（Props）。

// 子组件
const props = defineProps({
  title: String,
  visible: Boolean
})

2. defineEmits()

• 用途：在子组件中声明自定义事件，用来向父组件派发通知并传递数据。

// 子组件
const emit = defineEmits(['success', 'close'])
const handleSubmit = () => {
  emit('success', { code: 200 }) // 触发事件
}

3. defineExpose()

• 用途：显式暴露子组件内部的方法或属性。
• 场景：默认情况下 <script setup> 组件是全封闭的。如果父组件通过 ref 拿到了子组件实例，子组件必须用它暴露，父组件才能调用子组件的方法（如弹窗的 open() 方法）。

// 子组件（弹窗组件）
import { ref } from 'vue'
const isShow = ref(false)
const openModal = () => { isShow.value = true }

defineExpose({ openModal }) // 暴露给父组件调用