refWithControl

refとそのリアクティビティに対する細かい制御。

使用法

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

import { refWithControl } from '@vueuse/core'

const num = refWithControl(0)
const doubled = computed(() => num.value * 2)

// 通常のrefと同様
num.value = 42
console.log(num.value) // 42
console.log(doubled.value) // 84

// リアクティビティをトリガーせずに値を設定
num.set(30, false)
console.log(num.value) // 30
console.log(doubled.value) // 84 (更新されない)

// リアクティビティを追跡せずに値を取得
watchEffect(() => {
  console.log(num.peek())
}) // 30

num.value = 50 // 何も収集されなかったため、watch effectはトリガーされません。
console.log(doubled.value) // 100 (リアクティブセットなので再度更新されます)

peek, lay, untrackedGet, silentSet

リアクティビティシステムを追跡/トリガーせずにget/setを行うためのショートハンドも提供しています。以下の行は同等です。

import { refWithControl } from '@vueuse/core'
// ---cut---
const foo = refWithControl('foo')

import { refWithControl } from '@vueuse/core'

const foo = refWithControl('foo')
// ---cut---
// 取得
foo.get(false)
foo.untrackedGet()
foo.peek() // `untrackedGet`のエイリアス

import { refWithControl } from '@vueuse/core'

const foo = refWithControl('foo')
// ---cut---
// 設定
foo.set('bar', false)
foo.silentSet('bar')
foo.lay('bar') // `silentSet`のエイリアス

設定

onBeforeChange()

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

import { refWithControl } from '@vueuse/core'
// ---cut---
const num = refWithControl(0, {
  onBeforeChange(value, oldValue) {
    // 1回の操作で±5を超える変更を許可しない
    if (Math.abs(value - oldValue) > 5)
      return false // `false`を返して変更を却下
  },
})

num.value += 1
console.log(num.value) // 1

num.value += 6
console.log(num.value) // 1 (変更が却下されました)

onChanged()

onChangedオプションは、Vueのwatchと同様の機能を提供しますが、watchと比較してオーバーヘッドが少なく同期されています。

import { refWithControl } from '@vueuse/core'
// ---cut---
const num = refWithControl(0, {
  onChanged(value, oldValue) {
    console.log(value)
  },
})