toRef() プロパティを接続を保つ ref に変換する
最終更新：2026-10-22
toRef() プロパティを接続を保つ ref に変換する
toRef() はリアクティブなオブジェクトの 1 つのプロパティを、リンクが保たれた ref に変換します。この ref を介した読み書きは、元のプロパティへの操作としてそのまま反映されます。
| グループ | リアクティビティ: ユーティリティ |
|---|---|
| 種類 | API |
| スコープ | コンポーネント内 |
| Vue バージョン | 3.0+ |
| SSR 対応 | 対応 |
📝 構文
const state = reactive({ count: 0 })
const count = toRef(state, 'count')
count.value++ // state.count++ と同じ⚙️ 引数
| object | リアクティブなオブジェクト |
|---|---|
| key | プロパティ名 |
戻り値：元のプロパティと双方向にリンクされた ref
▶ 例
以下のコードを編集して結果を確認しましょう：
出力：
Both numbers always match: writing the ref updates state.count.💡 ポイント
💡 ヒント 定番の使い方：props のフィールドを ref に変換してからコンポーザブルに渡すと、リアクティビティが失われません。
ℹ️ 補足 toRef(state, 'a') は toRefs(state).a と同等です。プロパティが存在しない場合でも作成でき（書き込み可能です）。
⚠️ 注意 toRef はデータをコピーするのではなく通路です。元のオブジェクトを丸ごと置き換えるとリンクが切れます。
🏷️ 関連ユーティリティ
💡 関連ケース
関連ケースは近日公開予定。
📚 関連チュートリアル
❓ よくある質問
Q toRef と toRefs の関係は？
A toRef は 1 つのプロパティを扱い、toRefs はすべてのプロパティの ref をまとめて返します。後者は状態全体を分割代入するときによく使われます。
Q なぜ分割代入では代用できないのですか？
A const { count } = state で得られるのはスナップショットの数値で、以降の変化は同期されません。toRef なら接続が保たれます。
Q 通常のオブジェクトにも使えますか？
A 使えます。ただし通常のオブジェクトにはリアクティビティがないため、ref はそのプロパティを読み書きする便利な通路になるだけです。
