侦听器

基本示例

计算属性允许我们声明性地计算衍生值。然而在有些情况下，我们需要在状态变化时执行一些“副作用”：例如更改 DOM，或是根据异步操作的结果去修改另一处的状态。

我们可以使用 watch 函数在每次响应式状态发生变化时触发回调函数：

vue

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

<script lang='py'>
from vuepy import ref, watch

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

# // 可以直接侦听一个 ref

@watch(question)
def update(newQuestion, oldQuestion, on_cleanup):
  if '?' in newQuestion:
    loading.value = True
    answer.value = 'Thinking...'
    try:
      res = query(question.value)
      answer.value = res.answer
    except Exception as error:
      answer.value = f'Error! Could not reach the API. {error}'
    finally:
      loading.value = False
    }
  }
})
</script>

侦听数据源类型

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

x = ref(0)
y = ref(0)

# 单个 ref
@watch(x)
def x_update(newX, oldX, on_cleanup):
    print(f'x is {newX}')

# getter 函数
@watch(lambda: x.value + y.value)
def getter_update(sum, _, _):
    print(f'sum of x + y is: {sum}')

# 多个来源组成的数组
@watch([x, lambda: y.value])
def update(newVals, _, _):
    newX, newY = newVals
    print(f'x is {newX} and y is {newY}')

注意，你不能直接侦听响应式对象的属性值，例如:

obj = reactive({ 'count': 0 })

# 错误，因为 watch() 得到的参数是一个 number
@watch(obj.count)
def update(count, _, _):
    print(fcount is: {count}')

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

# 提供一个 getter 函数
@watch(lambda: obj.count)
def update(count, _, _):
    print(fcount is: {count}')

深层侦听器

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

obj = reactive({ 'count': 0 })

@watch(obj)
def update(newValue, oldValue, _):
  # 在嵌套的属性变更时触发
  # 注意：`newValue` 此处和 `oldValue` 是相等的
  # 因为它们是同一个对象！

obj.count += 1

相比之下，一个返回响应式对象的 getter 函数，只有在返回不同的对象时，才会触发回调：

@watch(lambda: state.someObject)
def update(_, __, ___):
    # 仅当 state.someObject 被替换时触发

你也可以给上面这个例子显式地加上 deep 选项，强制转成深层侦听器：

@watch(lambda: state.someObject, WatchOptions(deep=True))
def update(newValue, oldValue, _):
    # 注意：`newValue` 此处和 `oldValue` 是相等的
    # *除非* state.someObject 被整个替换了

谨慎使用

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

即时回调的侦听器

watch 默认是懒执行的：仅当数据源变化时，才会执行回调。但在某些场景中，我们希望在创建侦听器时，立即执行一遍回调。举例来说，我们想请求一些初始数据，然后在相关状态更改时重新请求数据。

我们可以通过传入 immediate: True 选项来强制侦听器的回调立即执行：

@watch(source, WatchOptions(immediate=True))
def update(newValue, oldValue, _):
    # 立即执行，且当 `source` 改变时再次执行

一次性侦听器

WARNING

请注意，这是一个预留的语法，当前版本未实现。

每当被侦听源发生变化时，侦听器的回调就会执行。如果希望回调只在源变化时触发一次，请使用 once: true 选项。

watch(
  source,
  (newValue, oldValue) => {
    // 当 `source` 变化时，仅触发一次
  },
  { once: true }
)

`watchEffect()`

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

todoId = ref(1)
data = ref(None)

@watch(todoId, WatchOptions(immediate=True))
def update(*args):
    response = fetch(f'https://xxx.com/todos/{todoId.value}')
    data.value = response.json()

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

我们可以用 watchEffect 函数来简化上面的代码。watchEffect() 允许我们自动跟踪回调的响应式依赖。上面的侦听器可以重写为：

@watchEffect
def update(*args):
  response = fetch(f'https://xxx.com/todos/{todoId.value}')
  data.value = response.json()

这个例子中，回调会立即执行，不需要指定 immediate: true。在执行期间，它会自动追踪 todoId.value 作为依赖（和计算属性类似）。每当 todoId.value 变化时，回调会再次执行。有了 watchEffect()，我们不再需要明确传递 todoId 作为源值。

对于这种只有一个依赖项的例子来说，watchEffect() 的好处相对较小。但是对于有多个依赖项的侦听器来说，使用 watchEffect() 可以消除手动维护依赖列表的负担。此外，如果你需要侦听一个嵌套数据结构中的几个属性，watchEffect() 可能会比深度侦听器更有效，因为它将只跟踪回调中被使用到的属性，而不是递归地跟踪所有的属性。

TIP

watchEffect 仅会在其同步执行期间，才追踪依赖。在使用异步回调时，只有在第一个 await 正常工作前访问到的属性才会被追踪。

`watch` vs. `watchEffect`

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

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

回调的触发时机

当你更改了响应式状态，它可能会同时触发 Vue 组件更新和侦听器回调。

类似于组件更新，用户创建的侦听器回调函数也会被批量处理以避免重复调用。例如，如果我们同步将一千个项目推入被侦听的数组中，我们可能不希望侦听器触发一千次。

默认情况下，侦听器回调会同步调用。

Post Watchers

WARNING

请注意，这是一个预留的语法，当前版本未实现。

如果想在侦听器回调中能访问被 Vue 更新之后的所属组件的 DOM，你需要指明 flush: 'post' 选项：

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

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

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

import { watchPostEffect } from 'vue'

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

同步侦听器

WARNING

请注意，这是一个预留的语法，当前版本未实现。

你还可以创建一个同步触发的侦听器，它会在 Vue 进行任何更新之前触发：

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

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

同步触发的 watchEffect() 有个更方便的别名 watchSyncEffect()：

import { watchSyncEffect } from 'vue'

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

谨慎使用

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

停止侦听器

用 watch 选项或者 $watch() 实例方法声明的侦听器，会在宿主组件卸载时自动停止。因此，在大多数场景下，你无需关心怎么停止它。

在少数情况下，你的确需要在组件卸载之前就停止一个侦听器，这时可以调用 $watch() API 返回的函数：

const unwatch = this.$watch('foo', callback)

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

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

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

@watchEffect
def update_stop(*args):
    pass

# ...当该侦听器不再需要时
update_stop()

在 GitHub 上编辑此页

侦听器 ​

基本示例 ​

侦听数据源类型 ​

深层侦听器 ​

即时回调的侦听器 ​

一次性侦听器 ​

watchEffect() ​

watch vs. watchEffect ​

回调的触发时机 ​

Post Watchers ​

同步侦听器 ​

停止侦听器 ​

侦听器

基本示例

侦听数据源类型

深层侦听器

即时回调的侦听器

一次性侦听器

`watchEffect()`

`watch` vs. `watchEffect`

回调的触发时机

Post Watchers

同步侦听器

停止侦听器