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 la Vue Composition API.
L'une des principales caractéristiques de FormKit est son API à composant unique — le composant <FormKit />. Ce seul composant vous donne accès à tous les types d'entrée. Et bien que certains types puissent s'é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 /> 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 comme 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". Même ainsi, en tant que meilleure pratique, nous devrions toujours au moins spécifier 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 de, et transmettre les valeurs à, leurs enfants en fonction du name :
Il manque encore à notre entrée certaines fonctionnalités d'accessibilité clés comme une label, help, et peut-être même un placeholder. FormKit accepte tout cela comme props, et produit les attributs aria appropriés. Les lecteurs d'écran annonceront maintenant le nom de l'entrée, le texte d'aide, et que l'entrée est prête à être éditée :
Parfois, vous voulez ajouter une valeur initiale à une entrée, comme fournir un point de départ sensé, 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 ajouter à ce guide. Imaginons que nous construisons un "formulaire de création de personnage" pour un jeu. Assignons à 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 gamme, et représentent le haut et le bas du curseur de gamme.
Supposons que notre "backend" nécessite que des données comme strength soient castées en nombre. Par défaut, FormKit suit le comportement des entrées "natives" HTML, rendant toutes les valeurs comme des "chaînes". Pour corriger cela, nous pouvons utiliser l'une des fonctionnalités les plus cool de FormKit - les plugins - qui peuvent être considérés comme des intergiciels pour les entrées. Avec un plugin, qui sont juste des fonctions, nous pouvons changer comment la valeur de notre entrée est retournée :
Tout d'abord, créons un formulaire de base et ajoutons plus d'entrées pour avoir du contenu avec lequel travailler. Nous ajouterons plus de fonctionnalités à chaque section, comme la validation, le regroupement et la modification des valeurs en fonction d'autres entrées.
Nous utiliserons l'une des entrées appelée form, qui facilitera le regroupement et la validation des champs. Vous avez juste besoin 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 un objet de données pour vous (tout comme group).
La première fonctionnalité d'un formulaire que nous allons explorer est que nous avons un événement @submit prêt à nous faciliter la vie lorsque vient le moment de soumettre notre formulaire. L'événement @submit nous donne comme premier argument tous les champs descendants que le formulaire a recueillis à partir des entrées. Il n'est pas nécessaire d'utiliser de nombreux v-models pour collecter les données du formulaire. Ajoutons notre gestionnaire de soumission createCharacter() :
Pour plus de 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 corriger cela, nous pouvons utiliser la propriété submit-label, qui est une fonctionnalité spécifique à form, simplement en ajoutant submit-label="Create Character" 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 frères). Supposons que notre backend a besoin de toutes les attributs à l'intérieur d'une propriété attributes. Nous pouvons utiliser le type group pour regrouper les entrées liées ensemble 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 c'est tout ! Nous pourrions nous arrêter ici pour une introduction sur la façon dont les formulaires et les entrées fonctionnent avec FormKit. Cependant, ajoutons quelques améliorations UX et utilisons cela pour nous exposer à des concepts et des 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 changer les attributs par défaut du personnage en fonction de la classe de personnage sélectionnée. Pour cela, nous allons utiliser quelques 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.Avec ces fonctionnalités combinées, nous pouvons obtenir le nœud central d'une entrée, écouter et répondre aux événements, et mettre à jour une 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 pour créer un plugin à la place. Notez que nous plaçons le nouveau updateAttributesPlugin uniquement sur l'entrée class, donc il n'affectera aucune autre entrée. Nous allons également apprendre une autre fonctionnalité utile appelée traversal en utilisant la fonction at d'un nœud :
La fonction at utilise l'attribut name au lieu de l'id que getNode utilise.
Supposons que, bien que différents personnages soient meilleurs dans différents attributs, aucun ne devrait être trop puissant. Nous pouvons faire cela en créant un budget de points, et en ajoutant une validation de groupe aux attributs group pour s'assurer qu'ils ne dépassent pas 20 points au total. Nous allons apprendre une nouvelle fonctionnalité - règles personnalisées - pour accomplir cela :
Par défaut, le type group ne produit aucune balise, donc pour montrer les erreurs de validation, nous devons l'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 de contexte dans le #default slot prop.group - La valeur d'un group (et form) input est un objet avec les valeurs de ses enfants, clés 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 nécessite un nouveau rendu, au lieu d'essayer de le réutiliser. Nous pouvons ajouter une propriété key unique à l'élément pour aider Vue.
Alors, prenons l'objet de contexte de l'entrée group et extrayons la value: #default="{ value }". Nous voulons ajouter un petit easter egg pour nos utilisateurs s'ils décident de changer tous les attributs à 1 :
Et cela 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 :