Fondamentaux de la réactivité ​

Déclarer un état réactif ​

ref() ​

Avec la Composition API, la méthode recommandée pour déclarer l'état réactif consiste à utiliser la fonction ref() :

import { ref } from 'vue'

const count = ref(0)

ref() prend l'argument et le renvoie enveloppé dans un objet ref avec une propriété .value :

const count = ref(0)

console.log(count) // { value: 0 }
console.log(count.value) // 0

count.value++
console.log(count.value) // 1

Voir aussi : Typer les variables réactives

Pour utiliser un état réactif dans le template d'un composant, déclarez et renvoyez-le depuis la fonction setup() du composant :

import { ref } from 'vue'

export default {
  // `setup` est un hook spécial dédié à la Composition API.
  setup() {
    const count = ref(0)

    // expose l'état au template
    return {
      count
    }
  }
}

<div>{{ count }}</div>

Notez que nous n'avons pas besoin d'ajouter .value lors de l'utilisation de la ref dans le template. Pour plus de commodité, les refs sont automatiquement déballées lorsqu'elles sont utilisées dans des templates (avec quelques pièges).

Vous pouvez également muter une ref directement dans les gestionnaires d'événements :

<button @click="count++">
  {{ count }}
</button>

Pour une logique plus complexe, nous pouvons déclarer des fonctions qui modifient les ref dans la même portée et les exposer en tant que méthodes à côté de l'état :

import { ref } from 'vue'

export default {
  setup() {
    const count = ref(0)

    function increment() {
      // .value est nécessaire en JavaScript
      count.value++
    }

    // n'oubliez pas d'également exposer la fonction.
    return {
      count,
      increment
    }
  }
}

Les méthodes exposées sont généralement utilisées comme écouteurs d'événements :

<button @click="increment">
  {{ count }}
</button>

Voici l'exemple sur Codepen, sans utiliser d'outils de build.

<script setup> ​

Exposer manuellement l'état et les méthodes via setup() peut être verbeux. Heureusement, cela peut être évité avec l'utilisation de composants monofichiers (SFC). Nous pouvons simplifier l'utilisation avec <script setup> :

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

const count = ref(0)

function increment() {
  count.value++
}
</script>

<template>
  <button @click="increment">
    {{ count }}
  </button>
</template>

Essayer en ligne

Les importations de premier niveau et les variables déclarées dans <script setup> sont automatiquement utilisables dans le template du même composant. Considérez le template comme une fonction JavaScript déclarée dans la même portée - il a naturellement accès à tout ce qui est déclaré à ses côtés.

Why Refs? ​

You might be wondering why we need refs with the .value instead of plain variables. To explain that, we will need to briefly discuss how Vue's reactivity system works.

When you use a ref in the template, and changes the ref's value later, Vue automatically detects the change and updates the DOM accordingly. This is made possible with a dependency-tracking based reactivity system. When a component is rendered for the first time, Vue tracks every ref that was used during the render. Later on, when a ref is mutated, it will trigger re-render for components that are tracking it.

In standard JavaScript, there is no way to detect the access or mutation of plain variables. But we can intercept a property's get and set operations.

The .value property gives Vue the opportunity to detect when a ref has been accessed or mutated. Under the hood, Vue performs the tracking in its getter, and performs triggering in its setter. Conceptually, you can think of a ref as an object that looks like this:

// pseudo code, not actual implementation
const myRef = {
  _value: 0,
  get value() {
    track()
    return this._value
  },
  set value(newValue) {
    this._value = newValue
    trigger()
  }
}

Another nice trait of refs is that unlike plain variables, you can pass refs into functions while retaining access to the latest value and the reactivity connection. This is particularly useful when refactoring complex logic into reusable code.

The reactivity system is discussed in more details in the Reactivity in Depth section.

Refs can hold any value type, including deeply nested objects, arrays, or JavaScript built-in data structures like Map.

A ref will make its value deeply reactive. This means you can expect changes to be detected even when you mutate nested objects or arrays:

import { ref } from 'vue'

const obj = ref({
  nested: { count: 0 },
  arr: ['foo', 'bar']
})

function mutateDeeply() {
  // cela va fonctionner comme prévu.
  obj.value.nested.count++
  obj.value.arr.push('baz')
}

Non-primitive values are turned into reactive proxies via reactive(), which is discussed below.

It is also possible to opt-out of deep reactivity with shallow refs. For shallow refs, only .value access is tracked for reactivity. Shallow refs can be used for optimizing performance by avoiding the observation cost of large objects, or in cases where the inner state is managed by an external library.

Further reading:

• Reduce Reactivity Overhead for Large Immutable Structures
• Integration with External State Systems

reactive() ​

There is another way to declare reactive state, with the reactive() API. Unlike a ref which wraps the inner value in a special object, reactive() makes an object itself reactive:

import { reactive } from 'vue'

const state = reactive({ count: 0 })

See also: Typing Reactive

Usage in template:

<button @click="state.count++">
  {{ state.count }}
</button>

Les objets réactifs sont des proxys JavaScript et se comportent comme des objets classiques. La différence est que Vue est capable de traquer l'accès aux propriétés et les mutations d'un objet réactif.

reactive() converts the object deeply: nested objects are also wrapped with reactive() when accessed. It is also called by ref() internally when the ref value is an object. Similar to shallow refs, there is also the shallowReactive() API for opting-out of deep reactivity.

Proxy réactif vs. original ​

Il est important de noter que la valeur retournée par reactive() est un proxy de l'objet original, qui n'est pas égal à l'objet original :

const raw = {}
const proxy = reactive(raw)

// le proxy n'est PAS égal à l'original.
console.log(proxy === raw) // faux

Seul le proxy est réactif - muter l'objet original ne déclenchera pas de mises à jour. Par conséquent, la meilleure pratique pour travailler avec le système de réactivité de Vue est d'utiliser exclusivement les versions proxifiées de votre état.

Pour assurer un accès cohérent au proxy, appeler reactive() sur le même objet retournera toujours le même proxy, et appeler reactive() sur un proxy existant retournera également ce même proxy :

// appeler reactive() sur le même objet retourne le même proxy
console.log(reactive(raw) === proxy) // true

// appeler reactive() sur un proxy se retourne lui-même
console.log(reactive(proxy) === proxy) // vrai

Cette règle s'applique tout aussi bien aux objets imbriqués. En raison de la réactivité profonde, les objets imbriqués à l'intérieur d'un objet réactif sont également des proxys :

const proxy = reactive({})

const raw = {}
proxy.nested = raw

console.log(proxy.nested === raw) // false

Limitations de reactive() ​

L'API reactive() a deux limitations :

1. Types limités : Elle ne fonctionne que pour les types d'objets (objets, tableaux et objets de type collections tels que Map et Set). Elle ne peut pas contenir les types primitifs tels que string, number ou boolean.

2. Remplacement impossible de l'intégralité de l'objet : Comme le suivi de la réactivité de Vue fonctionne sur l'accès aux propriétés, nous devons toujours conserver la même référence à l'objet réactif. Cela signifie que nous ne pouvons pas facilement "remplacer" un objet réactif car la connexion de réactivité à la première référence serait perdue :

   js

   let state = reactive({ count: 0 })
   
   // la référence précédente ({ count: 0 }) n'est plus suivie 
   // (la connexion de réactivité est perdue !)
   state = reactive({ count: 1 })

3. Ne fonctionne pas avec la destructuration : lorsque nous déstructurons la propriété d'un objet réactif en variables locales, ou lorsque nous passons cette propriété dans une fonction, nous perdons la connexion à la réactivité :

   js

   const state = reactive({ count: 0 })
   
   // count est déconnecté de state.count lorsqu'il est déstructuré.
   let { count } = state
   // n'affecte pas l'état original
   count++
   
   // la fonction reçoit un simple nombre et
   // ne sera pas capable de traquer les changements de state.count
   // nous devons passer l'objet entier pour conserver la réactivité
   callSomeFunction(state.count)

À cause de ces limites, nous recommandons l'usage de ref() en tant qu'API principale pour déclarer un état réactif.

As Reactive Object Property ​

A ref is automatically unwrapped when accessed or mutated as a property of a reactive object. In other words, it behaves like a normal property :

const count = ref(0)
const state = reactive({
  count
})

console.log(state.count) // 0

state.count = 1
console.log(count.value) // 1

If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:

const otherCount = ref(2)

state.count = otherCount
console.log(state.count) // 2
// original ref is now disconnected from state.count
console.log(count.value) // 1

Ref unwrapping only happens when nested inside a deep reactive object. It does not apply when it is accessed as a property of a shallow reactive object.

Pièges lors de déballage de tableaux et collections ​

Unlike reactive objects, there is no unwrapping performed when the ref is accessed as an element of a reactive array or a native collection type like Map:

const books = reactive([ref('Vue 3 Guide')])
// need .value here
console.log(books[0].value)

const map = reactive(new Map([['count', ref(0)]]))
// need .value here
console.log(map.get('count').value)

Ref unwrapping in templates only applies if the ref is a top-level property in the template render context.

In the example below, count and object are top-level properties, but object.id is not:

const count = ref(0)
const object = { id: ref(0) }

Therefore, this expression works as expected:

{{ count + 1 }}

...while this one does NOT:

{{ object.id + 1 }}

The rendered result will be [object Object]1 because object.id is not unwrapped when evaluating the expression and remains a ref object. To fix this, we can destructure id into a top-level property:

const { id } = object

{{ id + 1 }}

Désormais le résultat rendu sera 2.

Another thing to note is that a ref does get unwrapped if it is the final evaluated value of a text interpolation (i.e. a {{ }} tag), so the following will render 1:

{{ object.id }}

This is just a convenience feature of text interpolation and is equivalent to {{ object.id.value }}.