From 6a5fc04ea467f6a90cd1f00689bcd14596f83719 Mon Sep 17 00:00:00 2001 From: skirtle <65301168+skirtles-code@users.noreply.github.com> Date: Mon, 8 Aug 2022 10:40:46 +0100 Subject: [PATCH] Add a note about `flush: 'sync'`, with links from elsewhere --- src/api/component-instance.md | 2 +- src/api/options-state.md | 2 +- src/api/reactivity-core.md | 4 +++- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/src/api/component-instance.md b/src/api/component-instance.md index 7f6fc5ae95..9a6d1a6910 100644 --- a/src/api/component-instance.md +++ b/src/api/component-instance.md @@ -218,7 +218,7 @@ Imperative API for creating watchers. - **`immediate`**: trigger the callback immediately on watcher creation. Old value will be `undefined` on the first call. - **`deep`**: force deep traversal of the source if it is an object, so that the callback fires on deep mutations. See [Deep Watchers](/guide/essentials/watchers.html#deep-watchers). - - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing). + - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core.html#watcheffect). - **`onTrack / onTrigger`**: debug the watcher's dependencies. See [Watcher Debugging](/guide/extras/reactivity-in-depth.html#watcher-debugging). - **Example** diff --git a/src/api/options-state.md b/src/api/options-state.md index 3dc48aead6..203adfceb4 100644 --- a/src/api/options-state.md +++ b/src/api/options-state.md @@ -291,7 +291,7 @@ Declare watch callbacks to be invoked on data change. - **`immediate`**: trigger the callback immediately on watcher creation. Old value will be `undefined` on the first call. - **`deep`**: force deep traversal of the source if it is an object or an array, so that the callback fires on deep mutations. See [Deep Watchers](/guide/essentials/watchers.html#deep-watchers). - - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing). + - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core.html#watcheffect). - **`onTrack / onTrigger`**: debug the watcher's dependencies. See [Watcher Debugging](/guide/extras/reactivity-in-depth.html#watcher-debugging). Avoid using arrow functions when declaring watch callbacks as they will not have access to the component instance via `this`. diff --git a/src/api/reactivity-core.md b/src/api/reactivity-core.md index bc355e29a5..6bbf09f8ca 100644 --- a/src/api/reactivity-core.md +++ b/src/api/reactivity-core.md @@ -256,6 +256,8 @@ Runs a function immediately while reactively tracking its dependencies and re-ru The second argument is an optional options object that can be used to adjust the effect's flush timing or to debug the effect's dependencies. + By default, watchers will run just prior to component rendering. Setting `flush: 'post'` will defer the watcher until after component rendering. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing) for more information. In rare cases, it might be necessary to trigger a watcher immediately when a reactive dependency changes, e.g. to invalidate a cache. This can be achieved using `flush: 'sync'`. However, this setting should be used with caution, as it can lead to problems with performance and data consistency if multiple properties are being updated at the same time. + The return value is a handle function that can be called to stop the effect from running again. - **Example** @@ -382,7 +384,7 @@ Watches one or more reactive data sources and invokes a callback function when t - **`immediate`**: trigger the callback immediately on watcher creation. Old value will be `undefined` on the first call. - **`deep`**: force deep traversal of the source if it is an object, so that the callback fires on deep mutations. See [Deep Watchers](/guide/essentials/watchers.html#deep-watchers). - - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing). + - **`flush`**: adjust the callback's flush timing. See [Callback Flush Timing](/guide/essentials/watchers.html#callback-flush-timing) and [`watchEffect()`](/api/reactivity-core.html#watcheffect). - **`onTrack / onTrigger`**: debug the watcher's dependencies. See [Watcher Debugging](/guide/extras/reactivity-in-depth.html#watcher-debugging). Compared to [`watchEffect()`](#watcheffect), `watch()` allows us to: