refWithControl

カテゴリ

リアクティビティ

エクスポートサイズ

474 B

最終変更日

先週

エイリアス

controlledRef

使用方法

refWithControl は extendRef を使用して、リアクティビティの追跡/トリガーのタイミングをより細かく制御するための2つの追加関数 get と set を提供します。

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`

リアクティビティシステムの追跡/トリガーを行わずにget/setを行うためのいくつかの省略形も提供しています。以下の行は同等です。

const foo = refWithControl('foo')

// getting
foo.get(false)
foo.untrackedGet()
foo.peek() // an alias for `untrackedGet`

// setting
foo.set('bar', false)
foo.silentSet('bar')
foo.lay('bar') // an alias for `silentSet`

設定

`onBeforeChange()`

onBeforeChangeオプションは、新しい値を受け入れるかどうかを制御するために提供されます。例:

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オプションは、Vueのwatchと同様の機能を提供しますが、watchと比較してオーバーヘッドが少なくなっています。

const num = refWithControl(0, {
  onChanged(value, oldValue) {
    console.log(value)
  },
})

型宣言

typescript

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.
 */
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>
/**
 * Alias for `refWithControl`
 */
export declare const controlledRef: typeof refWithControl