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 grands en les maintenant petits et accessibles par rapport à la liste de toutes les entrées en une seule fois.
Pour commencer, importez createMultiStepPlugin de @formkit/addons ainsi que les styles associés. Les styles sont complètement autonomes et n'ont aucune dépendance sur le thème genesis qui est livré avec FormKit. Cela signifie que si vous utilisez Tailwind pour styliser vos entrées, vos styles d'entrée s'afficheront toujours comme prévu lorsqu'ils sont enveloppés dans le type d'entrée multi-step.
// 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 configmulti-step en action :La fonction createMultiStepPlugin enregistre deux nouveaux types d'entrée que vous pouvez utiliser avec le composant FormKit.
multi-step: Le groupe d'enveloppe pour l'ensemble de l'entrée multi-étapes. Cette entrée garde une trace de l'étape active, de la validation et des erreurs par étape, et ne doit contenir que des entrées step en tant qu'enfants immédiatsstep: Le groupe d'enveloppe 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'envelopper n'importe quel balisage que vous voulez avoir présent dans une étape d'un formulaire multi-étapes.
<FormKit type="multi-step">
<FormKit type="step" name="stepOne">
<!-- le contenu de stepOne va ici ! -->
</FormKit>
</FormKit>Par défaut, l'entrée parent multi-step suit la validité des entrées contenues dans chaque entrée step enfant et empêche de passer à l'étape suivante tant que l'étape en cours n'est pas valide. Le nombre total de validations et d'erreurs bloquantes sera affiché à côté du nom de l'étape en cours si un utilisateur tente de passer à l'étape suivante ou de soumettre le formulaire avant de satisfaire les validations d'entrée de l'étape en cours.
L'entrée multi-step est livrée avec deux styles d'onglets disponibles.
tab : L'expérience par défaut des onglets. Chaque nom d'é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 du nombre total d'étapes. 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 des noms de vos é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 : Un remplacement pour le nom de l'étape qui doit apparaître dans les onglets multi-étapes.previous-label : un remplacement pour l'étiquette du bouton stepPrevious qui est par défaut Retour.next-label : un remplacement pour l'étiquette du bouton stepNext qui est par défaut Suivant.Par défaut, l'entrée multi-step permettra de passer à des étapes ultérieures 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 coche 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 modifié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 uniquement 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, la première step d'un multi-step n'aura qu'un bouton d'action stepNext rendu, et la dernière step n'aura qu'un bouton d'action stepPrevious. Cela permet à un multi-step de fonctionner comme un groupe autonome dans le contexte d'un formulaire plus grand.
Si vous souhaitez ajouter une action personnalisée, comme un envoi de formulaire à un multi-step — utile si vous utilisez le multi-step comme votre formulaire complet — vous pouvez le faire en écrasant 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 renvoie une fonction callable — pour permettre 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 dans un multi-step.
Si vous souhaitez conserver ce comportement dans votre propre implémentation stepNext personnalisée, assurez-vous d'ajouter un attribut data-next="true" à votre élément pouvant recevoir le focus qui déclenche la navigation d'étape.
Parfois, vous devez faire quelque chose avec vos données de formulaire entre les étapes. Peut-être que vous voulez soumettre chaque étape indépendamment à votre back-end ou que vous devez enregistrer des événements analytiques pour déterminer jusqu'où les utilisateurs parviennent à travers votre formulaire. Dans des cas comme ceux-ci, vous pouvez utiliser l'événement beforeStepChange. beforeStepChange accepte une fonction et se voit attribuer 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 renvoyer un Boolean. Renvoyer 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 à laquelle la fonction est attribuée. beforeStepChange appliqué à une step remplacera tout beforeStepChange défini sur un multi-step parent s'il en existe un.
| 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 true, masque 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'elle est appliquée au multi-step, l'icône sera appliquée à toutes les entrées d'étape enfants. |
| beforeStepChange | function | undefined | Une fonction à exécuter avant que l'étape active ne soit modifiée. La fonction est fournie avec un objet de contexte contenant currentStep et targetStep qui sont tous deux des objets de contexte FormKit node. De plus, delta est fourni sous la forme d'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 modifier l'étiquette de l'onglet de l'étape. Si aucune étiquette personnalisée n'est fournie, le name de l'étape sera utilisé. | |
| previousLabel | string | Précédent | Utilisé pour modifier l'étiquette du bouton previousAction par défaut. |
| nextLabel | string | Suivant | Utilisé pour modifier l'étiquette du bouton nextAction par défaut. |
| previousAttrs | object | [object Object] | Utilisé pour appliquer des attributs au bouton d'entrée previousAction par défaut. |
| nextAttrs | object | [object Object] | Utilisé pour appliquer des attributs au bouton d'entrée nextAction par défaut. |
| validStepIcon | string | check | Spécifie une icône à placer dans la section badge lorsque l'étape est valide. Lorsqu'elle est appliquée à une étape, l'icône ne sera appliquée qu'à l'étape cible. |
| beforeStepChange | function | undefined | Une fonction à exécuter avant que l'étape active ne soit modifiée. La fonction est fournie avec un objet de contexte contenant currentStep et targetStep qui sont tous deux des objets de contexte FormKit node. De plus, delta est fourni sous la forme d'un entier qui reflète la distance entre currentStep et targetStep. Lorsqu'elle est fournie à une étape, cette fonction ne se déclenchera que 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 à partir de l'emplacement par défaut et des boutons d'action de l'étape. Chaque étape a un style de visibilité automatiquement appliqué en fonction de si elle est l'étape active actuelle. |
| stepInner | Un conteneur autour du contenu de l'emplacement par défaut pour une étape. |
| stepActions | Un conteneur autour des boutons d'action pour passer d'une étape à l'autre. |
| stepPrevious | Un conteneur autour du bouton d'action pour naviguer vers l'étape précédente. |
| stepNext | Un conteneur autour du bouton d'action pour naviguer vers 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. |