Formations — 1 037 leçons en français

Accueil › Vue.js › Les refs de template

Les refs de template

La Composition APIintermediaire

Parfois il faut l'élément lui-même : donner le focus, mesurer une hauteur, piloter une bibliothèque de graphiques. L'attribut ref dans le template crée ce lien.

Depuis Vue 3.5, la forme recommandée est useTemplateRef :

<script setup>
import { useTemplateRef, onMounted } from 'vue'

const champ = useTemplateRef('saisie')
onMounted(() => champ.value.focus())
</script>

<template>
  <input ref="saisie">
</template>

La forme historique reste valide : on déclare une ref dont le nom de variable correspond exactement à la chaîne de l'attribut.

<script setup>
import { ref, onMounted } from 'vue'
const saisie = ref(null)
onMounted(() => saisie.value.focus())
</script>

<template>
  <input ref="saisie">
</template>

La règle qui vaut pour les deux : la valeur n'existe qu'après le montage. Avant, elle vaut ce qu'on a mis à l'initialisation — null dans la forme homonyme. Après le démontage, Vue la remet à null.

Sur un composant enfant, ref donne l'instance. Si cet enfant est écrit avec <script setup>, elle est vide : il faut un defineExpose côté enfant pour que le parent voie quoi que ce soit.

Les termes à connaître

Ref de template

Une référence directe vers un élément du DOM ou une instance de composant, obtenue par l'attribut ref dans le template.

useTemplateRef

La fonction introduite en Vue 3.5 qui renvoie une ref liée à un attribut ref nommé, sans contrainte de nom de variable.

Ref homonyme

La façon historique de récupérer un élément : déclarer une ref dont le nom de variable est exactement la chaîne écrite dans l'attribut ref.

Disponibilité au montage

Le fait qu'une ref de template vaut null tant que le composant n'est pas monté, et redevient null au démontage.

Ref de fonction

La forme :ref="(element) => ..." : Vue appelle la fonction avec l'élément au montage, puis avec null au démontage.

defineExpose

La macro qui déclare ce qu'un parent peut atteindre à travers une ref pointant vers un composant <script setup>.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.