Vue3 中 watch 第三个参数怎么用？6 大配置属性 + 场景指南

在 Vue3 中，watch 的第三个参数是一个 配置选项对象（可选），用于精细控制监听行为。它支持多个属性，各自对应不同的功能，核心作用是调整监听的触发时机、深度监听、防抖节流等逻辑。以下是完整的配置属性及详细说明：

一、核心配置属性（常用）

1. immediate: boolean（默认 false）

• 作用：控制监听是否在 初始渲染时立即执行一次回调函数（无需等待被监听值变化）。

• 场景：需要页面加载时就根据初始值执行逻辑（例如：初始化时请求接口、设置默认状态）。

• 示例：

<script setup>
import { ref, watch } from 'vue'
const count = ref(0)
// 初始渲染时立即执行一次，之后 count 变化时再执行
watch(count, (newVal) => {
  console.log('count 值：', newVal) // 初始输出 0，后续修改时输出新值
}, { immediate: true })
</script>

2. deep: boolean（默认 false）

• 作用：控制是否 深度监听引用类型（对象 / 数组）的内部属性变化。

• 注意：

• • Vue3 的 watch 对 响应式对象（如 reactive 创建的） 默认会进行 “深度监听”（无需手动设 deep: true），但仅监听 “被访问过的属性”（基于 Proxy 代理的惰性监听）；

• • 对 非响应式对象（如 ref 包裹的普通对象） 或 需要监听所有内部属性（包括未访问过的） 时，必须手动设置 deep: true。

• 场景：监听对象的嵌套属性（如 user.info.age）、数组的元素变化。

• 示例：

<script setup>
import { ref, watch } from 'vue'
const user = ref({ name: '张三', info: { age: 20 } })
// 监听 user 内部属性变化（需 deep: true）
watch(user, (newUser) => {
  console.log('age 变化：', newUser.info.age) // 修改 user.value.info.age 时触发
}, { deep: true })
// 触发监听：修改嵌套属性
setTimeout(() => {
  user.value.info.age = 21
}, 1000)
</script>

3. flush: 'pre' | 'post' | 'sync'（默认 'pre'）

• 作用：控制回调函数的 执行时机（即：回调在 Vue 组件更新周期的哪个阶段运行）。

• 三个取值说明：

• 示例（操作更新后的 DOM）：

<template>
  <div ref="box" :style="{ width: `${count * 100}px` }"></div>
</template>
<script setup>
import { ref, watch } from 'vue'
const count = ref(1)
const box = ref(null)
// 回调在 DOM 更新后执行，可获取最新的元素宽度
watch(count, () => {
  console.log('box 宽度：', box.value.offsetWidth) // 正确输出更新后的宽度
}, { flush: 'post' })
// 触发监听：修改 count
setTimeout(() => {
  count.value = 2
}, 1000)
</script>

二、其他实用配置（Vue3.2+ 支持）

4. once: boolean（默认 false）

• 作用：控制监听是否 只触发一次（触发后自动停止监听）。

• 场景：只需响应第一次变化（如：首次加载后的一次性初始化、仅需执行一次的回调）。

• 示例：

<script setup>
import { ref, watch } from 'vue'
const count = ref(0)
// 仅在 count 第一次变化时触发（之后再修改不触发）
watch(count, (newVal) => {
  console.log('count 首次变化：', newVal) // 仅输出 1（第一次修改时）
}, { once: true })
// 触发两次修改
setTimeout(() => { count.value = 1 }, 1000)
setTimeout(() => { count.value = 2 }, 2000) // 无输出
</script>

5. debounce: number（默认 undefined）

• 作用：给监听添加 防抖（延迟 n 毫秒后执行回调，若期间值多次变化，仅执行最后一次）。

• 单位：毫秒（ms）。

• 场景：监听输入框输入（避免频繁触发接口请求）、频繁变化的数值（如滚动位置）。

• 示例（输入框防抖）：

<template>
  <input v-model="keyword" placeholder="搜索...">
</template>
<script setup>
import { ref, watch } from 'vue'
const keyword = ref('')
// 输入停止 500ms 后才执行回调（避免输入时频繁触发）
watch(keyword, (newVal) => {
  console.log('搜索关键词：', newVal) // 输入停止 500ms 后输出
}, { debounce: 500 })
</script>

6. throttle: number（默认 undefined）

• 作用：给监听添加 节流（每隔 n 毫秒最多执行一次回调，期间值多次变化仅执行一次）。

• 单位：毫秒（ms）。

• 场景：监听滚动事件、窗口大小变化等高频触发的场景。

• 示例（滚动节流）：

<script setup>
import { ref, watch } from 'vue'
const scrollTop = ref(0)
// 监听滚动位置，每隔 300ms 最多执行一次
window.addEventListener('scroll', () => {
  scrollTop.value = window.scrollY
})
watch(scrollTop, (newVal) => {
  console.log('滚动位置：', newVal) // 每 300ms 输出一次
}, { throttle: 300 })
</script>

三、配置属性总结表

四、注意事项

1. deep 的使用场景：

• • 监听 reactive 对象时，默认会 “惰性深度监听”（仅监听被访问过的属性），若需监听所有属性（包括未访问的），仍需设置 deep: true；

• • 监听 ref 包裹的对象时，必须设置 deep: true 才能监听内部属性变化。

2. debounce / throttle 的限制：仅 Vue3.2+ 版本支持，低版本需手动通过 lodash 等库实现。

3. 性能优化：避免不必要的 deep: true（会增加监听开销），尽量精准监听具体属性（如 () => user.info.age）。