4a3ce4cc1d
Add comprehensive reference documentation for: - Vitest: environments, projects/workspaces, type testing, vi utilities - Pinia: HMR, Nuxt integration, SSR setup - Vue: built-in components (Transition, Teleport, Suspense, KeepAlive) and advanced directives
121 lines
3.1 KiB
Markdown
121 lines
3.1 KiB
Markdown
---
|
|
category: Watch
|
|
alias: ignorableWatch
|
|
---
|
|
|
|
# watchIgnorable
|
|
|
|
Ignorable watch
|
|
|
|
## Usage
|
|
|
|
Extended `watch` that returns extra `ignoreUpdates(updater)` and `ignorePrevAsyncUpdates()` to ignore particular updates to the source.
|
|
|
|
```ts
|
|
import { watchIgnorable } from '@vueuse/core'
|
|
import { nextTick, shallowRef } from 'vue'
|
|
|
|
const source = shallowRef('foo')
|
|
|
|
const { stop, ignoreUpdates } = watchIgnorable(
|
|
source,
|
|
v => console.log(`Changed to ${v}!`),
|
|
)
|
|
|
|
source.value = 'bar'
|
|
await nextTick() // logs: Changed to bar!
|
|
|
|
ignoreUpdates(() => {
|
|
source.value = 'foobar'
|
|
})
|
|
await nextTick() // (nothing happened)
|
|
|
|
source.value = 'hello'
|
|
await nextTick() // logs: Changed to hello!
|
|
|
|
ignoreUpdates(() => {
|
|
source.value = 'ignored'
|
|
})
|
|
source.value = 'logged'
|
|
|
|
await nextTick() // logs: Changed to logged!
|
|
```
|
|
|
|
## WatchOptionFlush timing
|
|
|
|
`watchIgnorable` accepts the same options as `watch` and uses the same defaults.
|
|
So, by default the composable works using `flush: 'pre'`.
|
|
|
|
## `ignorePrevAsyncUpdates`
|
|
|
|
This feature is only for async flush `'pre'` and `'post'`. If `flush: 'sync'` is used, `ignorePrevAsyncUpdates()` is a no-op as the watch will trigger immediately after each update to the source. It is still provided for sync flush so the code can be more generic.
|
|
|
|
```ts
|
|
import { watchIgnorable } from '@vueuse/core'
|
|
import { nextTick, shallowRef } from 'vue'
|
|
|
|
const source = shallowRef('foo')
|
|
|
|
const { ignorePrevAsyncUpdates } = watchIgnorable(
|
|
source,
|
|
v => console.log(`Changed to ${v}!`),
|
|
)
|
|
|
|
source.value = 'bar'
|
|
await nextTick() // logs: Changed to bar!
|
|
|
|
source.value = 'good'
|
|
source.value = 'by'
|
|
ignorePrevAsyncUpdates()
|
|
|
|
await nextTick() // (nothing happened)
|
|
|
|
source.value = 'prev'
|
|
ignorePrevAsyncUpdates()
|
|
source.value = 'after'
|
|
|
|
await nextTick() // logs: Changed to after!
|
|
```
|
|
|
|
## Recommended Readings
|
|
|
|
- [Ignorable Watch](https://patak.dev/vue/ignorable-watch.html) - by [@patak-dev](https://github.com/patak-dev)
|
|
|
|
## Type Declarations
|
|
|
|
```ts
|
|
export type IgnoredUpdater = (updater: () => void) => void
|
|
export type IgnoredPrevAsyncUpdates = () => void
|
|
export interface WatchIgnorableReturn {
|
|
ignoreUpdates: IgnoredUpdater
|
|
ignorePrevAsyncUpdates: IgnoredPrevAsyncUpdates
|
|
stop: WatchStopHandle
|
|
}
|
|
export declare function watchIgnorable<
|
|
T extends Readonly<MultiWatchSources>,
|
|
Immediate extends Readonly<boolean> = false,
|
|
>(
|
|
sources: [...T],
|
|
cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>,
|
|
options?: WatchWithFilterOptions<Immediate>,
|
|
): WatchIgnorableReturn
|
|
export declare function watchIgnorable<
|
|
T,
|
|
Immediate extends Readonly<boolean> = false,
|
|
>(
|
|
source: WatchSource<T>,
|
|
cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
|
|
options?: WatchWithFilterOptions<Immediate>,
|
|
): WatchIgnorableReturn
|
|
export declare function watchIgnorable<
|
|
T extends object,
|
|
Immediate extends Readonly<boolean> = false,
|
|
>(
|
|
source: T,
|
|
cb: WatchCallback<T, Immediate extends true ? T | undefined : T>,
|
|
options?: WatchWithFilterOptions<Immediate>,
|
|
): WatchIgnorableReturn
|
|
/** @deprecated use `watchIgnorable` instead */
|
|
export declare const ignorableWatch: typeof watchIgnorable
|
|
```
|