What is the implementation principle of Vue3 listener watch

The essence of watch

The so-called watch, its essence is to observe a responsive data, notify and execute the corresponding callback function when the data changes. In fact, the essence of watch implementation is to use the effect and options.scheduler options. As shown in the following example:

// watch 函数接收两个参数，source 是响应式数据，cb 是回调函数
function watch(source, cb){
  effect(
    // 触发读取操作，从而建立联系
  	() => source.foo,
    {
      scheduler(){
        // 当数据变化时，调用回调函数 cb
        cb()
      }
    }
  )
}

As shown in the code, source is responsive data, and cb is the callback function. If there is a scheduler option in the side effect function, when the responsive data changes, the execution of the scheduler function will be triggered instead of directly triggering the execution of the side effect function. From this perspective, the scheduler scheduling function is equivalent to a callback function, and the implementation of watch takes advantage of this.

Function signature of watch

Listening to multiple sources

The data source to listen to can be an array, as shown in the following function signature:

// packages/runtime-core/src/apiWatch.ts

// 数据源是一个数组
// overload: array of multiple sources + cb
export function watch<
  T extends MultiWatchSources,
  Immediate extends Readonly<boolean> = false
>(
  sources: [...T],
  cb: WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>,
  options?: WatchOptions<Immediate>
): WatchStopHandle

You can also use an array to listen to multiple sources at the same time, as shown in the following function signature:

// packages/runtime-core/src/apiWatch.ts

// 使用数组同时侦听多个源
// overload: multiple sources w/ `as const`
// watch([foo, bar] as const, () => {})
// somehow [...T] breaks when the type is readonly
export function watch<
  T extends Readonly<MultiWatchSources>,
  Immediate extends Readonly<boolean> = false
>(
  source: T,
  cb: WatchCallback<MapSources<T, false>, MapSources<T, Immediate>>,
  options?: WatchOptions<Immediate>
): WatchStopHandle

Listen to a single source

The data source to listen to is a ref type data or Is a getter function with a return value, as shown in the following function signature:

// packages/runtime-core/src/apiWatch.ts

// 数据源是一个 ref 类型的数据 或者是一个具有返回值的 getter 函数
// overload: single source + cb
export function watch<T, Immediate extends Readonly<boolean> = false>(
source: WatchSource<T>,
 cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
 options?: WatchOptions<Immediate>
): WatchStopHandle

export type WatchSource<T = any> = Ref<T> | ComputedRef<T> | (() => T)

The listening data source is a responsive obj object, as shown in the following function signature:

// packages/runtime-core/src/apiWatch.ts

// 数据源是一个响应式的 obj 对象
// overload: watching reactive object w/ cb
export function watch<
  T extends object,
  Immediate extends Readonly<boolean> = false
>(
  source: T,
  cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
  options?: WatchOptions<Immediate>
): WatchStopHandle

Watch implementation

watch function

// packages/runtime-core/src/apiWatch.ts

// implementation
export function watch<T = any, Immediate extends Readonly<boolean> = false>(
  source: T | WatchSource<T>,
  cb: any,
  options?: WatchOptions<Immediate>
): WatchStopHandle {
  if (__DEV__ && !isFunction(cb)) {
    warn(
      `\`watch(fn, options?)\` signature has been moved to a separate API. ` +
        `Use \`watchEffect(fn, options?)\` instead. \`watch\` now only ` +
        `supports \`watch(source, cb, options?) signature.`
    )
  }
  return doWatch(source as any, cb, options)
}

As you can see, the watch function receives 3 parameters, namely: source listening data source, cb callback function, options listening options.

source parameter

It can be known from the function overloading of watch that when listening to a single source, the source can be a ref type data or a getter function with a return value. , or it can be a responsive obj object. When listening to multiple sources, source can be an array.

cb parameter

In the cb callback function, the developer is provided with the latest value, the old value and the onCleanup function for cleaning side effects. As shown in the following type definition:

export type WatchCallback<V = any, OV = any> = (
  value: V,
  oldValue: OV,
  onCleanup: OnCleanup
) => any

options Parameters

options Options can control the behavior of the watch. For example, the option parameter immediate of options can be used to control whether the callback of the watch is executed immediately. The option parameter controls whether the watch callback function is executed synchronously or asynchronously. The type definition of options parameter is as follows:

export interface WatchOptionsBase extends DebuggerOptions {
  flush?: 'pre' | 'post' | 'sync'
}
export interface WatchOptions<Immediate = boolean> extends WatchOptionsBase {
  immediate?: Immediate
  deep?: boolean
}

You can see the type definition of options. WatchOptions inherits WatchOptionsBase. That is to say, in addition to the two unique parameters of immediate and deep in the options of watch, all parameters in WatchOptionsBase can also be passed to control the behavior of side effect execution.

The doWatch function is called in the function body of watch. Let’s take a look at its implementation.

doWatch function

In fact, whether it is the watch function or the watchEffect function, the doWatch function is ultimately called during execution.

doWatch function signature

function doWatch(
  source: WatchSource | WatchSource[] | WatchEffect | object,
  cb: WatchCallback | null,
  { immediate, deep, flush, onTrack, onTrigger }: WatchOptions = EMPTY_OBJ
): WatchStopHandle

The function signature of doWatch is basically the same as the function signature of watch, and also receives three parameters. In order to facilitate the use of the options option, the doWatch function deconstructs it.

Initialize variables

First, get the current component instance through component, and then declare three different variables. One of the functions is called a getter, which is passed as an argument to the side-effect function. The variable forceTrigger is a Boolean value that indicates whether the side-effect function needs to be forced. The isMultiSource variable is also a Boolean value, used to mark whether the listening data source is a single source or multiple sources passed in in the form of an array. The initial value is false, indicating that the listening data source is a single source. As shown in the following code:

  const instance = currentInstance
  let getter: () => any
  // 是否需要强制触发副作用函数执行   
  let forceTrigger = false
  // 侦听的是否是多个源
  let isMultiSource = false

Next, initialize these three variables according to the listening data source.

The listening data source is a ref type data

When the listening data source is a ref type data, initialize by returning source.value Getter, that is to say, when the getter function is triggered, the actual listening data will be obtained through source.value. Then use the isShallow function to determine whether the listened data source is a shallow response, and assign the result to forceTrigger to complete the initialization of the forceTrigger variable. As shown in the following code:

if (isRef(source)) {
  // 侦听的数据源是 ref
  getter = () => source.value
  // 判断数据源是否是浅响应
  forceTrigger = isShallow(source)
}

The listening data source is a responsive data

When the listening data source is a responsive data, directly Return source to initialize the getter, that is, when the getter function is triggered, it directly returns the listening data source. Since the responsive data may be an object object, set deep to true, and the object's attribute values ​​can be read recursively when the getter function is triggered. As shown in the following code:

else if (isReactive(source)) {
  // 侦听的数据源是响应式数据
  getter = () => source
  deep = true
}

The listening data source is an array

When the listening data source is an array, that is, multiple listening data sources are listened to at the same time source. At this time, directly set the isMultiSource variable to true, indicating that multiple sources are being listened to. Then use the some method of the array to detect whether there are responsive objects in the multiple listening sources, and assign the results to forceTrigger. Traverse the array and complete the initialization of the getter function based on the type of each source. As shown in the following code:

else if (isArray(source)) {
  // 侦听的数据源是一个数组，即同时侦听多个源
  isMultiSource = true
  forceTrigger = source.some(isReactive)
  getter = () =>
    // 遍历数组，判断每个源的类型 
    source.map(s => {
      if (isRef(s)) {
        // 侦听的数据源是 ref  
        return s.value
      } else if (isReactive(s)) {
        // 侦听的数据源是响应式数据 
        return traverse(s)
      } else if (isFunction(s)) {
        // 侦听的数据源是一个具有返回值的 getter 函数 
        return callWithErrorHandling(s, instance, ErrorCodes.WATCH_GETTER)
      } else {
        __DEV__ && warnInvalidSource(s)
      }
    })
}

The listening data source is a function

当侦听的数据源是一个具有返回值的 getter 函数时，判断 doWatch 函数的第二个参数 cb 是否有传入。如果有传入，则处理的是 watch 函数的场景，此时执行 source 函数，将执行结果赋值给 getter 。该情况仅适用于 watchEffect 函数未接收到参数的情况。如果组件实例已被卸载，则直接返回而不执行 source 函数，根据该场景进行处理。如果未能执行成功，则执行清除依赖的代码并调用source函数，将返回结果赋值给getter。如下面的代码所示：

else if (isFunction(source)) {

  // 处理 watch 和 watchEffect 的场景
  // watch 的第二个参数可以是一个具有返回值的 getter 参数，第二个参数是一个回调函数
  // watchEffect 的参数是一个 函数

  // 侦听的数据源是一个具有返回值的 getter 函数 
  if (cb) {
    // getter with cb
    // 处理的是 watch 的场景
    // 执行 source 函数，将执行结果赋值给 getter   
    getter = () =>
      callWithErrorHandling(source, instance, ErrorCodes.WATCH_GETTER)
  } else {
    // no cb -> simple effect
    // 没有回调，即为 watchEffect 的场景  
    getter = () => {
      // 件实例已经卸载，则不执行，直接返回
      if (instance && instance.isUnmounted) {
        return
      }
      // 清除依赖
      if (cleanup) {
        cleanup()
      }
      // 执行 source 函数
      return callWithAsyncErrorHandling(
        source,
        instance,
        ErrorCodes.WATCH_CALLBACK,
        [onCleanup]
      )
    }
  }
}

递归读取响应式数据

如果侦听的数据源是一个响应式数据，需要递归读取响应式数据中的属性值。如下面的代码所示：

// 处理的是 watch 的场景
// 递归读取对象的属性值  
if (cb && deep) {
  const baseGetter = getter
  getter = () => traverse(baseGetter())
}

在上面的代码中，doWatch 函数的第二个参数 cb 有传入，说明处理的是 watch 中的场景。deep 变量为 true ，说明此时侦听的数据源是一个响应式数据，因此需要调用 traverse 函数来递归读取数据源中的每个属性，对其进行监听，从而当任意属性发生变化时都能够触发回调函数执行。

定义清除副作用函数

声明 cleanup 和 onCleanup 函数，并在 onCleanup 函数的执行过程中给 cleanup 函数赋值，当副作用函数执行一些异步的副作用时，这些响应需要在其失效是清除。如下面的代码所示：

// 清除副作用函数
let cleanup: () => void
let onCleanup: OnCleanup = (fn: () => void) => {
  cleanup = effect.onStop = () => {
    callWithErrorHandling(fn, instance, ErrorCodes.WATCH_CLEANUP)
  }
}

封装 scheduler 调度函数

为了便于控制 watch 的回调函数 cb 的执行时机，需要将 scheduler 调度函数封装为一个独立的 job 函数，如下面的代码所示：

// 将 scheduler 调度函数封装为一个独立的 job 函数，便于在初始化和变更时执行它
const job: SchedulerJob = () => {
  if (!effect.active) {
    return
  }
  if (cb) {
    // 处理 watch 的场景 
    // watch(source, cb)

    // 执行副作用函数获取新值
    const newValue = effect.run()
    
    // 如果数据源是响应式数据或者需要强制触发副作用函数执行或者新旧值发生了变化
    // 则执行回调函数，并更新旧值
    if (
      deep ||
      forceTrigger ||
      (isMultiSource
        ? (newValue as any[]).some((v, i) =>
            hasChanged(v, (oldValue as any[])[i])
          )
        : hasChanged(newValue, oldValue)) ||
      (__COMPAT__ &&
        isArray(newValue) &&
        isCompatEnabled(DeprecationTypes.WATCH_ARRAY, instance))
    ) {
      
      // 当回调再次执行前先清除副作用
      // cleanup before running cb again
      if (cleanup) {
        cleanup()
      }

      // 执行watch 函数的回调函数 cb，将旧值和新值作为回调函数的参数
      callWithAsyncErrorHandling(cb, instance, ErrorCodes.WATCH_CALLBACK, [
        newValue,
        
        // 首次调用时，将 oldValue 的值设置为 undefined
        // pass undefined as the old value when it's changed for the first time
        oldValue === INITIAL_WATCHER_VALUE ? undefined : oldValue,
        onCleanup
      ])
      // 更新旧值，不然下一次会得到错误的旧值
      oldValue = newValue
    }
  } else {
    // watchEffect
    // 处理 watchEffect 的场景
    effect.run()
  }
}

在 job 函数中，判断回调函数 cb 是否传入，如果有传入，那么是 watch 函数被调用的场景，否则就是 watchEffect 函数被调用的场景。

如果是 watch 函数被调用的场景，首先执行副作用函数，将执行结果赋值给 newValue 变量，作为最新的值。然后判断需要执行回调函数 cb 的情况：

• 如果侦听的数据源是响应式数据，需要深度侦听，即 deep 为 true

• 如果需要强制触发副作用函数执行，即 forceTrigger 为 true

• 如果新旧值发生了变化

如果存在上述三种情况之一，就必须执行 watch 函数的回调函数 cb。如果回调函数 cb 是再次执行，在执行之前需要先清除副作用。然后调用 callWithAsyncErrorHandling 函数执行回调函数cb，并将新值newValue 和旧值 oldValue 传入回调函数cb中。在回调函数cb执行后，更新旧值oldValue，避免在下一次执行回调函数cb时获取到错误的旧值。

如果是 watchEffect 函数被调用的场景，则直接执行副作用函数即可。

设置 job 的 allowRecurse 属性

设置 job 函数的 allowRecurse 属性根据是否传递回调函数 cb 来进行。这个设置非常关键，因为它可以使作业充当监听器的回调，这样调度程序就能够知道它是否允许调用自身。

// important: mark the job as a watcher callback so that scheduler knows
// it is allowed to self-trigger (#1727)
// 重要：让调度器任务作为侦听器的回调以至于调度器能知道它可以被允许自己派发更新
job.allowRecurse = !!cb

flush 选项指定回调函数的执行时机

在调用 watch 函数时，可以通过 options 的 flush 选项来指定回调函数的执行时机：

• 当 flush 的值为 sync 时，代表调度器函数是同步执行，此时直接将 job 赋值给 scheduler，这样调度器函数就会直接执行。

• 当 flush 的值为 post 时，代表调度函数需要将副作用函数放到一个微任务队列中，并等待 DOM 更新结束后再执行。

• 当 flush 的值为 pre 时，即调度器函数默认的执行方式，这时调度器会区分组件是否已经挂载。如果组件未挂载，则先执行一次调度函数，即执行回调函数cb。在组件挂载之后，将调度函数推入一个优先执行时机的队列中。

  // 这里处理的是回调函数的执行时机
  let scheduler: EffectScheduler if (flush === 'sync') { // 同步执行，将 job 直接赋值给调度器 scheduler = job as any // the scheduler function gets called directly } else if (flush === 'post') { // 将调度函数 job 添加到微任务队列中执行 scheduler = () => queuePostRenderEffect(job, instance && instance.suspense) } else { // default: 'pre' // 调度器函数默认的执行模式 scheduler = () => { if (!instance || instance.isMounted) { // 组件挂载后将 job 推入一个优先执行时机的队列中 queuePreFlushCb(job) } else { // with 'pre' option, the first call must happen before // the component is mounted so it is called synchronously. // 在 pre 选型中，第一次调用必须发生在组件挂载之前 // 所以这次调用是同步的 job() } } }

创建副作用函数

初始化完 getter 函数和调度器函数 scheduler 后，调用 ReactiveEffect 类来创建一个副作用函数

// 创建一个副作用函数
const effect = new ReactiveEffect(getter, scheduler)

执行副作用函数

在执行副作用函数之前，首先判断是否传入了回调函数cb，如果有传入，则根据 options 的 immediate 选项来判断是否需要立即执行回调函数cb，如果指定了immediate 选项，则立即执行 job 函数，即 watch 的回调函数会在 watch 创建时立即执行一次。如果不这样做，就需要手动调用副作用函数，将其返回值赋值给oldValue作为旧值。如下面的代码所示：

if (cb) {
  // 选项参数 immediate 来指定回调是否需要立即执行
  if (immediate) {
    // 回调函数会在 watch 创建时立即执行一次
    job()
  } else {
    // 手动调用副作用函数，拿到的就是旧值
    oldValue = effect.run()
  }
}

如果 options 的 flush 选项的值为 post ，需要将副作用函数放入到微任务队列中，等待组件挂载完成后再执行副作用函数。如下面的代码所示：

else if (flush === 'post') {
  // 在调度器函数中判断 flush 是否为 'post'，如果是，将其放到微任务队列中执行
  queuePostRenderEffect(
    effect.run.bind(effect),
    instance && instance.suspense
  )
}

其余情况都是立即执行副作用函数。如下面的代码所示：

else {
  // 其余情况立即首次执行副作用
  effect.run()
}

返回匿名函数，停止侦听

最终，doWatch函数返回了一个匿名函数，该函数用于取消对数据源的监听。因此在调用 watch 或者 watchEffect 时，可以调用其返回值类结束侦听。

return () => {
  effect.stop()
  if (instance && instance.scope) {
    // 返回一个函数，用以显式的结束侦听
    remove(instance.scope.effects!, effect)
  }
}

The above is the detailed content of What is the implementation principle of Vue3 listener watch. For more information, please follow other related articles on the PHP Chinese website!