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-modelsans nom sur un composant. Son pendant est l'événementupdate: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 unerefmodifiable.- Modèle nommé
v-model:titrecô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.
defineModeln'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. LarefdedefineModeldevient 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
computedavecgetetset, lesetémettant l'événement.
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.