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'envelopper 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 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.
Par souci de commodité, le form génère automatiquement un bouton de soumission button, et les thèmes fournis incluent également un spinner 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 indiquons au bouton de soumission inclus de ne pas être ignoré :
<FormKit
type="form"
submit-label="Mettre à jour"
:submit-attrs="{
inputClass: 'my-input-class',
wrapperClass: 'my-wrapper-class',
'data-theme': `dark`,
help: 'Mon texte d'aide pour le bouton',
ignore: false
}"
></FormKit>Excluant la fonctionnalité côté serveur, 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 de la soumission :
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 soit une ref soit 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 utilisateur telles que cliquer sur un bouton de soumission ou appuyer sur la touche entrée sur un nœud de texte dans le formulaire. Lors de la soumission, le formulaire (en séquence) :
@submit-raw.submitted sur toutes les entrées - affichant les erreurs de validation restantes (indépendamment de la validation-visibility).@submit-invalid est déclenché.@submit.@submit renvoie une Promise, définit l'état du formulaire sur loading jusqu'à ce qu'il se résolve.Utiliser des données v-model dans votre gestionnaire de soumission peut entraîner des mutations de formulaire involontaires. 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 transmise à 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 la forme d'un seul objet prêt pour la requête (pas besoin de v-model), et 2) le nœud central de l'entrée form, par commodité.loading devient vrai à context.state.loading et un spinner est affiché sur le thème genesis).Pour soumettre un formulaire via une demande de page, il suffit de ne pas inclure le gestionnaire @submit. Tout comme le HTML natif, vous pouvez également fournir un attribut action et éventuellement un attribut method.
Bien que soumettre un formulaire en utilisant n'importe quelle méthode HTML standard soit valide (comme cliquer sur un bouton submit, ou appuyer sur entrée sur une entrée 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 quel champ à l'intérieur du formulaire). Pour ce faire, vous devez récupérer une instance du nœud principal.
Les formulaires ne seront pas soumis tant que tous les champs du formulaire ne respectent 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 prop incomplete-message ou le désactiver en définissant la prop sur false.
Si vous souhaitez modifier le message incomplet 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 champs dont les validations échouent, 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 tous les champs d'un formulaire est suivie automatiquement dans l'objet contexte. Cela peut être utile pour créer diverses interfaces. Par exemple, si vous souhaitez qu'un bouton de soumission soit désactivé tant que tous les champs ne sont pas valides, vous pouvez utiliser la propriété state.valid pour ce faire.
Dans l'exemple ci-dessus, nous extrayons l'objet contexte de l'emplacement #default, mais il existe d'autres méthodes. L'objet contexte est disponible sur le nœud principal de chaque champ sur la propriété node.context, et vous pouvez récupérer le nœud d'un champ de plusieurs façons.
Pour désactiver tous les champs d'un formulaire donné, y compris le bouton de soumission, vous pouvez utiliser la prop disabled.
Lors de l'utilisation d'un gestionnaire de soumission asynchrone @submit avec FormKit, le formulaire sera automatiquement désactivé (et l'état sera défini 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).
Lors de l'utilisation de l'API de composition, vous pouvez accéder directement à la fonction de réinitialisation en l'important depuis le noyau : 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. Vous pouvez avoir une valeur par défaut :value ou v-model sur le formulaire et sur les entrées individuelles du formulaire - FormKit fusionne automatiquement ces éléments pour produire votre valeur initiale et restaurera cet état fusionné lors de la réinitialisation.
Vous pouvez éventuellement fournir un deuxième argument à reset(formId, initialState) si vous préférez un état de réinitialisation alternatif.
Avec FormKit, ajouter une validation côté client à votre formulaire est facile - mais qu'en est-il des erreurs générées 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 pour toute entrée FormKit, vous pouvez attribuer directement 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 car votre gestionnaire de soumission reçoit l'objet node du formulaire en tant que 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 donnant un id au formulaire, puis en appelant $formkit.setErrors('id', ['Form error here']). La méthode setErrors doit recevoir l'id du formulaire, puis peut gérer 1 ou 2 arguments supplémentaires - les erreurs de formulaire et les erreurs d'entrée :
Par défaut, les erreurs définies sur les entrées à l'aide de setErrors() sont automatiquement effacées lorsque l'utilisateur modifie la valeur de cette entrée. Vous pouvez modifier 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 seul formulaire :
Lors de l'utilisation de 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 d'entrée (celles à afficher avec des entrées spécifiques dans un formulaire) peuvent être appliquées de trois manières :
errors sur chaque entrée individuelle.input-errors sur le formulaire (fonctionne également avec les groupes et les listes).$formkit.setErrors() (voir exemple ci-dessus).errorsLa manière la plus simple d'afficher des erreurs sur un formulaire est d'utiliser la propriété errors qui est disponible sur chaque entrée FormKit.
input-errorsVous pouvez également définir des messages d'erreur pour toutes les entrées 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 d'entrée (adresses de nœuds relatives sont prises en charge) et la valeur est une erreur ou un tableau d'erreurs à appliquer à cette entrée.
Par défaut, la validation d'un formulaire et les messages d'erreur sont placés directement au-dessus de la section des actions du formulaire. Cependant, vous pouvez choisir de les afficher 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 endroit :
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 en tant que prop à <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 | Par défaut | Description |
|---|---|---|
node | hérité | Le nœud central pour afficher les messages. Par défaut, il 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 les autres sections de messages d'entrée). |
defaultPosition | false | Par défaut, FormKitMessages déplace les messages rendus vers un nouvel emplacement. Si vous souhaitez afficher les messages dans les deux emplacements, définissez cette prop sur true. |
Lorsque les entrées sont démontées d'un formulaire — par exemple lors de l'utilisation de v-if — la clé et la valeur sont supprimé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 la suppression de l'entrée. Ceci peut être réalisé en utilisant la prop preserve :
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. |