Formations — 1 037 leçons en français

Accueil › Vue.js › v-model sur un composant

v-model sur un composant

Événements et formulairesdebutant

Un composant peut se brancher sur v-model comme un champ natif. Le contrat est simple : il reçoit une propriété, il émet un événement.

<!-- Parent.vue -->
<Champ v-model="pseudo" />

<!-- strictement équivalent à : -->
<Champ :model-value="pseudo" @update:model-value="pseudo = $event" />

Depuis Vue 3.4, l'enfant déclare les deux extrémités d'un seul geste avec la macro defineModel(), disponible dans <script setup> :

<!-- Champ.vue -->
<script setup>
const valeur = defineModel()
</script>

<template>
  <input v-model="valeur" />
</template>

defineModel() renvoie une ref. La lire donne la valeur transmise par le parent ; l'écrire émet update:modelValue, que le parent attrape grâce à son v-model. Le flux reste celui de Vue : une propriété descend, un événement remonte — la macro écrit la plomberie à votre place.

Un composant peut exposer plusieurs modèles, chacun nommé :

<!-- Parent.vue -->
<Periode v-model:debut="du" v-model:fin="au" />

<!-- Periode.vue -->
<script setup>
const debut = defineModel('debut')
const fin = defineModel('fin')
</script>

Le nom gouverne les deux côtés : defineModel('debut') déclare la propriété debut et l'événement update:debut.

Les termes à connaître

modelValue

La propriété que le parent transmet quand il écrit v-model sans nom sur un composant. Son pendant est l'événement update:modelValue.

defineModel()

La macro de <script setup>, stable depuis Vue 3.4, qui déclare la propriété et l'événement d'un coup et renvoie une ref modifiable.

Modèle nommé

v-model:titre côté parent, defineModel('titre') côté enfant. Un composant peut en exposer plusieurs, chacun avec son couple propriété/événement.

Flux descendant

La règle de Vue : une propriété descend, un événement remonte. defineModel n'y déroge pas, il écrit l'événement à votre place.

Propriété non liée

Le cas où le parent n'écrit pas de v-model. La ref de defineModel devient alors un état local, et sa valeur n'est plus synchronisée avec personne.

computed accesseur

La façon d'écrire un modèle avant Vue 3.4, ou quand on veut transformer la valeur : un computed avec get et set, le set émettant l'événement.

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.