本文へジャンプ

リアクティビティー API: ユーティリティー

isRef()

値が ref オブジェクトかどうかをチェックします。

  • ts
    function isRef<T>(r: Ref<T> | unknown): r is Ref<T>
    

    戻り値の型は型述語であることに注意してください。これは isRef が型ガードとして使用できることを意味します:

    ts
    let foo: unknown
    if (isRef(foo)) {
      // foo の型が Ref<unknown> に絞り込まれる
      foo.value
    }
    

unref()

引数が ref であればその内部の値を返し、そうでなければ引数そのものを返します。これは val = isRef(val) ? val.value : val に対するシュガー関数です。

  • ts
    function unref<T>(ref: T | Ref<T>): T
    
  • ts
    function useFoo(x: number | Ref<number>) {
      const unwrapped = unref(x)
      // unwrapped は number であることが保証されます
    }
    

toRef()

ソースとなるリアクティブオブジェクトのプロパティの ref を作成するために使用できます。作成された ref はそのソースのプロパティと同期されます。ソースのプロパティを変更すると ref も更新され、その逆も同様です。

  • ts
    function toRef<T extends object, K extends keyof T>(
      object: T,
      key: K,
      defaultValue?: T[K]
    ): ToRef<T[K]>
    
    type ToRef<T> = T extends Ref ? T : Ref<T>
    
  • js
    const state = reactive({
      foo: 1,
      bar: 2
    })
    
    const fooRef = toRef(state, 'foo')
    
    // ref を変更すると参照元も更新されます
    fooRef.value++
    console.log(state.foo) // 2
    
    // 参照元を変更すると ref も更新されます
    state.foo++
    console.log(fooRef.value) // 3
    

    以下とはことなるので注意してください:

    js
    const fooRef = ref(state.foo)
    

    ref() が単なる数字の値を受け取っているため、上記の ref は state.foo と同期していません

    toRef() は prop の ref をコンポーザブル関数へ渡したいときに便利です:

    vue
    <script setup>
    import { toRef } from 'vue'
    
    const props = defineProps(/* ... */)
    
    // `props.foo` を ref に変換して
    // コンポーザブルに渡す
    useSomeFeature(toRef(props, 'foo'))
    </script>
    

    コンポーネントプロパティに toRefs を使用する場合、プロパティの変更に関するいつも通りの制限が適用されます。ref に新しい値を代入しようとするのは、プロパティを直接変更しようとすることと同等であり、許可されていません。そのようなシナリオでは getset を持つ computed を使うことを検討するとよいでしょう。詳しくは、コンポーネントで v-model を使うためのガイドを参照してください。

    toRef() はソースプロパティが現在存在しない場合でも、利用可能な ref を返します。これにより toRefs では取得できないオプショナルなプロパティを扱えるようになります。

toRefs()

リアクティブオブジェクトをプレーンオブジェクトに変換します。変換後のオブジェクトの各プロパティは、元のオブジェクトの対応するプロパティを指す ref です。個々の ref は toRef() を用いて生成されます。

  • ts
    function toRefs<T extends object>(
      object: T
    ): {
      [K in keyof T]: ToRef<T[K]>
    }
    
    type ToRef = T extends Ref ? T : Ref<T>
    
  • js
    const state = reactive({
      foo: 1,
      bar: 2
    })
    
    const stateAsRefs = toRefs(state)
    /*
    stateAsRefs の型: {
      foo: Ref<number>,
      bar: Ref<number>
    }
    */
    
    // ref と参照元のプロパティは「リンク」している
    state.foo++
    console.log(stateAsRefs.foo.value) // 2
    
    stateAsRefs.foo.value++
    console.log(state.foo) // 3
    

    toRefs はコンポーザブル関数からリアクティブなオブジェクトを返す場合に便利です。使用する側のコンポーネントはリアクティビティを失わずに、返されたオブジェクトを分割代入やスプレッドできます:

    js
    function useFeatureX() {
      const state = reactive({
        foo: 1,
        bar: 2
      })
    
      // ...ステートに関するロジック
    
      // 返すときに ref に変換する
      return toRefs(state)
    }
    
    // リアクティビティを失わずに分割代入できる
    const { foo, bar } = useFeatureX()
    

    toRefs は呼び出した時のソースオブジェクトにある列挙可能なプロパティに対する ref だけを生成します。存在しないかも知れないプロパティに対する ref を作るには、代わりに toRef を使用してください。

isProxy()

オブジェクトが reactive(), readonly(), shallowReactive(), shallowReadonly() によって作られたプロキシかどうかをチェックします。

  • ts
    function isProxy(value: unknown): boolean
    

isReactive()

オブジェクトが reactive() または shallowReactive() によって作られたプロキシかどうかをチェックします。

  • ts
    function isReactive(value: unknown): boolean
    

isReadonly()

渡された値が読み取り専用オブジェクトであるかどうかをチェックします。読み取り専用オブジェクトのプロパティは変更可能ですが、渡されたオブジェクトを経由して直接代入することはできません。

readonly()shallowReadonly() で作成したプロキシは、set 関数なしの computed() ref と同様に読み取り専用と見なされます。

  • ts
    function isReadonly(value: unknown): boolean
    
リアクティビティー API: ユーティリティーが読み込まれました