Les entrées FormKit sont similaires aux entrées HTML mais suralimentées avec des fonctionnalités très nécessaires comme les labels, le texte d'aide, la validation, et les messages d'erreur (et bien plus encore). De la même manière que la balise <input> de HTML utilise divers attributs type (c'est-à-dire, <input type="text"> vs <input type="checkbox">), FormKit utilise la prop type pour toutes les entrées. En fait, avec FormKit, il n'y a qu'un seul composant que vous devez apprendre :
Les entrées FormKit ne sont pas limitées à ce qui est disponible en HTML "natif". Notre package séparé FormKit Pro offre un accès à des types d'entrée "synthétiques" tels que repeater, autocomplete, mask, rating et plus encore. Bien sûr, vous pouvez aussi écrire vos propres entrées en créant des entrées personnalisées.
Bien que vous soyez libre d'utiliser les entrées FormKit par elles-mêmes, vous voudrez généralement les grouper dans un formulaire :
<FormKit type="form">
<!-- ... vos entrées de formulaire -->
</FormKit>
Le type de formulaire offre une multitude de fonctionnalités, notamment la collecte de valeurs, la définition de valeurs initiales, la soumission de formulaires, la gestion des erreurs, les états de chargement, et plus encore.
Il y a 4 façons de définir la valeur d'une entrée :
value (Note : ne définit que la valeur initiale).v-model.node.input() de FormKit.FormKit.valueVous pouvez définir la valeur initiale d'une seule entrée ou d'un groupe d'entrées en utilisant la prop value.
La prop value ne doit être utilisée que pour définir la valeur initiale d'une entrée. Elle ne réagira pas aux changements après la création du composant.
v-modelL'utilisation de v-model permet une liaison de données réactive bidirectionnelle avec n'importe quelle entrée FormKit.
node.input()Au cœur de chaque entrée FormKit se trouve une instance de l'objet node de FormKit, et l'utilisation de la méthode node.input() est le mécanisme le plus efficace pour modifier la valeur de n'importe quelle entrée (en savoir plus sur l'obtention d'une instance de l'objet node).
Les appels à node.input() sont espacés, et donc asynchrones (utilisez la prop delay pour changer la longueur de l'espacement). Vous pouvez await node.input(val) pour déterminer quand l'entrée s'est stabilisée.
Les entrées parentes comme list, group et form sont également capables de définir directement les valeurs de leurs enfants. En fait, la valeur d'un parent est simplement la valeur agrégée de ses enfants. Vous pouvez utiliser l'une des méthodes ci-dessus (value prop, v-model, ou node.input()) pour définir la valeur des enfants.
Dans presque tous les cas, les attributs définis sur le composant <FormKit> seront transmis à l'élément <input> réel au cœur du composant, plutôt qu'à tout élément DOM d'emballage. Par exemple :
Nous discutons de la validation en détail sur sa propre page de documentation — mais il suffit de dire que l'ajout de règles de validation aux entrées dans FormKit est aussi facile que d'ajouter la prop validation :
Pour des raisons de performance, toutes les entrées FormKit prennent en charge le debouncing en tant que fonctionnalité de première classe. Alors que la valeur d'une entrée change à chaque frappe (techniquement l'événement input), cette valeur nouvellement mise à jour n'est définie qu'en interne — les règles de validation, les groupes, les listes, les formulaires et (la plupart des) plugins ne sont pas encore "conscients" qu'un changement a été effectué.
En interne, FormKit débounce l'événement input. Lorsque le debounce est "stabilisé", la nouvelle valeur est "validée" et le reste de l'application est alors notifié via l'événement commit du nœud d'entrée. Le délai de debounce par défaut est de 20 millisecondes et peut être ajusté avec la prop delay ou l'option de configuration.
Pour illustrer cela, récupérons la value du group à partir de la prop de slot #default et observons comment elle n'est pas mise à jour avant la fin de notre delay de 1000ms :
La valeur par défaut de la prop delay est de 20 millisecondes. Cependant, les entrées group et list utilisent 0 millisecondes par défaut pour éviter que le délai de debounce ne s'accumule à chaque niveau de profondeur.
Les erreurs de validation ne sont pas la seule façon de définir des erreurs sur une entrée. Vous pouvez également définir explicitement des messages d'erreur sur une entrée en utilisant la prop errors.
Les erreurs définies explicitement ne sont pas bloquantes, ce qui signifie qu'elles n'empêchent pas le formulaire d'être soumis de la même manière que les erreurs de validation. Vous pouvez en savoir plus sur la gestion des erreurs dans la documentation du formulaire.
Les entrées FormKit acceptent à la fois des props universels (ceux qui s'appliquent à toutes les entrées FormKit), et des props spécifiques à l'entrée. Le tableau suivant est une liste complète des props disponibles pour toutes les entrées FormKit.
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| 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.. |
Les entrées FormKit émettent à la fois des événements universels (ceux qui sont émis par toutes les entrées), et des événements spécifiques à l'entrée. Le tableau suivant est une liste complète des événements émis par toutes les entrées FormKit.
| Event | Payload | Description |
|---|---|---|
| input | any | Emitted when the core node’s commit hook is completed. Has it’s own debounce to reduce noise. Includes the core node as the second argument. |
| input-raw | any | Emitted on every core node’s commit hook. Includes the core node as the second argument. |
| node | FormKitNode | Emitted when the component’s setup is complete. This is the internal FormKitNode object at the heart of the input. |
Ce qui précède sont des événements Vue émis par @formkit/vue. @formkit/core émet également ses propres événements dans le cadre du cycle de vie des nœuds centraux.
Les entrées sont composées de morceaux de HTML appelés "sections". Chaque section a une "clé" qui peut être utilisée pour cibler la section à diverses fins, comme :
{section-key}-class="your-class"<template #{section-key}>De nombreuses clés de section sont universellement disponibles tandis que d'autres sont spécifiques à un type d'entrée donné (vous pouvez définir les vôtres pour des entrées personnalisées également). Le tableau suivant est une liste complète de ceux qui sont généralement disponibles dans toutes les entrées :
| Section-key | Description |
|---|---|
| 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. |
Parfois, vous pouvez trouver nécessaire de restructurer le HTML à l'intérieur d'une entrée FormKit, comme ajouter, modifier, déplacer, ou supprimer des sections. Cela peut être fait en exportant l'entrée (en utilisant l'outil CLI), en apportant les modifications souhaitées, puis en utilisant l'entrée modifiée dans votre projet. Lisez le guide sur l'exportation des entrées pour savoir comment faire.
Les entrées peuvent avoir leur structure remplacée par des slots. Vous pouvez cibler précisément où va le contenu de votre slot avec les clés de section. Les slots sont ensuite passés à l'objet contexte pour être utilisés dans leur template.
Par exemple, si nous voulions utiliser un slot pour définir le label d'une entrée, nous pourrions utiliser un slot label pour le faire :
Un inconvénient de l'utilisation des slots est que vous devez souvent recréer des fonctionnalités non liées pour effectuer le changement que vous désirez. Par exemple, l'utilisation de slots vous obligerait à réimplémenter toutes les classes appliquées à ces sections (ce qui peut être fait en utilisant context.classes.sectionName).
Pour aider à résoudre ce problème, FormKit est également capable de remplacer/s'étendre sélectivement le schéma sous-jacent de chaque section permettant une modification structurelle complexe souvent sans perte de fonctionnalité.
FormKit fournit un mécanisme supplémentaire pour modifier la structure d'une entrée FormKit appelée "schéma des sections". Sous le capot, toutes les entrées FormKit sont alimentées par le schéma de FormKit — un format de données compatible JSON pour créer et stocker la structure DOM et la logique. Cela permet une flexibilité structurelle énorme car toutes les entrées peuvent avoir des parties de leur schéma étendues via des clés de section sans remplacement en gros du modèle.
Par exemple, par défaut, FormKit utilise une liste non ordonnée (<ul> et <li>) pour afficher les messages de validation — mais peut-être avez-vous besoin d'utiliser des balises <div>. Vous pouvez changer ces balises en utilisant la propriété schema sans avoir à recréer aucune fonctionnalité :
Pour l'accessibilité et la flexibilité, FormKit utilise plusieurs éléments d'enveloppe comme ceux dans les sections wrapper et inner. Cependant, peut-être que sur certaines entrées, vous devez supprimer un élément d'enveloppe pour vous assurer que d'autres éléments sont adjacents. Vous pouvez le faire en fournissant une valeur null comme élément de schéma :
Les schémas de section peuvent également changer le contenu qui est affiché en utilisant une logique de schéma avancée. Vous pourriez, par exemple, afficher une valeur spéciale lorsque la valeur de votre entrée correspond à une chaîne particulière :