Bien que vous soyez libre d'utiliser les entrées FormKit par elles-mêmes, vous voudrez généralement les regrouper dans un formulaire. Pour ce faire, il suffit d'entourer vos entrées avec 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 nom de propriété dans l'objet de données résultant (tout comme les groupes). Vous pouvez également lire et écrire les valeurs du formulaire en utilisant v-model comme vous le feriez sur n'importe quelle entrée.
Un <FormKit type="form"> suit l'état de validation du formulaire et empêche les utilisateurs de soumettre le formulaire si des entrées sont invalides.
Pour plus de commodité, le form génère automatiquement un bouton de soumission button, et les thèmes fournis incluent également un indicateur de chargement. Vous pouvez modifier ce bouton avec les props submit-label et submit-attrs, ou le désactiver avec :actions="false". Vous pouvez passer n'importe quelle prop FormKit à submit-attrs. Dans l'exemple ci-dessous, nous passons des classes, des attributs data, du texte d'aide, et même demander au bouton de soumission inclus d'être pris en compte :
<FormKit
type="form"
submit-label="Mettre à jour"
:submit-attrs="{
inputClass: 'ma-classe-input',
wrapperClass: 'ma-classe-wrapper',
'data-theme': `dark`,
help: 'Texte d'aide de mon bouton',
ignore: false
}"
></FormKit>
Excluant la fonctionnalité backend, voici un formulaire entièrement fonctionnel avec des entrées (form, text, email, password), du texte d'aide, des étiquettes, une validation avec des messages personnalisés, et la gestion des erreurs et des soumissions :
Vous pouvez remplir un formulaire entier en fournissant une prop value au <FormKit type="form">. La prop value doit être un objet de paires nom d'entrée à valeur d'entrée. Vous pouvez également utiliser v-model pour remplir un formulaire si vous avez besoin d'une liaison de données bidirectionnelle :
Assurez-vous de v-model une ref ou une propriété d'un objet reactive. Ne v-model pas l'objet réactif lui-même car cela entraîne un comportement inattendu.
Les formulaires sont généralement soumis par des actions de l'utilisateur telles que cliquer sur un bouton de soumission ou appuyer sur la touche entrée dans un champ de texte du formulaire. Lors de la soumission, le formulaire (dans l'ordre) :
@submit-raw.submitted à vrai sur toutes les entrées — affichant toutes les erreurs de validation restantes (indépendamment de la validation-visibility).@submit-invalid est déclenché.@submit.@submit retourne une Promise, il définit l'état du formulaire à loading jusqu'à ce qu'elle soit résolue.Utiliser des données v-model dans votre gestionnaire de soumission peut entraîner des mutations involontaires du formulaire. FormKit collecte automatiquement les données du formulaire pour vous, utilisez donc la copie non liée des données de votre formulaire qui est passée à votre gestionnaire de soumission à la place.
La méthode de soumission de formulaire la plus courante dans une SPA moderne est une requête XHR (pensez à axios ou fetch). FormKit est bien adapté à cette tâche :
@submit 1) les données du formulaire collectées sous forme d'un objet unique prêt pour la requête (pas de v-model nécessaire), et 2) le nœud central de l'entrée form, pour plus de commodité.loading devient vrai dans context.state.loading et un indicateur de chargement est affiché sur le thème genesis).Pour soumettre un formulaire via une requête de page, il suffit de ne pas utiliser le gestionnaire @submit. Tout comme en HTML natif, vous pouvez également fournir un attribut action et éventuellement un attribut method.
Bien que la soumission d'un formulaire en utilisant n'importe quelle méthode HTML standard soit valide (comme cliquer sur un bouton submit, ou appuyer sur entrée dans un champ de texte) — vous pouvez également soumettre un formulaire de manière programmatique. Il y a 2 façons de faire cela :
this.$formkit.submit('form-id') (submitForm('form-id') pour l'API de composition).$formkit.submit()node.submit()Vous pouvez également soumettre un formulaire de manière programmatique en appelant node.submit() sur le nœud principal du formulaire (ou de n'importe quelle entrée à l'intérieur du formulaire). Pour ce faire, vous devez récupérer une instance du nœud principal.
Pour désactiver toutes les entrées dans un formulaire donné, y compris le bouton de soumission, vous pouvez utiliser la propriété disabled.
Lorsque vous utilisez un gestionnaire @submit asynchrone, FormKit désactivera automatiquement le formulaire (et définira l'état sur loading) pendant que le gestionnaire de soumission est en attente.
Vous pouvez réinitialiser votre formulaire (ou n'importe quelle entrée) à son état initial en appelant $formkit.reset(formId).
Lorsque vous utilisez l'API de composition, vous pouvez accéder directement à la fonction de réinitialisation en l'important depuis le cœur : import { reset } from '@formkit/core'.
Il est important de noter que l'"état initial" d'un formulaire n'est pas nécessairement un formulaire vide. Si vous avez une valeur par défaut :value ou v-model sur le formulaire ou sur des entrées individuelles dans le formulaire, FormKit fusionne automatiquement ces valeurs pour produire votre valeur initiale, et restaurera cet état fusionné lors de la réinitialisation.
Facultativement, vous pouvez fournir un second argument à reset(formId, initialState) si vous préférez un état de réinitialisation alternatif.
Les formulaires ne seront pas soumis tant que toutes les entrées du formulaire ne passent pas leurs règles de validation.
En plus de ne pas déclencher l'événement de soumission, un message est affiché au-dessus du bouton de soumission indiquant que le formulaire est encore incomplet. Vous pouvez personnaliser ce message en utilisant la propriété incomplete-message ou le désactiver en définissant la propriété sur false.
Si vous souhaitez modifier le message d'incomplétude pour tous les formulaires de votre projet, vous pouvez modifier le message de localisation i18n pour ui.incomplete.
Lorsqu'un utilisateur tente de soumettre un formulaire contenant des entrées qui ne passent pas les validations, l'événement @submit-invalid est déclenché.
Par exemple, nous pourrions utiliser cet événement pour alerter nos utilisateurs des règles de validation échouées.
La validité de toutes les entrées dans un formulaire est automatiquement suivie dans l'objet contexte. Cela peut être utile lors de la création de diverses interfaces. Par exemple, si vous vouliez qu'un bouton de soumission soit désactivé jusqu'à ce que toutes les entrées soient valides, vous pourriez utiliser la propriété state.valid pour ce faire.
Dans l'exemple ci-dessus, nous extrayons l'objet contexte du slot #default, mais il existe d'autres moyens également. L'objet contexte est disponible sur le nœud central de chaque entrée sur la propriété node.context, et vous pouvez récupérer le nœud d'une entrée de plusieurs manières.
Avec FormKit, ajouter une validation côté client à votre formulaire est facile — mais qu'en est-il des erreurs produites par votre framework backend, ou celles que vous souhaitez attribuer manuellement ? Il existe deux types d'erreurs que vous pouvez attribuer à un formulaire :
Les erreurs de formulaire (celles qui s'appliquent à l'ensemble du formulaire) peuvent être définies de trois manières.
errors sur un <FormKit type="form">.node.setErrors().$formkit.setErrors().errorsComme avec n'importe quelle entrée FormKit, vous pouvez directement attribuer des erreurs en utilisant la propriété errors. Ces erreurs sont toujours visibles (non soumises à validation-visibility).
node.setErrors()Définir les erreurs de votre formulaire en utilisant node.setErrors est pratique puisque votre gestionnaire de soumission reçoit l'objet node du formulaire comme deuxième argument. node.setErrors() prend 2 arguments — un tableau pour les erreurs de formulaire et un objet clé pour les erreurs d'entrée :
$formkit.setErrors()Alternativement, vous pouvez définir des erreurs directement sur un formulaire en lui attribuant un id puis en appelant $formkit.setErrors('id', ['Erreur du formulaire ici']). La méthode setErrors doit recevoir l'id du formulaire, et peut ensuite gérer 1 ou 2 arguments supplémentaires — les erreurs du formulaire et les erreurs des champs :
Par défaut, les erreurs qui ont été définies sur les champs en utilisant setErrors() sont automatiquement effacées lorsque l'utilisateur modifie la valeur de ce champ. Vous pouvez changer ce comportement par défaut en définissant la propriété preserve-errors.
Pour effacer toutes les erreurs du formulaire (indépendamment de la propriété preserve-errors), appelez node.clearErrors().
Si vous préférez conserver les erreurs par défaut, vous pouvez modifier le comportement par défaut en modifiant l'option de configuration preserveErrors. Cela peut être fait globalement ou pour un formulaire unique :
Lorsque vous utilisez l'API de composition de Vue 3, vous pouvez accéder à setErrors et clearErrors en les important directement depuis @formkit/vue.import { setErrors, clearErrors } from '@formkit/vue'
Les erreurs de champ (celles à afficher avec des champs spécifiques dans un formulaire) peuvent être appliquées de trois manières :
errors sur chaque champ individuel.input-errors sur le formulaire (fonctionne aussi avec les groupes et les listes).$formkit.setErrors() (voir l'exemple ci-dessus).errorsLa manière la plus basique d'afficher des erreurs sur un formulaire est d'utiliser la propriété errors qui est disponible sur chaque champ FormKit.
input-errorsVous pouvez également définir de manière pratique des messages d'erreur pour tous les champs de votre formulaire (ou groupe ou liste) en utilisant la propriété input-errors. La propriété accepte un objet d'erreurs, où les clés sont les noms des champs (les adresses de nœuds relatives sont prises en charge) et la valeur est une erreur ou un tableau d'erreurs à appliquer à ce champ.
Il peut être utile pour l'accessibilité de fournir un résumé des messages de validation et d'erreur en haut de votre formulaire. FormKit fournit un composant <FormKitSummary /> pour rendre ce résumé pour vous.
Ce composant affichera automatiquement tous les messages de validation et d'erreur d'un formulaire avec des liens de saut vers les entrées auxquelles ils s'appliquent. Ces erreurs ne sont affichées qu'après la soumission du formulaire, mais elles sont enveloppées dans une région aria-live pour garantir que les lecteurs d'écran seront notifiés lorsque les erreurs se présentent. De plus, la page défilera automatiquement vers la boîte de résumé et se focalisera sur la première erreur listée.
<FormKitSummary /> n'est pas un composant enregistré globalement — vous devez l'importer :
import { FormKitSummary } from '@formkit/vue'
Le composant de résumé doit généralement être imbriqué dans le formulaire qu'il résume. Si vous souhaitez déplacer le résumé vers un autre emplacement sur la page, vous pouvez le faire en fournissant le nœud central du formulaire comme propriété node.
Par défaut, les messages de validation et d'erreur d'un formulaire sont placés juste au-dessus de la section des actions du formulaire. Cependant, vous pouvez choisir de les rendre n'importe où sur votre page en utilisant le composant <FormKitMessages />. <FormKitMessages /> n'est pas un composant enregistré globalement — vous devez l'importer :
import { FormKitMessages } from '@formkit/vue'
Il y a deux façons d'utiliser <FormKitMessages /> :
Placez un composant <FormKitMessages /> n'importe où à l'intérieur de votre formulaire, et les messages du formulaire seront automatiquement déplacés à cet emplacement :
nodePour déplacer les messages n'importe où dans le DOM — même en dehors du formulaire — vous pouvez passer le nœud central du formulaire comme propriété à <FormKitMessages />. Dans cet exemple, nous utilisons les messages pour créer une popup de style toast :
Le composant <FormKitMessages /> a quelques options de configuration supplémentaires :
| Prop | Défaut | Description |
|---|---|---|
node | hérité | Le nœud central pour lequel rendre les messages. Par défaut, cela est hérité du parent du nœud (s'il existe). |
sectionsSchema | {} | Remplace les sections internes messages et message (même structure par défaut que la section des messages d'autres entrées). |
defaultPosition | false | Par défaut, FormKitMessages déplace les messages rendus vers un nouvel emplacement. Si vous souhaitez rendre les messages dans les deux emplacements, mettez cette propriété à true. |
Lorsqu'une entrée est démontée d'un formulaire — par exemple en utilisant v-if — sa clé et sa valeur sont retirées des données du formulaire. Cependant, dans certaines circonstances, il peut être préférable de conserver la paire clé/valeur même après que l'entrée a été retirée. Cela peut être accompli en utilisant la prop preserve :
FormKit fournit quelques composables pour vous aider à accéder aux données et au contexte du formulaire. Ceux-ci sont disponibles à l'importation depuis le package @formkit/vue :
Le useFormKitContext est un composable qui retourne l'objet contexte du formulaire sous forme de Ref vue dès qu'il devient disponible. Cela doit être utilisé dans un composant qui est un enfant d'un composant <FormKit> (comme le formulaire). Le premier argument est un chemin de traversée optionnel qui vous permet de naviguer vers n'importe quel nœud dans l'arborescence de votre formulaire. Le deuxième argument est un rappel d'effet optionnel qui sera invoqué chaque fois que le contexte deviendra disponible.
Similaire à useFormKitContext, ce composable trouve tout objet contexte <FormKit> si ce composant s'est vu attribuer un id explicite. Facultativement, vous pouvez fournir un rappel d'effet qui sera invoqué chaque fois que le nœud deviendra disponible.
Récupère tout nœud FormKit qui a un id explicite. Il retourne un Ref qui se peuplera avec le nœud central dès qu'il sera monté. Facultativement, vous pouvez fournir un rappel d'effet qui sera invoqué chaque fois que le nœud deviendra disponible.
Le nœud lui-même n'est pas réactif et devrait être utilisé pour des actions impératives comme node.submit(). L'objet contexte est réactif et devrait être utilisé pour lire et réagir à l'état du formulaire.
Les formulaires sont techniquement considérés comme des types input — ils partagent donc de nombreuses props universelles que les entrées standard utilisent.
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| disabled | Boolean | false | Disables the form submit button and all the inputs in the form. |
| incomplete-message | String/Boolean | {locale}.ui.incomplete | The message that is shown to near the submit button when a user attempts to submit a form, but not all inputs are valid. |
| submit-attrs | Object | {} | Attributes or props that should be passed to the built-in submit button. |
| submit-behavior | String | disabled | Async submit handlers automatically disable the form while pending, you can change this by setting this prop to 'live'. |
| submit-label | String | Submit | The label to use on the built-in submit button. |
| actions | Boolean | true | Whether or not to include the actions bar at the bottom of the form (ex. you want to remove the submit button and use your own, set this to false). |
| Afficher Universel props | |||
| config | Object | {} | Options de configuration à fournir au nœud d'entrée et à tout nœud descendant de cette entrée. |
| delay | Number | 20 | Nombre de millisecondes à attendre avant que la valeur d'une entrée ne soit déclenchée avant que le commit hook ne soit déclenché. |
| dirtyBehavior | string | touched | Détermine comment le drapeau "dirty" de cette entrée est défini. Peut être défini sur touched ou compare — touched (par défaut) est plus performant, mais ne détectera pas lorsque le formulaire correspond à nouveau à son état initial. |
| errors | Array | [] | Tableau de chaînes à afficher comme messages d'erreur sur ce champ. |
| help | String | '' | Texte pour le texte d'aide associé à l'entrée. |
| id | String | input_{n} | L'identifiant unique de l'entrée. Fournir un identifiant permet également d'accéder globalement au nœud de l'entrée. |
| ignore | Boolean | false | Empêche une entrée d'être incluse dans un parent (groupe, liste, formulaire, etc). Utile lors de l'utilisation d'entrées pour l'interface utilisateur au lieu de valeurs réelles. |
| index | Number | undefined | Permet d'insérer une entrée à l'index donné si le parent est une liste. Si la valeur de l'entrée est indéfinie, elle hérite de la valeur de cette position d'index. Si elle a une valeur, elle l'insère dans les valeurs de la liste à l'index donné. |
| label | String | '' | Texte pour l'élément label associé à l'entrée. |
| name | String | input_{n} | Le nom de l'entrée tel qu'identifié dans l'objet de données. Cela doit être unique au sein d'un groupe de champs. |
| parent | FormKitNode | contextual | Par défaut, le parent est un groupe d'enrobage, une liste ou un formulaire — mais cette propriété permet une affectation explicite du nœud parent. |
| prefix-icon | String | '' | Spécifie une icône à placer dans la section prefixIcon. |
| preserve | boolean | false | Conserve la valeur de l'entrée sur un groupe parent, une liste ou un formulaire lorsque l'entrée est démontée. |
| preserve-errors | boolean | false | Par défaut, les erreurs définies sur les entrées à l'aide de setErrors sont automatiquement effacées lors de l'entrée, en définissant cette propriété sur true, l'erreur est maintenue jusqu'à ce qu'elle soit explicitement effacée. |
| sections-schema | Object | {} | Un objet de clés de section et de valeurs partielles de schéma, où chaque partie de schéma est appliquée à la section respective. |
| suffix-icon | String | '' | Spécifie une icône à placer dans la section suffixIcon. |
| type | String | text | Le type d'entrée à afficher à partir de la bibliothèque. |
| validation | String, Array | [] | Les règles de validation à appliquer à l'entrée. |
| validation-visibility | String | blur | Détermine quand afficher les règles de validation en échec d'une entrée. Les valeurs valides sont blur, dirty et live. |
| validation-label | String | {label prop} | Détermine quelle étiquette utiliser dans les messages d'erreur de validation, par défaut, elle utilise la propriété label si elle est disponible, sinon elle utilise la propriété name. |
| validation-rules | Object | {} | Règles de validation personnalisées supplémentaires à rendre disponibles pour la propriété de validation. |
| value | Any | undefined | Initialise la valeur initiale d'une entrée et/ou de ses enfants. Non réactif. Peut initialiser des groupes entiers (formulaires) et des listes.. |
| Section-key | Description |
|---|---|
| form | Responsable du rendu de la balise form et de l'écoute des événements de soumission. |
| actions | Responsable d'un conteneur en bas du formulaire avec des actions de formulaire comme le bouton de soumission. |
| submit | Responsable d'un bouton de soumission — par défaut un type d'entrée FormKit submit. |
| Afficher Universel section keys | |
| outer | L'élément d'enrobage le plus externe. |
| wrapper | Un enrobage autour de l'étiquette et de l'entrée. |
| label | L'étiquette de l'entrée. |
| prefix | N'a pas de sortie par défaut, mais permet du contenu directement avant un élément d'entrée. |
| prefixIcon | Un élément pour afficher une icône avant la section de préfixe. |
| inner | Un enrobage autour de l'élément d'entrée réel. |
| suffix | N'a pas de sortie par défaut, mais permet du contenu directement après un élément d'entrée. |
| suffixIcon | Un élément pour afficher une icône après la section de suffixe. |
| input | L'élément d'entrée lui-même. |
| help | L'élément contenant le texte d'aide. |
| messages | Un enrobage autour de tous les messages. |
| message | L'élément (ou plusieurs éléments) contenant un message — le plus souvent des messages de validation et d'erreur. |
Toutes les entrées FormKit sont conçues en tenant compte des considérations d'accessibilité suivantes. Aidez-nous à améliorer continuellement l'accessibilité pour tous en signalant les problèmes d'accessibilité ici: