Commençons par créer notre premier formulaire FormKit ! Nous découvrirons certaines des principales fonctionnalités de FormKit et comment elles vous sont bénéfiques. Nous apprendrons également quelques astuces en cours de route, comme la gestion de l'état du formulaire sans utiliser v-model.
Ce guide suppose que vous êtes familiarisé avec l'API de composition Vue.
L'une des principales caractéristiques de FormKit est son API de composant unique : le composant <FormKit />. Ce composant unique vous donne accès à tous les types d'entrée. Et bien que certains types puissent étendre et ajouter des fonctionnalités, ils partagent la même fonctionnalité de base. Vous pouvez en savoir plus sur les entrées ici.
Même sans aucune prop, le composant <FormKit /> nu a déjà donné à notre entrée un excellent point de départ, avec un balisage accessible, un type d'entrée text de base et des fonctionnalités supplémentaires qui seront expliquées dans les sections suivantes.
Par défaut, le composant <FormKit /> utilisera type="text" si aucun type n'est spécifié. Le type est la façon dont nous spécifions l'entrée que nous voulons. Tout comme les entrées natives, nous avons des entrées comme text, select, checkbox et ainsi de suite. Cependant, nous ne sommes pas limités aux seules entrées "natives", FormKit Pro ajoute des contrôles non natifs tels que les types repeater, taglist et autocomplete, qui peuvent gérer des interactions plus complexes.
Si vous regardez le HTML généré par l'exemple précédent, vous verrez que FormKit a déjà créé un balisage accessible. Cependant, comme nous n'avons pas spécifié les propriétés name et id, elles ont été générées automatiquement pour nous : name: "text_1" id="input_0". Néanmoins, en tant que meilleure pratique, nous devrions toujours spécifier au moins le name, car cela facilite l'utilisation des entrées à l'intérieur d'un formulaire. Le name est utilisé par les types form et group pour collecter les valeurs et les transmettre à leurs enfants en fonction du name :
Notre entrée manque encore de certaines fonctionnalités clés en matière d'accessibilité, comme une label, help, et peut-être même un placeholder. FormKit accepte tout cela sous forme de props et génère les attributs aria appropriés. Les lecteurs d'écran annonceront désormais le nom de l'entrée, le texte d'aide et indiqueront que l'entrée est prête à être modifiée :
Parfois, vous voulez ajouter une valeur initiale à une entrée, comme fournir un point de départ logique ou remplir des données pré-enregistrées à partir d'une base de données. Nous faisons cela avec la prop value.
Commençons à construire un exemple que nous pourrons compléter pour ce guide. Imaginons que nous construisons un "formulaire de création de personnage" pour un jeu. Attribuons à notre personnage une note de force. Nous pourrions utiliser l'entrée range avec une valeur prédéfinie de 5 lorsque l'utilisateur ouvre le formulaire pour la première fois :
La validation est l'une des principales fonctionnalités de FormKit. Elle aide l'utilisateur à savoir si la valeur qu'il soumet est correcte. Ajouter une validation est un jeu d'enfant, avec de nombreuses règles de validation puissantes déjà implémentées pour vous. Nous utiliserons la prop validation pour nous assurer que le personnage n'est pas trop fort ou trop faible. La prop validation-visibility nous permet de contrôler quand montrer les messages de validation à l'utilisateur — immédiatement, lorsque l'utilisateur sort de l'entrée, ou lors de la soumission du formulaire. L'état de validité réel est calculé en temps réel et toujours à jour — nous choisissons simplement quand exposer les messages :
Notez que les props min et max ci-dessus sont des props de navigateur intégrées pour une entrée de plage et représentent le haut et le bas du curseur de plage.
Supposons que notre "backend" exige que des données telles que strength soient castées en nombre. Par défaut, FormKit suit le comportement des entrées "natives" HTML, traitant toutes les valeurs comme des "chaînes de caractères". Pour résoudre cela, nous pouvons utiliser l'une des fonctionnalités les plus intéressantes de FormKit — plugins — qui peuvent être considérés comme des intergiciels pour les entrées. Avec un plugin, qui sont juste des fonctions, nous pouvons modifier la manière dont la valeur de notre entrée est renvoyée :
Tout d'abord, créons un formulaire de base et ajoutons-y plusieurs champs pour avoir du contenu à travailler. Nous ajouterons d'autres fonctionnalités à chaque section, comme la validation, le regroupement et la modification des valeurs en fonction d'autres entrées.
Nous utiliserons l'un des champs appelés form, qui facilitera grandement le regroupement et la validation des champs. Il vous suffit d'envelopper toutes vos entrées dans un <FormKit type="form"> :
Le type form collectera activement toutes les valeurs des entrées enfants en utilisant le name de chaque entrée comme objet de données pour vous (tout comme group).
La première fonctionnalité d'un formulaire que nous explorerons est que nous avons un événement @submit prêt à nous faciliter la vie lorsque vient le temps de soumettre notre formulaire. L'événement @submit nous donne en premier argument tous les champs descendants que le formulaire a rassemblés à partir des entrées. Il n'est pas nécessaire d'utiliser de nombreux v-model pour collecter les données du formulaire. Ajoutons notre gestionnaire de soumission createCharacter() :
Par commodité lors de l'utilisation de type="form", le form génère automatiquement un bouton de soumission. Dans notre cas, un texte "Submit" ne montre pas correctement l'intention du formulaire. Pour résoudre cela, nous pouvons utiliser la propriété submit-label, qui est une fonctionnalité spécifique à form. Nous pouvons simplement ajouter submit-label="Créer un personnage" pour montrer l'intention du formulaire :
<FormKit type="form" @submit="createCharacter" submit-label="Créer un personnage">
<!-- Reste de notre formulaire de création -->
</FormKit>Bien que le formulaire fonctionne actuellement, nous pouvons voir que certaines entrées liées sont séparées (c'est-à-dire que les données du formulaire sont une structure plate où toutes les données du formulaire sont des éléments frères). Supposons que notre backend a besoin de tous les attributs à l'intérieur d'une propriété attributes. Nous pouvons utiliser le type group pour regrouper les entrées liées par un name commun.
Tout comme le type form, vous pouvez envelopper tous vos champs dans un <FormKit type="group" name: "attributes">. N'oubliez pas d'ajouter la propriété name :
Et voilà ! Nous pourrions nous arrêter ici pour une introduction sur le fonctionnement des formulaires et des entrées avec FormKit. Cependant, ajoutons quelques améliorations UX et utilisons cela pour nous exposer à des concepts et fonctionnalités supplémentaires que vous pouvez utiliser pour amener vos formulaires au niveau supérieur.
Une chose que nous pouvons faire pour améliorer ce formulaire est de modifier les attributs par défaut du personnage en fonction de la classe de personnage sélectionnée. Pour cela, nous utiliserons de nouvelles fonctionnalités :
getNode obtient le nœud central d'une entrée en utilisant son id comme identifiant. Chaque entrée a un nœud central associé.events écoute les modifications d'une certaine entrée.input sur un nœud nous permet de mettre à jour sa valeur.En combinant ces fonctionnalités, nous pouvons obtenir le nœud central d'une entrée, écouter et répondre aux events, et mettre à jour la valeur d'un autre champ en utilisant la fonction input :
Le code est maintenant un peu moins lisible, alors extrayons la logique dans un autre fichier et utilisons un plugin à la place. Notez que nous plaçons le nouveau updateAttributesPlugin uniquement sur l'entrée class, de sorte qu'il n'affectera aucune autre entrée. Nous apprendrons également une autre fonctionnalité utile appelée traversal en utilisant la fonction at d'un nœud :
La fonction at utilise les attributs name au lieu du id que getNode utilise.
Supposons que, bien que différents personnages soient meilleurs dans différents attributs, aucun ne doit être trop puissant. Nous pouvons le faire en créant un budget de points et en ajoutant une validation de groupe au groupe d'attributs pour s'assurer qu'ils ne dépassent pas 20 points au total. Nous apprendrons une nouvelle fonctionnalité - règles personnalisées - pour accomplir cela :
Par défaut, le type group ne génère aucune balise, donc pour afficher les erreurs de validation, nous devons les ajouter manuellement.
Parfois, les formulaires doivent afficher ou masquer des champs en fonction de la valeur d'une autre entrée. Nous pouvons le faire en apprenant 2 nouveaux concepts :
FormKit reçoivent leur objet contexte dans la #default slot prop.group - La valeur d'un group (et form) est un objet contenant les valeurs de ses enfants, indexées par les names des enfants.Lors de l'utilisation du rendu conditionnel, notez que Vue a besoin d'indices pour savoir qu'un élément DOM doit être réaffiché, au lieu d'essayer de le réutiliser. Nous pouvons ajouter une propriété key unique à l'élément pour aider Vue.
Alors, récupérons l'objet contexte de l'entrée group et extrayons la value: #default="{ value }". Nous voulons ajouter un petit easter egg pour notre utilisateur s'ils décident de changer tous les attributs à 1 :
Et voilà qui conclut notre introduction à FormKit ! Vous êtes maintenant prêt à commencer à l'utiliser !
Il y a quelques sujets que nous vous recommandons d'explorer ensuite, que vous pouvez lire dans n'importe quel ordre ou même plus tard après avoir essayé FormKit par vous-même :