1. 基本使用

侦听器和计算属性类似，都是依赖响应式数据。不同的是，计算属性在进行二次操作时，不允许进行有副作用的操作。而侦听器恰恰相反，需要我们在状态变化时执行一些“副作用”：例如更改 DOM，或是根据异步操作的结果去修改另一处的状态。

让我们来看一个实例：

<script setup>
import { ref, watch } from 'vue'

const question = ref('')
const answer = ref('Questions usually contain a question mark. ;-)')
const loading = ref(false)

// 可以直接侦听一个 ref
watch(question, async (newQuestion, oldQuestion) => {
  if (newQuestion.includes('?')) {
    loading.value = true
    answer.value = 'Thinking...'
    try {
      const res = await fetch('https://yesno.wtf/api')
      answer.value = (await res.json()).answer
    } catch (error) {
      answer.value = 'Error! Could not reach the API. ' + error
    } finally {
      loading.value = false
    }
  }
})
</script>

<template>
  <p>
    Ask a yes/no question:
    <input v-model="question" :disabled="loading" />
  </p>
  <p>{{ answer }}</p>
</template>

在上面的示例中，watch 就是一个侦听器，侦听 question 这个 ref 状态的变化，每次当 ref 状态发生变化的时候，就会重新执行后面的回调函数，回调函数接收两个参数：
（1）新的状态值
（2）旧的状态值

2. 使用细节

2.1 侦听数据源类型

watch 的第一个参数可以是不同形式的“数据源”：它可以是一个 ref (包括计算属性)、一个响应式对象 reactive、一个 getter 函数、或多个数据源组成的数组。

2.1.1 侦听 ref

在 1.基本使用 中已经提供示例，请返回查看。

2.1.2 侦听 计算属性

<template>
  <div>
    <input type="text" v-model="firstName" placeholder="first name" />
    <input type="text" v-model="lastName" placeholder="last name" />
    <p>全名：{{ fullName }}</p>
  </div>
</template>

<script setup>
import { ref, computed, watch } from 'vue'
const firstName = ref('John')
const lastName = ref('Doe')
const fullName = computed(() => `${firstName.value} ${lastName.value}`)

// 设置侦听器
watch(fullName, (newVal, oldVal) => {
  console.log(`new: ${newVal}, old: ${oldVal}`)
})
</script>

<style scoped></style>

2.1.3 侦听 reactive 响应式对象

2.1.3.1 侦听整个 reactive 对象

<template>
  <div>
    <input type="text" v-model="user.name" placeholder="name" />
    <input type="text" v-model="user.age" placeholder="age" />
    <p>用户信息：{{ user.name }} - {{ user.age }}</p>
  </div>
</template>

<script setup>
import { reactive, watch } from 'vue'
const user = reactive({
  name: 'John',
  age: 18
})

// 设置侦听器
watch(user, () => {
  console.log('触发了侦听器回调函数')
})
</script>

<style scoped></style>

2.1.3.1 侦听 reactie 对象的某个属性（会报错，需要借助 getter 函数）

在 Vue3 中，不能直接侦听响应式对象的属性值，例如:

const obj = reactive({ count: 0 })

// 错误，因为 watch() 得到的参数是一个 number，无法被监听
watch(obj.count, (count) => {
  console.log(`Count is: ${count}`)
})

会有警告，无法实现侦听。

这里需要用一个返回该属性的 getter 函数：

<template>
  <div>
    <input type="text" v-model.number="obj.count" placeholder="count" />
    <p>用户信息：{{ obj }}</p>
  </div>
</template>

<script setup>
import { reactive, watch } from 'vue'
const obj = reactive({ count: 0 })

// 提供一个 getter 函数
watch(
  () => obj.count,
  (count) => {
    console.log(`Count is: ${count}`)
  }
)
</script>

<style scoped></style>

2.1.4 侦听 getter 函数

修改 getter 函数中相关数据的值，触发 watch 的回调函数。

<template>
  <div>
    <input type="number" v-model="x" />
    <span> + </span>
    <input type="number" v-model.number="y" />
    <span> = {{ x + y }}</span>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
let x = ref(1)
let y = ref(2)
// 侦听getter 函数
watch(
  () => x.value + y.value,
  (sum) => {
    console.log(`sum of x + y is: ${sum}`)
  }
)
</script>

<style scoped></style>

2.1.5 侦听多个数据源组成的数组

修改侦听数组的相关数据源，触发watch的回调函数。

<template>
  <div>
    x：<input type="number" v-model="x" />
    ，y：<input type="number" v-model.number="y" />
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
let x = ref(1)
let y = ref(2)
// 多个来源组成的数组
watch([x, () => y.value], ([newX, newY]) => {
  console.log(`x is ${newX} and y is ${newY}`)
})
</script>

<style scoped></style>

2.2 深层侦听器

2.2.1 reactive 对象的侦听默认为深层

直接给 watch() 传入一个响应式对象 reactive，会隐式地创建一个深层侦听器——该回调函数在所有嵌套的变更时都会被触发：

<template>
  <div>
    <input type="number" v-model="obj.count" />
  </div>
</template>

<script setup>
import { reactive, watch } from 'vue'
const obj = reactive({ count: 0 })

watch(obj, (newValue, oldValue) => {
  // 在嵌套的属性变更时触发
  // 注意：`newValue` 此处和 `oldValue` 是相等的
  // 因为它们是同一个对象！
  console.log('obj changed', newValue, oldValue)
})

obj.count++
</script>

<style scoped></style>

注意：深度侦听需要遍历被侦听对象中的所有嵌套的属性，当用于大型数据结构时，开销很大。因此请只在必要时才使用它，并且要留意性能。

2.2.2 侦听响应式对象的 getter 函数，默认为浅层

侦听响应式对象的 getter 函数，默认为浅层，意味着需要替换整个对象的值，才会触发侦听器的回调：

<template>
  <div>{{ state.obj }}</div>
</template>

<script setup>
import { reactive, watch } from 'vue'
const state = reactive({
  obj: {
    count: 0,
  }
})

watch(
  () => state.obj,
  () => {
    // 仅当 state.obj 被替换时触发
    console.log('state.obj 被替换')
  }
)

// 这里只修改 state.obj.count，并不会触发上面的 watch 回调函数
setTimeout(() => {
  state.obj.count = 1
}, 2000)

// 这里替换整个 state.obj，会触发上面的 watch 回调函数
setTimeout(() => {
  state.obj = {
    count: 5
  }
}, 5000)

</script>

<style scoped></style>

2.3 侦听器的第三个参数配置项

• 第一个参数：侦听的数据源；
• 第二个参数：数据发生变化时要执行的回调函数；
• 第三个参数：选项对象
• deep：true/false
  • 强制转换为深层次侦听器
  • 什么时候会用到呢？有些时候使用 watch 来侦听一个由计算属性或者 getter 函数返回的对象的时候，默认就不是深层次的侦听
  • 通过设置 deep 可以让这种情况下的对象侦听，也变成深层次的侦听
• immediate：true/false
  • 默认情况下，watch 对应的回调函数是懒执行的，只有在依赖的数据发生变化时，才会执行回调。
  • 但是在某些场景中，我们可能期望立即执行一次，例如请求一些初始化数据，这个时候就可以设置该配置项
• once：true/false
  • 侦听器的回调函数只执行一次

2.3.1 deep（强制设置为深层侦听器）

<template>
  <div>{{ state.obj }}</div>
</template>

<script setup>
import { reactive, watch } from 'vue'
const state = reactive({
  obj: {
    count: 0,
  },
})

watch(
  () => state.obj,
  () => {
    console.log('obj changed', state.obj.count)
  },
  // 开启深度监听
  { deep: true }
)

setTimeout(() => {
  state.obj.count = 1
}, 2000)

setTimeout(() => {
  state.obj = {
    count: 5
  }
}, 5000)

</script>

<style scoped></style>

2.3.2 immediate（创建时就执行回调）

<template>
  <input type="number" v-model="count">
</template>

<script setup>
import { ref, watch } from 'vue'
let count = ref(0)
watch(
  count,
  (newValue, oldValue) => {
    // 立即执行，且当 `count` 改变时再次执行
    console.log('count：', newValue, oldValue)
  },
  { immediate: true }
)

</script>

<style scoped></style>

2.3.3 once（只执行一次回调函数，仅支持3.4以上版本）

<template>
  <input type="number" v-model="count">
</template>

<script setup>
import { ref, watch } from 'vue'
let count = ref(0)
watch(
  count,
  (newValue, oldValue) => {
    // 立即执行，且当 `count` 改变时再次执行
    console.log('count：', newValue, oldValue)
  },
  { once: true }
)

</script>

<style scoped></style>

2.4 watchEffect()（自动追踪回调里的响应式属性）

2.4.1 使用方式

侦听器的回调使用与源完全相同的响应式状态是很常见的。例如下面的代码，在每当 todoId 的引用发生变化时使用侦听器来加载一个远程资源：

const todoId = ref(1)
const data = ref(null)

watch(
  todoId,
  async () => {
    const response = await fetch(
      `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
    )
    data.value = await response.json()
  },
  { immediate: true }
)

特别是注意侦听器是如何两次使用 todoId 的，一次是作为源，另一次是在回调中。

Vue3 提供了 watchEffect()，允许我们自动跟踪回调的响应式依赖，上面代码可重写简化为：

watchEffect(async () => {
  const response = await fetch(
    `https://jsonplaceholder.typicode.com/todos/${todoId.value}`
  )
  data.value = await response.json()
})

2.4.2 watchEffect 和 watch 的异同（侦听一个嵌套的数据结构的几个属性，建议使用watchEffect）

watch 和 watchEffect 都能响应式地执行有副作用的回调。它们之间的主要区别是追踪响应式依赖的方式：

• watch 只追踪明确侦听的数据源。它不会追踪任何在回调中访问到的东西。另外，仅在数据源确实改变时才会触发回调。watch 会避免在发生副作用时追踪依赖，因此，我们能更加精确地控制回调函数的触发时机。
• watchEffect，则会在副作用发生期间追踪依赖。它会在同步执行过程中，自动追踪所有能访问到的响应式属性。这更方便，而且代码往往更简洁，但有时其响应性依赖关系会不那么明确。

综上，如果你需要侦听一个嵌套的数据结构的几个属性，建议使用watchEffect 。它只会侦听回调中用到的属性，而不是递归侦听所有的属性，对于性能优化会更加友好。

2.5 副作用清理

有时我们可能会在侦听器中执行副作用，例如异步请求：

watch(id, (newId) => {
  fetch(`/api/${newId}`).then(() => {
    // 回调逻辑
  })
})

但是如果在请求完成之前 id 发生了变化怎么办？当上一个请求完成时，它仍会使用已经过时的 ID 值触发回调。理想情况下，我们希望能够在 id 变为新值时取消过时的请求。

2.5.1 onWatcherCleanup() （清理副作用函数，版本 3.5+ 中支持）

我们可以使用 onWatcherCleanup() API 来注册一个清理函数，当侦听器失效并准备重新运行时会被调用：

import { watch, onWatcherCleanup } from 'vue'

watch(id, (newId) => {
  const controller = new AbortController()

  fetch(`/api/${newId}`, { signal: controller.signal }).then(() => {
    // 回调逻辑
  })

  onWatcherCleanup(() => {
    // 终止过期请求
    controller.abort()
  })
})

请注意，onWatcherCleanup 仅在 Vue 3.5+ 中支持，并且必须在 watchEffect 效果函数或 watch 回调函数的同步执行期间调用：你不能在异步函数的 await 语句之后调用它。

2.5.2 onCleanup()（清理副作用函数，3.5 之前的版本有效）

onCleanup 函数还作为第三个参数传递给侦听器回调，以及 watchEffect 作用函数的第一个参数：

watch(id, (newId, oldId, onCleanup) => {
  // ...
  onCleanup(() => {
    // 清理逻辑
  })
})

watchEffect((onCleanup) => {
  // ...
  onCleanup(() => {
    // 清理逻辑
  })
})

这在 3.5 之前的版本有效。此外，通过函数参数传递的 onCleanup 与侦听器实例相绑定，因此不受 onWatcherCleanup 的同步限制。

2.6 回调的触发时机（DOM更新的前后）

2.6.1 Post Watchers（让回调函数访问组件更新之后的DOM）

默认情况下，侦听器回调的执行时机在父组件更新之后，所属组件的 DOM 更新 之前 被调用。这意味着如果你尝试在回调函数中访问所属组件的 DOM，拿到的是 DOM 更新之前的状态。

让我们来看一个实例进行理解：

<template>
  <div>
    <button @click="isShow = !isShow">显示/隐藏</button>
    <div v-if="isShow" ref="divRef">
      <p>this is a test</p>
    </div>
    <p>上面的高度为：{{ height }} pixels</p>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
const isShow = ref(false)
const height = ref(0) // 存储高度
const divRef = ref(null) // 获取元素

watch(isShow, () => {
  // 获取高度，将高度值给 height
  height.value = divRef.value ? divRef.value.offsetHeight : 0
  console.log(`当前获取的高度为：${height.value}`)
})
</script>

<style scoped></style>

点击，切换为显示，但是watch中的高度却是0，说明在 DOM 更新前，就已经执行了 watch 的回调函数。

同理，再次点击，隐藏div，DOM 未更新前仍处于显示状态，因此高度为23。

2.6.1.1 flush: ‘post’（watch 访问更新后的DOM）

但是这明显不符合我们的需求，我们希望在侦听器回调中能访问被 Vue 更新之后的所属组件的 DOM。此时，我们只需要在侦听器的第三个参数中，指明 flush: 'post' 选项：

watch(
  isShow,
  () => {
    // 获取高度，将高度值给 height
    height.value = divRef.value ? divRef.value.offsetHeight : 0
    console.log(`当前获取的高度为：${height.value}`)
  },
  {
    flush: 'post'
  }
)

2.6.1.2 watchPostEffect()（watchEffect 访问更新后的DOM）

后置刷新的 watchEffect() 有个更方便的别名 watchPostEffect()：

import { watchPostEffect } from 'vue'

watchPostEffect(() => {
  /* 在 Vue 更新后执行 */
})

2.6.2 同步侦听器（让回调函数访问所有组件更新之前的DOM）

2.6.2.1 flush: ‘sync’（watch 访问更新前的DOM）

watch(source, callback, {
  flush: 'sync'
})

watchEffect(callback, {
  flush: 'sync'
})

2.6.2.2 watchSyncEffect()（watchEffect 访问更新前的DOM）

import { watchSyncEffect } from 'vue'

watchSyncEffect(() => {
  /* 在响应式数据变化时同步执行 */
})

谨慎使用
同步侦听器不会进行批处理，每当检测到响应式数据发生变化时就会触发。可以使用它来监视简单的布尔值，但应避免在可能多次同步修改的数据源 (如数组) 上使用。

2.7 停止侦听器

2.7.1 停止侦听器的方法（调用 watch 或 watchEffect 返回的函数）

在 setup() 或 <script setup> 中用同步语句创建的侦听器，会自动绑定到宿主组件实例上，并且会在宿主组件卸载时自动停止。因此，在大多数情况下，你无需关心怎么停止一个侦听器。

用异步回调创建的侦听器，不会绑定到当前组件上，你必须手动停止它，以防内存泄漏。如下方这个例子：

<script setup>
import { watchEffect } from 'vue'

// 它会自动停止
watchEffect(() => {})

// ...这个则不会！
setTimeout(() => {
  watchEffect(() => {})
}, 100)
</script>

要手动停止一个侦听器，请调用 watch 或 watchEffect 返回的函数：

const unwatch = watchEffect(() => {})

// ...当该侦听器不再需要时
unwatch()

下面是一个实例：

<template>
  <div>
    <button @click="a++">+1</button>
    <p>当前 a 的值为：{{ a }}</p>
    <p>{{ message }}</p>
  </div>
</template>

<script setup>
import { ref, watch } from 'vue'
const a = ref(1) // 计数器
const message = ref('') // 消息
// 假设我们期望 a 的值到达一定的值之后，停止侦听
const unwatch = watch(
  a,
  (newVal) => {
    // 当值大于 5 的时候，停止侦听
    if (newVal > 5) {
      unwatch()
    }
    message.value = `当前 a 的值为：${a.value}`
  },
  { immediate: true }
)
</script>

<style scoped></style>

一直点击 +1 按钮，当 a 的值超过5，也就是为6时，侦听器便被手动停止了。

2.7.2 条件式侦听（替代异步创建侦听，推荐）

注意，需要异步创建侦听器的情况很少，请尽可能选择同步创建。

如果需要等待一些异步数据，你可以使用条件式的侦听逻辑：

// 需要异步请求得到的数据
const data = ref(null)

watchEffect(() => {
  if (data.value) {
    // 数据加载后执行某些操作...
  }
})

---

上一章 《Vue3 表单输入绑定》

下一章 《Vue3 基础实战练习》