[Vue.js 3.0] API – Refs

# Refs

This section uses single-file component syntax for code examples

# ref

Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property .value that points to the inner value.


const count = ref(0)
console.log(count.value) // 0
console.log(count.value) // 1

If an object is assigned as a ref's value, the object is made deeply reactive by the reactive method.


interface Ref<T> {
value: T
function ref<T>(value: T): Ref<T>

Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling ref to override the default inference:

const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
foo.value = 123 // ok!

If the type of the generic is unknown, it's recommended to cast ref to Ref<T>:

function useState<State extends string>(initial: State) {
const state = ref(initial) as Ref<State> // state.value -> State extends string
return state

# unref

Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for val = isRef(val) ? val.value : val.

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

# toRef

Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.

const state = reactive({
foo: 1,
bar: 2
const fooRef = toRef(state, 'foo')
console.log(state.foo) // 2
console.log(fooRef.value) // 3

toRef is useful when you want to pass the ref of a prop to a composition function:

export default {
setup(props) {
useSomeFeature(toRef(props, 'foo'))

toRef will return a usable ref even if the source property doesn't currently exist. This makes it especially useful when working with optional props, which wouldn't be picked up by toRefs.

# toRefs

Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.

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"
console.log(stateAsRefs.foo.value) // 2
console.log(state.foo) // 3

toRefs is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:

function useFeatureX() {
const state = reactive({
foo: 1,
bar: 2
// logic operating on state
// convert to refs when returning
return toRefs(state)
export default {
setup() {
// can destructure without losing reactivity
const { foo, bar } = useFeatureX()
return {

toRefs will only generate refs for properties that are included in the source object. To create a ref for a specific property use toRef instead.

# isRef

Checks if a value is a ref object.

# customRef

Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives track and trigger functions as arguments and should return an object with get and set.

  • Example using a custom ref to implement debounce with v-model:

    <input v-model="text" />
    function useDebouncedRef(value, delay = 200) {
    let timeout
    return customRef((track, trigger) => {
    return {
    get() {
    return value
    set(newValue) {
    timeout = setTimeout(() => {
    value = newValue
    }, delay)
    export default {
    setup() {
    return {
    text: useDebouncedRef('hello')


function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
type CustomRefFactory<T> = (
track: () => void,
trigger: () => void
) => {
get: () => T
set: (value: T) => void

# shallowRef

Creates a ref that tracks its own .value mutation but doesn't make its value reactive.

const foo = shallowRef({})
// mutating the ref's value is reactive
foo.value = {}
// but the value will not be converted.
isReactive(foo.value) // false

See also: Creating Standalone Reactive Values as refs

# triggerRef

Execute any effects tied to a shallowRef manually.

const shallow = shallowRef({
greet: 'Hello, world'
// Logs "Hello, world" once for the first run-through
watchEffect(() => {
// This won't trigger the effect because the ref is shallow
shallow.value.greet = 'Hello, universe'
// Logs "Hello, universe"

See also: Computed and Watch - watchEffect

以上是[Vue.js 3.0] API – Refs的全部内容。
< <上一篇