Formations — 1 037 leçons en français

Accueil › Vue.js › v-model sur un champ de formulaire

v-model sur un champ de formulaire

Événements et formulairesdebutant

v-model relie un champ de formulaire à une donnée réactive, dans les deux sens. Ce n'est pas une primitive : le compilateur le remplace par une liaison d'attribut et un écouteur d'événement.

<script setup>
import { ref } from 'vue'
const pseudo = ref('')
</script>

<template>
  <input v-model="pseudo" />
  <!-- strictement équivalent à : -->
  <input :value="pseudo" @input="pseudo = $event.target.value" />
  <p>Bonjour {{ pseudo }}</p>
</template>

Le couple exact dépend du type de champ : :value et @input pour un texte ou un textarea, :checked et @change pour une case à cocher ou un bouton radio, :value et @change pour un select.

Conséquence immédiate : l'état est la source de vérité. v-model ignore les attributs value, checked et selected écrits dans le gabarit. Une valeur par défaut se déclare dans le ref, jamais dans le HTML.

<script setup>
import { ref } from 'vue'
const accepte = ref(false)
const langue = ref('fr')
const sujets = ref([])
</script>

<template>
  <input type="checkbox" v-model="accepte" />

  <input type="radio" value="fr" v-model="langue" />
  <input type="radio" value="en" v-model="langue" />

  <input type="checkbox" value="vue" v-model="sujets" />
  <input type="checkbox" value="vite" v-model="sujets" />

  <select v-model="langue">
    <option value="fr">Français</option>
    <option value="en">English</option>
  </select>
</template>

Une case à cocher seule donne un booléen. Plusieurs cases liées au même tableau y déposent leur value. Un groupe de radios donne la value du bouton sélectionné.

Les termes à connaître

Liaison bidirectionnelle

Un raccourci qui relie une donnée et un champ dans les deux sens. Vue ne l'implémente pas magiquement : il écrit pour vous une liaison d'attribut et un écouteur d'événement.

v-model

La directive qui produit ce couple. Sur un input texte elle devient :value plus @input ; sur une case à cocher :checked plus @change.

true-value / false-value

Deux attributs qui remplacent true et false par les valeurs de votre choix sur une case à cocher unique. Ils n'existent que pour v-model.

Groupe de cases

Plusieurs cases à cocher liées au même tableau. Vue y ajoute ou retire la value de chaque case ; l'ordre obtenu est celui du gabarit, pas celui des clics.

Valeur dynamique

:value sur un option ou un radio permet de lier autre chose qu'une chaîne — un nombre, un objet. Sans les deux-points, le navigateur n'a que du texte à offrir.

Source de vérité

L'état JavaScript. v-model ignore les attributs value, checked et selected écrits dans le gabarit : c'est la donnée qui décide de l'affichage initial.

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.