Liaisons des entrées utilisateur d'un formulaire #

Lorsque nous devons gérer des formulaires côté front, il arrive souvent que nous ayons besoin de synchroniser l'état des éléments de saisi du formulaire avec l'état correspondant en JavaScript. Cela peut être encombrant de connecter les liaisons des valeurs et de changer les écouteurs d'événements :

<input
  :value="text"
  @input="event => text = event.target.value">

La directive v-model nous aide à simplifier le code ci-dessus par :

<input v-model="text">

De plus, v-model peut être utilisé sur des entrées de différents types, des éléments <textarea>, et <select>. Il s'étend automatiquement aux différentes paires de propriétés et d'événements du DOM en fonction de l'élément sur lequel il est utilisé :

• Les éléments <input> de type texte et <textarea> utilisent la propriété value et l'événement input ;
• <input type="checkbox"> et <input type="radio"> utilisent la propriété checked et l'événement change ;
• <select> utilise value comme prop et change comme événement.

Utilisation basique #

Texte #

<p>Message is: {{ message }}</p>
<input v-model="message" placeholder="edit me" />

Texte multiligne #

<span>Multiline message is:</span>
<p style="white-space: pre-line;">{{ message }}</p>
<textarea v-model="message" placeholder="add multiple lines"></textarea>

Notez que l'interpolation à l'intérieur de <textarea> ne fonctionnera pas. Utilisez v-model à la place.

<!-- À éviter -->
<textarea>{{ text }}</textarea>

<!-- OK -->
<textarea v-model="text"></textarea>

Checkbox #

Case à cocher unique, valeur booléenne :

<input type="checkbox" id="checkbox" v-model="checked" />
<label for="checkbox">{{ checked }}</label>

Nous pouvons également lier plusieurs cases à cocher au même tableau ou à la même valeur Set :

const checkedNames = ref([])

export default {
  data() {
    return {
      checkedNames: []
    }
  }
}

<div>Checked names: {{ checkedNames }}</div>

<input type="checkbox" id="jack" value="Jack" v-model="checkedNames">
<label for="jack">Jack</label>

<input type="checkbox" id="john" value="John" v-model="checkedNames">
<label for="john">John</label>

<input type="checkbox" id="mike" value="Mike" v-model="checkedNames">
<label for="mike">Mike</label>

Dans ce cas, le tableau checkedNames contiendra toujours les valeurs des cases qui sont actuellement cochées.

Radio #

<div>Picked: {{ picked }}</div>

<input type="radio" id="one" value="One" v-model="picked" />
<label for="one">One</label>

<input type="radio" id="two" value="Two" v-model="picked" />
<label for="two">Two</label>

Select #

Simple select :

<div>Selected: {{ selected }}</div>

<select v-model="selected">
  <option disabled value="">Please select one</option>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>

Plusieurs select (liés à un tableau):

<div>Selected: {{ selected }}</div>

<select v-model="selected" multiple>
  <option>A</option>
  <option>B</option>
  <option>C</option>
</select>

Les options d'un select peuvent être rendues de manière dynamique avec v-for :

const selected = ref('A')

const options = ref([
  { text: 'One', value: 'A' },
  { text: 'Two', value: 'B' },
  { text: 'Three', value: 'C' }
])

export default {
  data() {
    return {
      selected: 'A',
      options: [
        { text: 'One', value: 'A' },
        { text: 'Two', value: 'B' },
        { text: 'Three', value: 'C' }
      ]
    }
  }
}

<select v-model="selected">
  <option v-for="option in options" :value="option.value">
    {{ option.text }}
  </option>
</select>

<div>Selected: {{ selected }}</div>

Liaisons d'une valeur #

Pour les options de type radio, checkbox et select, les valeurs de liaison du v-model sont généralement des chaînes de caractères statiques (ou des booléens pour les checkbox) :

<!-- `picked` est une chaîne de caractères valant "a" lorsqu'il est sélectionné -->
<input type="radio" v-model="picked" value="a" />

<!-- `toggle` peut être vrai ou faux -->
<input type="checkbox" v-model="toggle" />

<!-- `selected` est une chaîne de caractères valant "abc" lorsque la première option est sélectionnée -->
<select v-model="selected">
  <option value="abc">ABC</option>
</select>

Mais parfois, il peut arriver que nous voulions lier la valeur à une propriété dynamique sur l'instance actuellement active. Nous pouvons utiliser v-bind pour ce faire. De plus, l'utilisation de v-bind nous permet de lier la valeur d'entrée à des valeurs autres que des chaînes de caractères.

Checkbox #

<input
  type="checkbox"
  v-model="toggle"
  true-value="yes"
  false-value="no" />

true-value et false-value sont des attributs spécifiques à Vue qui ne fonctionnent qu'avec v-model. Ici, la valeur de la propriété toggle sera définie à 'yes' lorsque la case est cochée, et à 'no' lorsqu'elle est décochée. Vous pouvez également les lier à des valeurs dynamiques en utilisant v-bind :

<input
  type="checkbox"
  v-model="toggle"
  :true-value="dynamicTrueValue"
  :false-value="dynamicFalseValue" />

Radio #

<input type="radio" v-model="pick" :value="first" />
<input type="radio" v-model="pick" :value="second" />

pick prendra la valeur first lorsque la première entrée radio sera cochée, et prendra la valeur second lorsque la seconde sera cochée.

Options de select #

<select v-model="selected">
  <!-- inline object literal -->
  <option :value="{ number: 123 }">123</option>
</select>

v-model supporte également les liaisons de valeurs autres que des chaînes de caractères ! Dans l'exemple précédent, lorsque l'option est sélectionnée, selected sera défini comme la valeur littérale de l'objet { number : 123 }.

Modificateurs #

.lazy #

Par défaut, v-model synchronise l'entrée avec les données après chaque événement input (à l'exception de la composition IME comme indiqué ci-dessus). Vous pouvez ajouter le modificateur lazy pour enclencher la synchronisation après les événements change :

<!-- synchronisé après "change" au lieu de "input" -->
<input v-model.lazy="msg" />

.number #

Si vous voulez que l'entrée de l'utilisateur soit automatiquement typée comme un nombre, vous pouvez ajouter le modificateur number à vos entrées gérées par v-model :

<input v-model.number="age" />

Si la valeur ne peut pas être analysée avec parseFloat(), alors la valeur originale est utilisée à la place.

Le modificateur number est appliqué automatiquement si l'entrée possède type="number".

.trim #

Si vous voulez que les espaces blancs des entrées utilisateur soient automatiquement supprimés, vous pouvez ajouter le modificateur trim à vos entrées gérées par v-model :

<input v-model.trim="msg" />

v-model avec les composants #

Si vous n'êtes pas encore familiarisé avec les composants de Vue, vous pouvez sauter cette étape pour le moment.

Les types de saisie natifs dans HTML ne répondent pas toujours à vos besoins. Heureusement, les composants Vue vous permettent de construire des entrées réutilisables avec un comportement complètement personnalisé. Ces entrées fonctionnent même avec v-model ! Pour en savoir plus, lisez à propos de l'utilisation avec v-model dans le guide des composants.