customRef() 独自の動作を持つ ref を作る
最終更新：2026-10-22
customRef() 独自の動作を持つ ref を作る
customRef() はファクトリ関数で依存の追跡とトリガーのタイミングをカスタマイズできます。定番の用途は入力欄へのデバウンスです。
| グループ | リアクティビティ: 応用 |
|---|---|
| 種類 | API |
| スコープ | コンポーネント内 |
| Vue バージョン | 3.0+ |
| SSR 対応 | 対応 |
📝 構文
function useDebounced(value, delay) {
return customRef((track, trigger) => ({
get() { track(); return value },
set(v) { clearTimeout(timer); timer = setTimeout(() => { value = v; trigger() }, delay) }
}))
}⚙️ 引数
| factory | (track, trigger) => { get, set }。track が依存を収集し、trigger が更新を通知します |
|---|
戻り値：カスタム動作の ref
▶ 例
以下のコードを編集して結果を確認しましょう：
出力：
Typing fast updates the line only after a 400ms pause — intermediate states are merged.💡 ポイント
⚠️ 注意 track() と trigger() は必ず呼びます。track を忘れると依存が収集されず、trigger を忘れると更新が発火しません。
💡 ヒント useDebounced のようなコンポーザブルにラップして再利用するのが定番のパターンです。
ℹ️ 補足 デバウンス、スロットル、バリデーション付きの入力モデルなど、独自の同期戦略に最適です。
🏷️ 関連応用
💡 関連ケース
関連ケースは近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q 依存を手動で track するのはなぜですか？
A customRef は完全な制御を開発者に委ねるため、いつ依存を収集し、いつ通知するかを明示的に宣言する必要があります。
Q デバウンスに customRef は必須ですか？
A 必須ではありません。watch + setTimeout で通常の ref を管理することもできますが、customRef のほうがまとまりのある書き方です。
Q スロットルも実装できますか？
A できます。set 内で最初の書き込みは即座に実行し、以降は間隔をあけてトリガーすればよいです。
