FormKit est livré avec un plugin d'entrée multi-étapes de première partie disponible dans le package @formkit/addons. Cette entrée vous permet de construire un assistant ou de diviser facilement vos formulaires en plusieurs étapes. Diviser les formulaires en plusieurs étapes peut améliorer l'expérience utilisateur des formulaires plus importants en les rendant petits et accessibles par rapport à la liste de toutes les entrées en une fois.
Pour utiliser ce plugin avec FormKit, installez @formkit/addons :
yarn add @formkit/addons
Une fois que vous avez installé le package addons, vous devrez enregistrer le plugin avec FormKit et inclure les styles CSS de support :
// formkit.config.js
import { defaultConfig } from '@formkit/vue'
import { createMultiStepPlugin } from '@formkit/addons'
import '@formkit/addons/css/multistep'
const config = defaultConfig({
plugins: [createMultiStepPlugin()],
})
export default config
multi-step en action :La fonction createMultiStepPlugin enregistre deux nouveaux types d'entrée pour que vous puissiez les utiliser avec le composant FormKit.
multi-step : Le groupe englobant pour l'entrée multi-étapes entière. Cette entrée suit quelle étape est active, la validation et les erreurs par étape, et ne doit contenir que des entrées step comme enfants immédiats.step : Le groupe englobant pour une étape donnée dans votre entrée multi-étapes. Ne doit être qu'un enfant immédiat d'une entrée multi-step. Ses enfants seront rendus comme le contenu de l'étape.Utiliser ces entrées ensemble est aussi simple que d'englober tout balisage que vous souhaitez avoir présent dans une étape d'un formulaire multi-étapes.
<FormKit type="multi-step">
<FormKit type="step" name="stepOne">
<!-- le contenu pour stepOne va ici ! -->
</FormKit>
</FormKit>
Dès le départ, l'entrée parent multi-step suivra la validité des entrées contenues dans chaque entrée enfant step et empêchera de passer à l'étape suivante step jusqu'à ce que l'étape actuelle soit valide. Le nombre total de validations bloquantes et d'erreurs sera affiché à côté du nom de l'étape actuelle si un utilisateur tente de passer à l'étape suivante ou de soumettre le formulaire avant de satisfaire aux validations d'entrée de l'étape actuelle.
L'entrée multi-step est livrée avec deux styles d'onglets disponibles.
tab : L'expérience par défaut des onglets. Le nom de chaque étape est affiché dans un onglet avec un état actif. Le nombre d'erreurs est affiché en haut à droite de l'onglet.progress : Un style de barre de progression où chaque étape est un "nœud" sur une chronologie des étapes totales. Avec ce mode d'affichage, vous pouvez également utiliser la propriété hide-progress-labels pour masquer les noms des étapes.Par défaut, l'entrée multi-step utilisera l'attribut name de ses entrées step enfants pour générer des étiquettes pour les étapes. Si vous souhaitez avoir plus de contrôle sur l'affichage de vos noms d'étapes, vous pouvez utiliser la propriété label. Vous pouvez également personnaliser les étiquettes qui apparaissent dans la section stepActions de votre step en utilisant les propriétés previous-label et next-label.
label : Une substitution pour le nom de l'étape qui doit apparaître dans les onglets multi-étapes.previous-label : une substitution pour l'étiquette du bouton stepPrevious qui par défaut est Back.next-label : une substitution pour l'étiquette du bouton stepNext qui par défaut est Next.Par défaut, l'entrée multi-step permettra de passer aux étapes suivantes même si l'étape actuelle ou une étape entre l'étape actuelle et l'étape cible a des messages de validation bloquants. Pour empêcher un utilisateur de sauter en avant, définissez la propriété allow-incomplete sur false.
Lorsqu'une étape a été complétée sans erreurs de validation, l'entrée multi-step affichera — par défaut — une icône de vérification indiquant que l'étape est valide et qu'aucune autre action n'est requise. L'valid-step-icon est une Icône FormKit et peut être changée via une propriété comme toute autre icône FormKit.
Vous pouvez soit :
valid-step-icon sur l'entrée multi-step pour changer l'icône pour toutes les étapes à l'intérieur de l'entrée.valid-step-icon sur une entrée step pour changer ou remplacer l'icône juste pour cette étape.Chaque step dans une entrée multi-step a des boutons par défaut rendus pour se déplacer entre les étapes. Par défaut, le premier step dans un multi-step n'aura qu'un bouton d'action stepNext rendu, et le dernier step n'aura qu'un bouton d'action stepPrevious. Cela permet à un multi-step d'agir comme un groupe autonome dans le contexte d'un formulaire plus large.
Si vous souhaitez ajouter une action personnalisée telle qu'une soumission de formulaire à un multi-step — utile si vous utilisez le multi-step comme votre formulaire entier — vous pouvez le faire en remplaçant l'emplacement stepNext sur l'étape souhaitée. Dans ce cas, nous ajouterons une entrée submit à la dernière étape de notre entrée multi-step pour soumettre le formulaire.
Les sections stepNext et stepPrevious ont accès au gestionnaire incrementStep — qui retourne une fonction appelable — pour activer la navigation programmatique.
Par défaut, le stepNext dans une entrée multi-step utilise des écouteurs d'événements pour capturer la navigation par onglets via le clavier et permettre aux utilisateurs de parcourir toutes les étapes disponibles au sein d'un multi-step.
Si vous souhaitez préserver ce comportement dans votre propre implémentation de stepNext, assurez-vous d'ajouter un attribut data-next="true" à votre élément focusable qui déclenche la navigation d'étape.
Parfois, vous avez besoin de faire quelque chose avec vos données de formulaire entre les étapes. Peut-être que vous souhaitez soumettre chaque étape indépendamment à votre back-end ou que vous avez besoin de consigner des événements analytiques pour déterminer jusqu'où les utilisateurs avancent dans votre formulaire. Dans des cas comme ceux-ci, vous pouvez utiliser l'événement beforeStepChange. beforeStepChange accepte une fonction et fournit un objet contexte avec les clés suivantes :
currentStep : L'objet contexte du nœud d'étape actuellement actif dont l'utilisateur s'éloigne.targetStep : L'objet contexte du nœud d'étape vers lequel l'utilisateur se dirige.delta : La distance entre les étapes. Les entiers positifs représentent l'avancement, les entiers négatifs représentent le recul.Votre fonction beforeStepChange doit retourner un Boolean. Retourner false empêchera le changement d'étape de se produire.
beforeStepChange peut être utilisé sur votre entrée multi-step auquel cas il s'appliquera à toutes les étapes. De plus, vous pouvez utiliser beforeStepChange sur une entrée step spécifique pour exécuter votre fonction uniquement lors de la navigation à partir de l'étape qui a la fonction assignée. beforeStepChange appliqué à un step remplacera tout beforeStepChange défini sur un multi-step parent s'il en existe un.
Le nœud multi-étapes est équipé de fonctions d'assistance pratiques conçues pour faciliter la navigation programmatique entre n'importe laquelle de ses étapes. Ces fonctions comprennent :
next : Elle permet de passer à l'étape suivante à partir de l'étape actuellement sélectionnée.previous : Elle permet de revenir à l'étape précédente à partir de l'étape actuellement sélectionnée.goTo : Elle accepte un argument étape pour se déplacer vers cette étape à partir de l'étape actuellement sélectionnée, elle accepte l'index ou le nom de l'étape.| Prop | Type | Par défaut | Description |
|---|---|---|---|
| allowIncomplete | boolean | true | Lorsque true, permet aux utilisateurs de naviguer entre les étapes même si l'étape actuelle est invalide. |
| tabStyle | string | tab | Utilisé pour définir un attribut de données pour créer des styles d'onglets. Le thème par défaut est livré avec le support des styles d'onglets tab et progress. |
| hideProgressLabels | boolean | false | Lorsque vrai, cache les étiquettes pour le style d'onglet progress. |
| validStepIcon | string | check | Spécifie une icône à placer dans la section badge lorsqu'une étape est valide. Lorsqu'appliquée au multi-step, l'icône sera appliquée à toutes les entrées step enfants. |
| beforeStepChange | function | undefined | Une fonction à exécuter avant que l'étape active ne soit changée. La fonction est fournie avec un objet contexte contenant currentStep et targetStep qui sont tous deux des objets de contexte de nœud FormKit. De plus, delta est fourni comme un entier qui reflète la distance entre currentStep et targetStep. Lorsqu'elle est fournie au multi-step, cette fonction se déclenchera à chaque changement d'étape. |
| 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.. |
| Prop | Type | Par défaut | Description |
|---|---|---|---|
| label | string | Utilisé pour changer l'étiquette de l'onglet de l'étape. Si aucune étiquette personnalisée n'est fournie, le nom de l'étape sera utilisé. | |
| previousLabel | string | Précédent | Utilisé pour changer l'étiquette du bouton previousAction par défaut. |
| nextLabel | string | Suivant | Utilisé pour changer l'étiquette du bouton nextAction par défaut. |
| previousAttrs | object | [object Object] | Utilisé pour appliquer des attributs au bouton d'action previousAction par défaut. |
| nextAttrs | object | [object Object] | Utilisé pour appliquer des attributs au bouton d'action nextAction par défaut. |
| validStepIcon | string | check | Spécifie une icône à placer dans la section badge lorsque l'étape est valide. Lorsqu'appliquée à une étape, l'icône ne sera appliquée qu'à l'étape ciblée. |
| beforeStepChange | function | undefined | Une fonction à exécuter avant que l'étape active ne soit changée. La fonction est fournie avec un objet contexte contenant currentStep et targetStep qui sont tous deux des objets de contexte de nœud FormKit. De plus, delta est fourni comme un entier qui reflète la distance entre currentStep et targetStep. Lorsqu'elle est fournie à une étape, cette fonction se déclenchera uniquement lors de la navigation à partir de l'étape spécifiée. |
| 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 |
|---|---|
| tabs | Un conteneur autour de tous les onglets. |
| tab | Un élément bouton qui contient le nom de l'onglet et le décorateur pour refléter l'état de validation. |
| tabLabel | Un élément span qui contient le nom de l'onglet. |
| badge | Un élément span utilisé comme décorateur pour montrer l'état de validité de l'onglet actuel. |
| steps | Un conteneur autour de toutes les étapes. |
| step | Un conteneur autour du contenu de l'étape du slot par défaut et des boutons d'action de l'étape. Chaque étape a un style de visibilité automatiquement appliqué en fonction de si c'est l'étape active actuelle. |
| stepInner | Un conteneur autour du contenu du slot par défaut pour une étape. |
| stepActions | Un conteneur autour des boutons d'action pour se déplacer entre les étapes. |
| stepPrevious | Un conteneur autour du bouton d'action pour naviguer à l'étape précédente. |
| stepNext | Un conteneur autour du bouton d'action pour naviguer à l'étape suivante. |
| 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. |