Config

設定

これらは、VueUse のほとんどの関数に対する一般的な設定を示しています。

イベントフィルター

v4.0 から、イベントがいつトリガーされるかを柔軟に制御するためのイベントフィルターシステムを提供しています。例えば、throttleFilter と debounceFilter を使用してイベントのトリガーレートを制御できます。

import { debounceFilter, throttleFilter, useLocalStorage, useMouse } from '@vueuse/core'

// 変更は 1 秒間隔で localStorage に書き込まれます
const storage = useLocalStorage('my-key', { foo: 'bar' }, { eventFilter: throttleFilter(1000) })

// マウスの位置は 100ms のアイドル後に更新されます
const { x, y } = useMouse({ eventFilter: debounceFilter(100) })

さらに、pausableFilter を利用して一時的にいくつかのイベントを停止することができます。

import { pausableFilter, useDeviceMotion } from '@vueuse/core'

const motionControl = pausableFilter()

const motion = useDeviceMotion({ eventFilter: motionControl.eventFilter })

motionControl.pause()
// モーションの更新が停止されました

motionControl.resume()
// モーションの更新が再開されました

リアクティブなタイミング

VueUse の関数は、可能な限り Vue のリアクティビティシステムのデフォルトの flush タイミングに従います。

watch に似たコンポーザブル（例: watchPausable, whenever, useStorage, useRefHistory）では、デフォルトは { flush: 'pre' } です。これは、無効化された効果をバッファし、それらを非同期にフラッシュすることを意味します。これにより、同じ「ティック」で複数の状態変化が発生する場合に不要な重複呼び出しを避けることができます。

watch と同様に、VueUse では flush オプションを渡すことでタイミングを設定できます。

import { watchPausable } from '@vueuse/core'
import { ref } from 'vue'

const counter = ref(0)
const { pause, resume } = watchPausable(
  counter,
  () => {
    // 更新された DOM に安全にアクセス
  },
  { flush: 'post' },
)

flush オプション（デフォルト: 'pre'）

'pre': 同じ「ティック」で無効化された効果をバッファし、レンダリング前にフラッシュ
'post': 'pre' と同様に非同期だが、コンポーネントの更新後に発火するため、更新された DOM にアクセス可能
'sync': 効果を常に同期的にトリガーすることを強制

注意: computed に似たコンポーザブル（例: syncRef, computedWithControl）では、flush タイミングが設定可能な場合、デフォルトは { flush: 'sync' } に変更され、Vue の computed refs の動作と一致します。

設定可能なグローバル依存関係

v4.0 から、ブラウザ API にアクセスする関数は、グローバル依存関係（例: window, document, navigator）を指定するためのオプションフィールドを提供します。デフォルトではグローバルインスタンスを使用するため、ほとんどの場合、心配する必要はありません。この設定は、iframe やテスト環境で作業する際に便利です。

// @lib: dom
// @noErrors: 18047 2339
import { useMouse } from '@vueuse/core'

// 親コンテキストにアクセス
const parentMousePos = useMouse({ window: window.parent })

const iframe = document.querySelector('#my-iframe')

// 子コンテキストにアクセス
const childMousePos = useMouse({ window: iframe.contentWindow })

// テスト
const mockWindow = { /* ... */ }

const { x, y } = useMouse({ window: mockWindow })