响应性API: 工具

isRef()

检查一个值是否为ref对象。

类型

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

注意返回类型是一个类型守卫，这意味着 isRef 可以用作类型守卫

let foo: unknown
if (isRef(foo)) {
  // foo's type is narrowed to Ref<unknown>
  foo.value
}

unref()

如果参数是ref，则返回内部值，否则返回参数本身。这是一个简写函数，相当于 val = isRef(val) ? val.value : val。

类型
ts
```
function unref<T>(ref: T | Ref<T>): T
```

示例

function useFoo(x: number | Ref<number>) {
  const unwrapped = unref(x)
  // unwrapped is guaranteed to be number now
}

toRef()

可以用于将值 / refs / getters 规范化为refs（3.3+）。

也可以用于为源响应式对象的属性创建一个ref。创建的ref与其源属性同步：修改源属性将更新ref，反之亦然。

类型

// normalization signature (3.3+)
function toRef<T>(
  value: T
): T extends () => infer R
  ? Readonly<Ref<R>>
  : T extends Ref
  ? T
  : Ref<UnwrapRef<T>>

// object property signature
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+）

// returns existing refs as-is
toRef(existingRef)

// creates a readonly ref that calls the getter on .value access
toRef(() => props.foo)

// creates normal refs from non-function values
// equivalent to ref(1)
toRef(1)

对象属性签名

const state = reactive({
  foo: 1,
  bar: 2
})

// a two-way ref that syncs with the original property
const fooRef = toRef(state, 'foo')

// mutating the ref updates the original
fooRef.value++
console.log(state.foo) // 2

// mutating the original also updates the ref
state.foo++
console.log(fooRef.value) // 3

注意这与

const fooRef = ref(state.foo)

上面的引用没有与 state.foo 同步，因为 ref() 接收的是纯数字值。

toRef() 当你想将属性的引用传递给组合函数时很有用。

vue

<script setup>
import { toRef } from 'vue'

const props = defineProps(/* ... */)

// convert `props.foo` into a ref, then pass into
// a composable
useSomeFeature(toRef(props, 'foo'))

// getter syntax - recommended in 3.3+
useSomeFeature(toRef(() => props.foo))
</script>

当与组件属性一起使用 toRef 时，仍然适用关于修改属性的限制。尝试为引用分配新值相当于尝试直接修改属性，并且是不允许的。在这种情况下，你可能需要考虑使用带有 get 和 set 的 computed。有关更多信息，请参阅使用 v-model 与组件的指南。

当使用对象属性签名时，即使源属性当前不存在，toRef() 也会返回一个可用的引用。这使得可以处理可选属性，这些属性不会被 toRefs 捕获。

toValue()

仅支持在 3.3+ 中。

将值、引用和获取器标准化为值。这与 unref() 类似，但还标准化了获取器。如果参数是获取器，它将被调用，并返回其返回值。

这可以在组合式中使用，以标准化可以是值、引用或获取器的参数。

类型

function toValue<T>(source: T | Ref<T> | (() => T)): T

示例

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

在组合式中标准化参数

import type { MaybeRefOrGetter } from 'vue'

function useFeature(id: MaybeRefOrGetter<number>) {
  watch(() => toValue(id), id => {
    // react to id changes
  })
}

// this composable supports any of the following:
useFeature(1)
useFeature(ref(1))
useFeature(() => 1)

toRefs()

将响应式对象转换为普通对象，其中结果对象的每个属性都是指向原始对象相应属性的引用。每个单独的引用都是使用 toRef() 创建的。

类型

function toRefs<T extends object>(
  object: T
): {
  [K in keyof T]: ToRef<T[K]>
}

type ToRef = T extends Ref ? T : Ref<T>

示例

const state = reactive({
  foo: 1,
  bar: 2
})

const stateAsRefs = toRefs(state)
/*
Type of stateAsRefs: {
  foo: Ref<number>,
  bar: Ref<number>
}
*/

// The ref and the original property is "linked"
state.foo++
console.log(stateAsRefs.foo.value) // 2

stateAsRefs.foo.value++
console.log(state.foo) // 3

toRefs 当从组合函数返回响应式对象时很有用，这样消耗组件就可以解构/展开返回的对象，而不会丢失响应性。

function useFeatureX() {
  const state = reactive({
    foo: 1,
    bar: 2
  })

  // ...logic operating on state

  // convert to refs when returning
  return toRefs(state)
}

// can destructure without losing reactivity
const { foo, bar } = useFeatureX()

toRefs 将只为在调用时在源对象上是可枚举的属性生成引用。要为可能还不存在的属性创建引用，请使用 toRef。

isProxy()

检查一个对象是否是由 reactive()、readonly()、shallowReactive() 或 shallowReadonly() 创建的代理。

类型
ts
```
function isProxy(value: any): boolean
```

isReactive()

检查一个对象是否是由 reactive() 或 shallowReactive() 创建的代理。

类型

function isReactive(value: unknown): boolean

isReadonly()

检查传入的值是否是只读对象。只读对象的属性可以更改，但无法通过传入的对象直接赋值。

readonly() 和 shallowReadonly() 创建的代理都被认为是只读的，就像没有 set 函数的 computed 引用一样。

类型

function isReadonly(value: unknown): boolean

在 GitHub 上编辑此页面

响应性API: 工具 ​

isRef() ​

unref() ​

toRef() ​

toValue() ​

toRefs() ​

isProxy() ​

isReactive() ​

isReadonly() ​