Reactivity API: Утилиты
isRef()
Проверяет, является ли значение ref-объектом.
Тип
tsfunction isRef<T>(r: Ref<T> | unknown): r is Ref<T>
Обратите внимание, что возвращаемый тип является предикатом типа, поэтому
isRef
может быть использован какtype guard
:tslet foo: unknown if (isRef(foo)) { // тип foo сужен до Ref<unknown> foo.value }
unref()
Возвращает внутреннее значение, если аргумент является ref-объектом, в противном случае возвращает сам аргумент. Функция является синтаксическим сахаром для val = isRef(val) ? val.value : val
.
Тип
tsfunction unref<T>(ref: T | Ref<T>): T
Пример
tsfunction 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)
Сигнатура свойства объекта:
jsconst 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
Обратите внимание, что это отличается от:
jsconst 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-объектом или геттером.
Тип
tsfunction toValue<T>(source: T | Ref<T> | (() => T)): T
Пример
jstoValue(1) // --> 1 toValue(ref(1)) // --> 1 toValue(() => 1) // --> 1
Нормализация аргументов в composable-функциях:
tsimport 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()
.
Тип
tsfunction toRefs<T extends object>( object: T ): { [K in keyof T]: ToRef<T[K]> } type ToRef = T extends Ref ? T : Ref<T>
Пример
jsconst 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-функции, чтобы использующий функцию компонент мог деструктурировать возвращенный объект без потери реактивности:jsfunction useFeatureX() { const state = reactive({ foo: 1, bar: 2 }) // ...логика, работающая с состоянием // создание ref-ссылок при возвращении return toRefs(state) } // может быть деструктурировано без потери реактивности const { foo, bar } = useFeatureX()
toRefs
будет генерировать ссылки только для тех свойств, которые являются перечислимыми для исходного объекта на момент вызова. Чтобы создать ссылку для свойства, которое может еще не существовать, используйтеtoRef
.
isProxy()
Проверяет, является ли объект прокси, созданным с помощью reactive()
, readonly()
, shallowReactive()
или shallowReadonly()
.
Тип
tsfunction isProxy(value: any): boolean
isReactive()
Проверяет, является ли объект прокси, созданным reactive()
или shallowReactive()
.
Тип
tsfunction isReactive(value: unknown): boolean
isReadonly()
Проверяет, является ли переданное значение объектом только для чтения. Свойства объекта только для чтения могут изменяться, но их нельзя присвоить напрямую через переданный объект.
Прокси, созданные readonly()
и shallowReadonly()
, считаются доступными только для чтения, как и ref-ссылка computed()
без функции set
.
Тип
tsfunction isReadonly(value: unknown): boolean