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
147 lines
3.4 KiB
Markdown
147 lines
3.4 KiB
Markdown
---
|
|
category: Reactivity
|
|
alias: controlledRef
|
|
related: computedWithControl
|
|
---
|
|
|
|
# refWithControl
|
|
|
|
Fine-grained controls over ref and its reactivity.
|
|
|
|
## Usage
|
|
|
|
`refWithControl` uses `extendRef` to provide two extra functions `get` and `set` to have better control over when it should track/trigger the reactivity.
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
|
|
const num = refWithControl(0)
|
|
const doubled = computed(() => num.value * 2)
|
|
|
|
// just like normal ref
|
|
num.value = 42
|
|
console.log(num.value) // 42
|
|
console.log(doubled.value) // 84
|
|
|
|
// set value without triggering the reactivity
|
|
num.set(30, false)
|
|
console.log(num.value) // 30
|
|
console.log(doubled.value) // 84 (doesn't update)
|
|
|
|
// get value without tracking the reactivity
|
|
watchEffect(() => {
|
|
console.log(num.peek())
|
|
}) // 30
|
|
|
|
num.value = 50 // watch effect wouldn't be triggered since it collected nothing.
|
|
console.log(doubled.value) // 100 (updated again since it's a reactive set)
|
|
```
|
|
|
|
### `peek`, `lay`, `untrackedGet`, `silentSet`
|
|
|
|
We also provide some shorthands for doing the get/set without track/triggering the reactivity system. The following lines are equivalent.
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
// ---cut---
|
|
const foo = refWithControl('foo')
|
|
```
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
|
|
const foo = refWithControl('foo')
|
|
// ---cut---
|
|
// getting
|
|
foo.get(false)
|
|
foo.untrackedGet()
|
|
foo.peek() // an alias for `untrackedGet`
|
|
```
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
|
|
const foo = refWithControl('foo')
|
|
// ---cut---
|
|
// setting
|
|
foo.set('bar', false)
|
|
foo.silentSet('bar')
|
|
foo.lay('bar') // an alias for `silentSet`
|
|
```
|
|
|
|
## Configurations
|
|
|
|
### `onBeforeChange()`
|
|
|
|
`onBeforeChange` option is offered to give control over if a new value should be accepted. For example:
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
// ---cut---
|
|
const num = refWithControl(0, {
|
|
onBeforeChange(value, oldValue) {
|
|
// disallow changes larger then ±5 in one operation
|
|
if (Math.abs(value - oldValue) > 5)
|
|
return false // returning `false` to dismiss the change
|
|
},
|
|
})
|
|
|
|
num.value += 1
|
|
console.log(num.value) // 1
|
|
|
|
num.value += 6
|
|
console.log(num.value) // 1 (change been dismissed)
|
|
```
|
|
|
|
### `onChanged()`
|
|
|
|
`onChanged` option offers a similar functionally as Vue's `watch` but being synchronized with less overhead compared to `watch`.
|
|
|
|
```ts
|
|
import { refWithControl } from '@vueuse/core'
|
|
// ---cut---
|
|
const num = refWithControl(0, {
|
|
onChanged(value, oldValue) {
|
|
console.log(value)
|
|
},
|
|
})
|
|
```
|
|
|
|
## Type Declarations
|
|
|
|
```ts
|
|
export interface ControlledRefOptions<T> {
|
|
/**
|
|
* Callback function before the ref changing.
|
|
*
|
|
* Returning `false` to dismiss the change.
|
|
*/
|
|
onBeforeChange?: (value: T, oldValue: T) => void | boolean
|
|
/**
|
|
* Callback function after the ref changed
|
|
*
|
|
* This happens synchronously, with less overhead compare to `watch`
|
|
*/
|
|
onChanged?: (value: T, oldValue: T) => void
|
|
}
|
|
/**
|
|
* Fine-grained controls over ref and its reactivity.
|
|
*
|
|
* @__NO_SIDE_EFFECTS__
|
|
*/
|
|
export declare function refWithControl<T>(
|
|
initial: T,
|
|
options?: ControlledRefOptions<T>,
|
|
): ShallowUnwrapRef<{
|
|
get: (tracking?: boolean) => T
|
|
set: (value: T, triggering?: boolean) => void
|
|
untrackedGet: () => T
|
|
silentSet: (v: T) => void
|
|
peek: () => T
|
|
lay: (v: T) => void
|
|
}> &
|
|
Ref<T, T>
|
|
/** @deprecated use `refWithControl` instead */
|
|
export declare const controlledRef: typeof refWithControl
|
|
```
|