x-model

x-model vous permet de lier la valeur d'un champ de saisie à des données Alpine.

Voici un exemple simple d'utilisation de x-model pour lier la valeur d'un champ texte à une donnée d'Alpine.

<div x-data="{ message: '' }">
    <input type="text" x-model="message">

    <span x-text="message"></span>
</div>

Désormais, à mesure que l'utilisateur saisit du texte dans le champ, le contenu de message est reflété dans la balise <span>.

x-model est lié dans les deux sens : il « écrit » et il « lit ». En plus de modifier les données, si les données elles-mêmes changent, l'élément reflète ce changement.

Nous pouvons reprendre le même exemple, mais cette fois en ajoutant un bouton qui change la valeur de la propriété message.

<div x-data="{ message: '' }">
    <input type="text" x-model="message">

    <button x-on:click="message = 'modifié'">Changer le message</button>
</div>

Désormais, lorsque l'on clique sur le <button>, la valeur du champ de saisie est instantanément mise à jour avec « modifié ».

x-model fonctionne avec les éléments de saisie suivants :

• <input type="text">
• <textarea>
• <input type="checkbox">
• <input type="radio">
• <select>
• <input type="range">

Champs texte

<input type="text" x-model="message">

<span x-text="message"></span>

Remarque : bien que cela ne figure pas dans l'extrait ci-dessus, x-model ne peut pas être utilisé si aucun élément parent ne définit x-data. → En savoir plus sur x-data

Zones de texte (textarea)

<textarea x-model="message"></textarea>

<span x-text="message"></span>

Cases à cocher

Case à cocher unique avec un booléen

<input type="checkbox" id="checkbox" x-model="show">

<label for="checkbox" x-text="show"></label>

Plusieurs cases à cocher liées à un tableau

<input type="checkbox" value="red" x-model="colors">
<input type="checkbox" value="orange" x-model="colors">
<input type="checkbox" value="yellow" x-model="colors">

Couleurs : <span x-text="colors"></span>

Boutons radio

<input type="radio" value="yes" x-model="answer">
<input type="radio" value="no" x-model="answer">

Réponse : <span x-text="answer"></span>

Listes de sélection (select)

Sélection simple

<select x-model="color">
    <option>Rouge</option>
    <option>Orange</option>
    <option>Jaune</option>
</select>

Couleur : <span x-text="color"></span>

Sélection simple avec texte d'invite

<select x-model="color">
    <option value="" disabled>Choisissez une couleur</option>
    <option>Rouge</option>
    <option>Orange</option>
    <option>Jaune</option>
</select>

Couleur : <span x-text="color"></span>

Sélection multiple

<select x-model="color" multiple>
    <option>Rouge</option>
    <option>Orange</option>
    <option>Jaune</option>
</select>

Couleurs : <span x-text="color"></span>

Options de sélection générées dynamiquement

<select x-model="color">
    <template x-for="color in ['Rouge', 'Orange', 'Jaune']">
        <option x-text="color"></option>
    </template>
</select>

Couleur : <span x-text="color"></span>

Curseurs (range)

<input type="range" x-model="range" min="0" max="1" step="0.1">

<span x-text="range"></span>

Modificateurs

.lazy

Sur les champs texte, par défaut, x-model met à jour la propriété à chaque frappe. En ajoutant le modificateur .lazy, vous pouvez forcer un champ x-model à ne mettre à jour la propriété que lorsque l'utilisateur quitte l'élément de saisie.

C'est pratique, par exemple, pour la validation de formulaire en temps réel, lorsque vous ne voulez pas afficher d'erreur de validation tant que l'utilisateur n'est pas passé au champ suivant (avec la touche Tab).

<input type="text" x-model.lazy="username">
<span x-show="username.length > 20">Le nom d'utilisateur est trop long.</span>

.change

.change synchronise les données uniquement lorsque le champ perd le focus et que sa valeur a changé (l'événement natif change). C'est fonctionnellement équivalent à .lazy.

<input type="text" x-model.change="username">

.blur

.blur synchronise les données lorsque le champ perd le focus, que sa valeur ait changé ou non.

<input type="text" x-model.blur="email">

.enter

.enter synchronise les données lorsque l'utilisateur appuie sur la touche Entrée. C'est utile pour les champs de recherche où vous voulez déclencher une action uniquement lorsque l'utilisateur valide explicitement.

<input type="text" x-model.enter="search">

Remarque : .enter n'empêche pas le comportement par défaut. Si le champ se trouve dans un formulaire, celui-ci sera tout de même envoyé.

Combiner les modificateurs d'événements

Les modificateurs .change, .blur et .enter peuvent être combinés pour synchroniser sur plusieurs événements. C'est utile lorsque vous souhaitez laisser aux utilisateurs de la souplesse dans la façon de valider leur saisie.

<!-- Synchronise sur blur OU enter -->
<input type="text" x-model.blur.enter="search" placeholder="Appuyez sur Entrée ou cliquez ailleurs">

<!-- Synchronise sur change, blur OU enter -->
<input type="text" x-model.change.blur.enter="message">

.number

Par défaut, toute donnée stockée dans une propriété via x-model est stockée sous forme de chaîne de caractères. Pour forcer Alpine à stocker la valeur sous forme de nombre JavaScript, ajoutez le modificateur .number.

<input type="text" x-model.number="age">
<span x-text="typeof age"></span>

.boolean

Par défaut, toute donnée stockée dans une propriété via x-model est stockée sous forme de chaîne de caractères. Pour forcer Alpine à stocker la valeur sous forme de booléen JavaScript, ajoutez le modificateur .boolean. Les entiers (1/0) comme les chaînes (true/false) sont des valeurs booléennes valides.

<select x-model.boolean="isActive">
    <option value="true">Oui</option>
    <option value="false">Non</option>
</select>
<span x-text="typeof isActive"></span>

.debounce

En ajoutant .debounce à x-model, vous pouvez facilement temporiser (debounce) la mise à jour de la donnée liée.

C'est utile, par exemple, pour des champs de recherche en temps réel qui récupèrent de nouvelles données auprès du serveur à chaque changement de la propriété de recherche.

<input type="text" x-model.debounce="search">

La durée de temporisation par défaut est de 250 millisecondes ; vous pouvez facilement la personnaliser en ajoutant un modificateur de durée, comme ceci.

<input type="text" x-model.debounce.500ms="search">

.throttle

Comme pour .debounce, vous pouvez limiter la mise à jour de la propriété déclenchée par x-model à un intervalle précis.

<input type="text" x-model.throttle="search">

L'intervalle de limitation (throttle) par défaut est de 250 millisecondes ; vous pouvez facilement le personnaliser en ajoutant un modificateur de durée, comme ceci.

<input type="text" x-model.throttle.500ms="search">

.fill

Par défaut, si un champ possède un attribut value, Alpine l'ignore et définit à la place la valeur du champ avec celle de la propriété liée via x-model.

Mais si la propriété liée est vide, vous pouvez utiliser l'attribut value du champ pour alimenter la propriété en ajoutant le modificateur .fill.

<div x-data="{ message: null }">
  <input type="text" x-model.fill="message" value="Ceci est le message par défaut.">
</div>

Accès programmatique

Alpine expose des utilitaires internes pour lire et écrire les propriétés liées avec x-model. C'est utile pour des utilitaires Alpine complexes qui souhaitent remplacer le comportement par défaut de x-model, ou pour les cas où vous voulez autoriser x-model sur un élément qui n'est pas un champ de saisie.

Vous pouvez accéder à ces utilitaires via une propriété nommée _x_model sur l'élément portant x-model. _x_model possède deux méthodes pour lire et écrire la propriété liée :

• el._x_model.get() (retourne la valeur de la propriété liée)
• el._x_model.set() (définit la valeur de la propriété liée)

<div x-data="{ username: 'calebporzio' }">
    <div x-ref="div" x-model="username"></div>

    <button @click="$refs.div._x_model.set('phantomatrix')">
        Changer le nom d'utilisateur en : 'phantomatrix'
    </button>

    <span x-text="$refs.div._x_model.get()"></span>
</div>

Traduction française de la documentation officielle d'Alpine.js (licence MIT) – https://alpinejs.dev