FormKit rend la validation côté client simple en vous permettant de déclarer vos règles de validation directement sur vos entrées. Il est facile d'écrire des règles personnalisées aussi, mais vous en aurez rarement besoin avec plus de 20 règles prêtes à l'emploi.
Déclarer quelles règles de validation s'appliquent à une entrée donnée est aussi simple que de fournir une propriété validation. Les règles peuvent être déclarées en utilisant deux syntaxes :
Les règles de validation peuvent être déclarées en spécifiant chaque nom de règle souhaité séparé par des barres verticales |. Certaines règles peuvent également accepter des arguments, qui peuvent être fournis après un deux-points :. Vous pouvez utiliser plusieurs arguments en les séparant par des virgules :
Les règles de validation peuvent également être déclarées en fournissant un tableau. Chaque élément du tableau doit être lui-même un tableau où le premier élément est le nom de la règle de validation en chaîne, et les n éléments restants sont des arguments pour cette règle.
Cela est particulièrement utile si les arguments fournis doivent être de véritables types JavaScript — par exemple, une expression régulière (regex) :
Les règles de validation sont toujours calculées en temps réel — ce qui signifie qu'un champ donné sera toujours valide ou invalide (il est considéré comme invalide en attendant l'exécution des règles de validation asynchrones). Cependant — la visibilité des erreurs de validation est déterminée par la propriété validation-visibility.
| Visibilité | Description |
|---|---|
| blur | (Par défaut) Les erreurs sont affichées après qu'un utilisateur retire le focus d'une entrée. |
| live | Les erreurs sont toujours visibles. |
| dirty | Les erreurs sont affichées après qu'un utilisateur modifie la valeur d'une entrée. |
| submit | Les erreurs sont affichées uniquement après qu'un utilisateur tente de soumettre un formulaire. |
Si une entrée est à l'intérieur d'un formulaire, alors tous les messages de validation restants seront affichés à l'utilisateur final lorsque celui-ci tente de soumettre le formulaire.
Grâce à l'héritage de configuration de FormKit, vous pouvez définir validation-visibility au niveau d'un form, group, ou list en utilisant la propriété config, que vous pouvez toujours remplacer pour chaque entrée individuellement :
Les règles de validation fonctionnent selon quelques caractéristiques par défaut, que vous pouvez modifier au cas par cas avec des "indices de règles" :
required|length:5, alors la règle length ne s'exécutera pas tant que la règle required n'est pas validée.required est la seule exception).Les caractéristiques ci-dessus peuvent être modifiées lors de la déclaration de vos règles en utilisant des "indices". Les indices de règles sont de petits caractères modificateurs que vous ajoutez au début d'une déclaration de règle pour changer son comportement par défaut :
| Indice | Nom | Description |
|---|---|---|
(200) | Temporisation | Temporise la règle de validation par le nombre de millisecondes indiqué. |
+ | Vide | Exécute la règle de validation même si l'entrée est vide (mais ne force pas la règle). |
* | Force | Exécute la règle de validation même si une règle précédente a échoué. |
? | Optionnel | Rend une règle de validation optionnelle (elle est non-bloquante, ce qui signifie que le formulaire peut toujours être soumis). |
(milli)Il est parfois judicieux de temporiser vos règles de validation. Pour ce faire, utilisez l'indice de temporisation — une parenthèse contenant une durée en millisecondes — avant votre règle :
+ VideParfois, vous souhaitez qu'une règle de validation s'exécute même lorsque une entrée est vide. Vous pouvez utiliser l'indication + vide pour cela :
*L'indication de force assure qu'une règle de validation s'exécutera même si une règle définie avant elle échoue (note : cela ne signifie pas qu'elle s'exécutera lorsque une entrée est vide). Remarquez comment cet exemple affichera les deux messages length et email :
?L'indication optionnelle permet à une règle de validation échouée de ne pas empêcher la soumission du formulaire. Dans cet exemple, remarquez comment le formulaire ne sera pas soumis si les règles required ou confirm échouent, mais il sera soumis si la règle length indiquée comme optionnelle échoue :
Vous pouvez utiliser les indications de règles ensemble. Pour ce faire, placez simplement plusieurs indications avant la déclaration de la règle : required|*+(200)min:10.
FormKit est livré avec plus de 20 règles de validation prêtes à l'emploi, couvrant la plupart des besoins de validation. Si vous ne trouvez pas celle qui répond à votre exigence exacte, vous pouvez ajouter une règle personnalisée pour répondre à vos besoins.
La valeur doit être yes, on, 1 ou true. Utile pour les entrées de type case à cocher — souvent là où vous devez valider si quelqu'un a accepté les termes.
Vérifie si une valeur contient uniquement des caractères alphabétiques. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù ou ś.
Vérifie si une valeur est uniquement composée de caractères alphabétiques ou de chiffres numériques. Pour la partie alphabétique, vous pouvez passer default ou latin - voir alpha ci-dessus.
Vérifie si une valeur est uniquement composée de caractères alphabétiques ou d'espaces. Pour la partie alphabétique, vous pouvez passer default ou latin - voir alpha ci-dessus.
Vérifie si un nombre est (inclusivement) entre deux autres nombres. La valeur entrée doit être un nombre, sinon la règle de validation échouera.
Vérifie si la valeur d'une entrée correspond à la valeur d'une autre entrée — souvent utilisé pour les confirmations de mot de passe. Il y a deux façons de spécifier quelle entrée doit correspondre :
_confirm à l'attribut name de la seconde entrée.name de la première entrée comme argument à la règle de confirmation dans la seconde entrée confirm:name_of_input_1 (plus spécifique).Note : les deux entrées doivent être dans le même group ou form.
Vérifie si une valeur contient des caractères alphabétiques. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù ou ś.
Vérifie si une valeur contient des caractères alphabétiques ou des chiffres numériques. Pour la partie alphabétique, vous pouvez passer default ou latin - voir contient alpha ci-dessus.
Vérifie si une valeur contient des caractères alphabétiques ou des espaces. Pour la partie alphabétique, vous pouvez passer default ou latin - voir contient alpha ci-dessus.
Vérifie si une valeur contient un caractère en minuscule. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù, ou ś.
Vérifie si une valeur contient un chiffre.
Vérifie si une valeur contient un symbole.
Vérifie si une valeur contient un caractère en majuscule. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù, ou ś.
Détermine si une date est postérieure à la date actuelle ou à une date fournie en argument de la règle. Les dates utilisées peuvent être des objets Date de JavaScript ou des chaînes qui peuvent être analysées par Date.parse().
Détermine si une date est antérieure à la date actuelle ou à une date fournie en argument de la règle. Les dates utilisées peuvent être des objets Date de JavaScript ou des chaînes qui peuvent être analysées par Date.parse().
Détermine si une date se situe entre (et inclut) les deux dates fournies en arguments de la règle. Les dates utilisées peuvent être des objets Date de JavaScript ou des chaînes qui peuvent être analysées par Date.parse().
Assurez-vous que le format de la date saisie correspond à un format de date spécifique. Le format doit être spécifié en utilisant les jetons de formatage suivants :
| Jeton | Valeurs valides |
|---|---|
| MM | Représentation du mois sur deux chiffres (01-12) |
| M | Représentation du mois sur un chiffre (1-12), zéro autorisé |
| DD | Jour du mois sur deux chiffres (01-31) |
| D | Jour du mois sur un chiffre (1-31), zéro autorisé |
| YY | Année sur deux chiffres |
| YYYY | Année sur quatre chiffres |
Les champs de date natifs produisent toujours le même format YYYY-MM-DD ... même s'ils affichent les dates selon la locale du navigateur. Utiliser cette règle pour spécifier un format différent résulterait en un champ qui ne pourrait jamais être valide.
Vérifie si le champ contient une adresse email valide.
Vérifie si la valeur du champ se termine par une sous-chaîne donnée.
Vérifie que la valeur du champ correspond à au moins un des arguments fournis.
Vérifie que la valeur du champ dépasse une longueur donnée, ou se situe entre deux valeurs de longueur. Cela fonctionne pour valider des tableaux (comme les listes), des objets (comme les groupes), ou des longueurs de chaînes de caractères. Peut être utilisé pour simuler les attributs natifs maxlength et minlength également.
Vérifie si une valeur est composée uniquement de caractères minuscules. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù, ou ś.
Vérifie si l'entrée correspond à une valeur ou un motif particulier. Si vous passez plusieurs arguments, il vérifie chacun jusqu'à ce qu'une correspondance soit trouvée.
Au lieu de passer des chaînes de caractères dans la propriété de validation pour une correspondance simple, vous pouvez formater votre argument avec des barres obliques / pour passer votre propre expression régulière.
Lorsque vous utilisez la Syntaxe de chaîne, vous ne pouvez pas échapper aux caractères utilisés pour définir les règles de validation elles-mêmes (|,:). Pour utiliser ces caractères dans vos expressions régulières, vous devez utiliser l'alternative Syntaxe de tableau.
Vérifie qu'un Number est inférieur ou égal à une valeur maximale. La valeur maximale par défaut est 10.
Vous pouvez également utiliser cette règle pour valider que la longueur d'un Array est inférieure ou égale à une valeur maximale.
Vérifie qu'un Number est supérieur ou égal à une valeur minimale. La valeur minimale par défaut est 1.
Vous pouvez également utiliser cette règle pour valider que la longueur d'un Array est supérieure ou égale à une valeur minimale.
Vérifie pour s'assurer que les données saisies ne correspondent pas à un ensemble de valeurs prédéfinies.
Vérifie si l'entrée est un nombre valide évalué par isNaN().
Vérifie si l'entrée est vide.
Si vous ne voulez pas que les espaces blancs permettent à la règle required d'être validée, vous pouvez passer trim comme argument à la règle :
Vérifie plusieurs entrées et valide si l'une d'elles a une valeur.
Note : les deux entrées doivent être dans le même group ou form.
Vérifie si l'entrée commence par l'une des options fournies.
Vérifie si une valeur est composée uniquement de symboles.
Vérifie si une valeur est composée uniquement de caractères majuscules. Il existe deux ensembles de caractères : latin et par défaut. Les caractères latins sont strictement [a-zA-Z], tandis que l'ensemble par défaut inclut la plupart des caractères accentués, tels que ä, ù, ou ś.
Vérifie si la valeur saisie semble être une URL correctement formatée, y compris le protocole. Cela ne vérifie pas si l'URL est réellement résolue.
Les règles de validation sont des fonctions qui acceptent un nœud central et retournent une valeur booléenne — true pour un succès et false pour un échec. De plus, tous les arguments passés à la règle de validation sont disponibles en tant qu'arguments 1-n. Écrire la vôtre est simple — par exemple :
/**
* Fichier : my-custom-rules/monday.js
*
* Une règle de validation artificielle qui assure que la valeur saisie est lundi ou lun.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
export default monday
Comme mentionné dans la section astuces pour les règles de validation, les règles de validation — y compris vos règles personnalisées — fonctionnent selon des comportements par défaut : elles s'exécutent en séquence, sont ignorées lorsque la valeur de l'entrée est vide, sont synchrones et bloquantes. Si vous souhaitez que les comportements par défaut de votre règle fonctionnent différemment, vous pouvez les remplacer sur votre règle de validation personnalisée :
/**
* Une règle de validation artificielle qui assure que la valeur saisie est lundi ou lun.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
// remplacer les comportements par défaut de la règle pour votre règle personnalisée
monday.blocking = false
monday.skipEmpty = false
monday.debounce = 20 // millisecondes
monday.force = true
export default monday
Vous pouvez également remplacer ces comportements au cas par cas avec les astuces pour les règles de validation.
Une fois que vous avez écrit une fonction de validation — vous devez enregistrer la règle de validation avec FormKit — soit globalement, soit spécifiquement sur une entrée.
Les règles de validation peuvent dépendre des valeurs d'autres entrées dans l'arborescence de votre formulaire. Pour ce faire, utilisez la traversée de nœuds pour localiser un autre nœud et accéder à sa valeur :
Les règles de validation doivent toujours être des fonctions pures. Utilisez uniquement les arguments passés et ne réalisez aucun effet de bord.
Pour utiliser une règle de validation n'importe où dans votre projet, vous pouvez la spécifier là où votre plugin FormKit est enregistré avec Vue.
import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'
// prettier-ignore
createApp(App).use(plugin, defaultConfig({
rules: { monday },
})).mount('#app')
Une fois installée, vous pouvez utiliser votre règle de validation n'importe où dans votre projet.
<FormKit validation="required|monday" />
Pour personnaliser le message d'erreur qui apparaît lorsque votre validation personnalisée échoue, suivez les instructions ici.
Pour ajouter une validation à un champ spécifique, utilisez la prop validation-rules.
Vos règles personnalisées nécessitent probablement un message personnalisé — la section suivante de la documentation couvrira cela.
Il existe plusieurs façons de personnaliser votre message de validation. La plus simple est d'utiliser la prop validation-label — vous permettant de changer le nom du champ tel qu'il est utilisé dans les messages de validation prédéfinis.
Si vous avez besoin d'être plus spécifique, vous avez deux options :
Vous pouvez facilement remplacer les messages de validation directement sur votre champ FormKit en fournissant un objet de chaînes de caractères ou de fonctions.
Pour remplacer un message de validation sur un seul champ FormKit, ajoutez la prop validation-messages avec un objet de noms de règles et un message correspondant.
Si vous avez besoin de plus de puissance pour vos règles de validation, vous pouvez utiliser une fonction au lieu d'une chaîne de caractères. La fonction reçoit un objet contexte.
| Comportement | Description |
|---|---|
| args | Un tableau d'arguments passés à la règle. Par exemple 'Vue', 'React', 'Angular' de la règle is:Vue,React,Angular. |
| name | Le nom du champ (premier disponible parmi : validation-label, label, puis name). |
| node | Le noeud central node de FormKit. |
Réécrivons l'exemple ci-dessus en utilisant une fonction au lieu d'une chaîne de caractères pour encore plus de contrôle sur la prop validation-messages :
Si vous souhaitez remplacer (ou ajouter) des messages de règles de validation dans l'ensemble de votre projet, vous pouvez définir ces règles de messages lors de l'enregistrement de FormKit sous la clé de langue que vous souhaitez remplacer :
import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'
// prettier-ignore
createApp(App).use(plugin, defaultConfig({
messages: {
fr: {
validation: {
required({ name }) {
return `Veuillez remplir le champ ${name}.`
}
}
}
}
})).mount('#app')
Si vous souhaitez afficher les messages de validation d'un champ en dehors du composant <FormKit />, vous pouvez utiliser le composant <FormKitMessages /> en passant le nœud du champ en tant que prop. L'utilisation de ce composant désactive l'affichage par défaut des messages (situés sous le champ) et les déplace là où se trouve le composant <FormKitMessages /> :
FormKit 1.0.0 a introduit le composant FormKitSummary qui offre une solution "clé en main" pour afficher tous les messages de validation dans un formulaire donné ou un sous-arbre.
Pour obtenir tous les messages de validation du nœud central d'un champ, vous pouvez utiliser la fonction getValidationMessages exportée depuis @formkit/validation. Cette fonction vérifiera de manière récursive le nœud donné et tous ses enfants pour les messages de validation et retournera une Map des nœuds centraux aux messages de validation, ce qui la rend idéale pour une utilisation avec des formulaires :