Skip to content

Reactivity API: Утилиты

isRef()

Проверяет, является ли значение ref-объектом.

  • Тип

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

    Обратите внимание, что возвращаемый тип является предикатом типа, поэтому isRef может быть использован как type guard:

    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 теперь гарантированно имеет числовой тип
    }

toRef()

Может использоваться для нормализации значений / ref-объектов / геттеров к ref-ссылкам (3.3+).

Может использоваться для создания ref-ссылки на свойство исходного реактивного объекта. Созданная ref-ссылка синхронизируется с исходным свойством: изменение свойства в исходном объекте приведет к обновлению ref-ссылки и наоборот.

  • Тип

    ts
    // сигнатура нормализации (3.3+)
    function toRef<T>(
      value: T
    ): T extends () => infer R
      ? Readonly<Ref<R>>
      : T extends Ref
      ? T
      : Ref<UnwrapRef<T>>
    
    // сигнатура свойства объекта
    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>
  • Пример

    Сигнатура нормализации (3.3+):

    js
    // возвращает существующие ref-объекты как есть
    toRef(existingRef)
    
    // создает ref-ссылку только для чтения, которая вызывает геттер при обращении к .value
    toRef(() => props.foo)
    
    // создает нормальную ref-ссылку для значений, кроме функций
    // эквивалент для ref(1)
    toRef(1)

    Сигнатура свойства объекта:

    js
    const state = reactive({
      foo: 1,
      bar: 2
    })
    
    // двусторонняя ref-ссылка, которая синхронизируется с исходным свойством
    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-ссылка не синхронизируется с state.foo, потому что ref() получает обычное числовое значение.

    Функция toRef() полезна, когда вы хотите передать ref-ссылку входного параметра в composable-функцию:

    vue
    <script setup>
    import { toRef } from 'vue'
    
    const props = defineProps(/* ... */)
    
    // преобразуем `props.foo` в ref-ссылку, и затем передаем
    // в composable-функцию
    useSomeFeature(toRef(props, 'foo'))
    
    // синтаксис геттера - рекомендовано в 3.3+
    useSomeFeature(toRef(() => props.foo))
    </script>

    Когда toRef используется с входными параметрами компонента, обычные ограничения на изменение входных параметров остаются в силе. Попытка присвоить новое значение ref-ссылке эквивалентна попытке изменить входные параметры напрямую, что в свою очередь - не допустимо. В этом случае вы можете рассмотреть возможность использования computed с get и set вместо этого. Для получения дополнительной информации смотрите руководство по использованию v-model в компонентах.

    При использовании сигнатуры свойства объекта, toRef() вернет пригодную для использования ref-ссылку, даже если исходное свойство в данный момент не существует. Это позволяет работать с опциональными свойствами, которые не были бы подхвачены toRefs.

toValue()

  • Поддерживается только в версиях 3.3+

Нормализует значения / ref-объекты / геттеры к значениям. Это похоже на unref(), с той лишь разницей, что оно также нормализует геттеры. Если аргумент является геттером, то он будет вызван, и будет возвращено его возвращаемое значение.

Это можно использовать в composable-функциях для нормализации аргумента, который может быть значением, ref-объектом или геттером.

  • Тип

    ts
    function toValue<T>(source: T | Ref<T> | (() => T)): T
  • Пример

    js
    toValue(1) //       --> 1
    toValue(ref(1)) //  --> 1
    toValue(() => 1) // --> 1

    Нормализация аргументов в composable-функциях:

    ts
    import type { MaybeRefOrGetter } from 'vue'
    
    function useFeature(id: MaybeRefOrGetter<number>) {
      watch(
        () => toValue(id),
        id => {
          // реагировать на изменения id
        }
      )
    }
    
    // эта composable-функция поддерживает что-либо из следующего:
    useFeature(1)
    useFeature(ref(1))
    useFeature(() => 1)

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)
    /*
    Type of 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 полезно использовать при возвращении реактивного объекта из composable-функции, чтобы использующий функцию компонент мог деструктурировать возвращенный объект без потери реактивности:

    js
    function useFeatureX() {
      const state = reactive({
        foo: 1,
        bar: 2
      })
    
      // ...логика, работающая с состоянием
    
      // создание ref-ссылок при возвращении
      return toRefs(state)
    }
    
    // может быть деструктурировано без потери реактивности
    const { foo, bar } = useFeatureX()

    toRefs будет генерировать ссылки только для тех свойств, которые являются перечислимыми для исходного объекта на момент вызова. Чтобы создать ссылку для свойства, которое может еще не существовать, используйте toRef.

isProxy()

Проверяет, является ли объект прокси, созданным с помощью reactive(), readonly(), shallowReactive() или shallowReadonly().

  • Тип

    ts
    function isProxy(value: any): boolean

isReactive()

Проверяет, является ли объект прокси, созданным reactive() или shallowReactive().

  • Тип

    ts
    function isReactive(value: unknown): boolean

isReadonly()

Проверяет, является ли переданное значение объектом только для чтения. Свойства объекта только для чтения могут изменяться, но их нельзя присвоить напрямую через переданный объект.

Прокси, созданные readonly() и shallowReadonly(), считаются доступными только для чтения, как и ref-ссылка computed() без функции set.

  • Тип

    ts
    function isReadonly(value: unknown): boolean
Reactivity API: УтилитыУже загружено