FormKit simplifie la validation côté client 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 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 sous forme de 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 soit valide, soit invalide (il est considéré comme invalide pendant l'exécution des règles de validation asynchrones en attente). 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 que l'utilisateur ait retiré le focus d'une entrée. |
| live | Les erreurs sont toujours visibles. |
| dirty | Les erreurs sont affichées après que l'utilisateur ait modifié la valeur d'une entrée. |
| submit | Les erreurs sont affichées uniquement après que l'utilisateur ait tenté de soumettre un formulaire. |
Si une entrée se trouve à l'intérieur d'un formulaire, alors tous les messages de validation restants seront affichés à l'utilisateur final lorsqu'un utilisateur tente de soumettre le formulaire.
En raison de 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 au cas par cas pour chaque entrée :
Les règles de validation fonctionnent selon quelques fonctionnalités par défaut, que vous pouvez modifier au cas par cas avec des "indices de règles" :
required|length:5, la règle length ne s'exécutera pas tant que la règle required ne sera pas validée.required est la seule exception).Les fonctionnalités 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 modifier son comportement par défaut :
| Indice | Nom | Description |
|---|---|---|
(200) | Debounce | Temporise la règle de validation du nombre de millisecondes donné. |
+ | Empty | 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é. |
? | Optional | Rend une règle de validation facultative (elle n'est pas bloquante, le formulaire peut être soumis). |
(milli)Parfois, il est 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 :
+Parfois, vous voulez qu'une règle de validation s'exécute même lorsqu'une entrée est vide. Vous pouvez utiliser l'indice vide + pour ce faire :
*L'indice de force garantit 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 lorsqu'une entrée est vide). Remarquez comment cet exemple affichera les deux messages length et email :
?L'indice optionnel 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 avec l'indice optionnel échoue :
Vous pouvez utiliser les indices de règles ensemble. Pour ce faire, placez simplement plusieurs indices 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 en matière de validation. Si vous n'en trouvez pas une qui répond exactement à vos besoins, 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 case à cocher, souvent lorsque vous devez valider si quelqu'un a accepté les conditions.
Vérifie si une valeur ne contient que 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 comprend 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. 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) compris entre deux autres nombres. La valeur d'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ée pour les confirmations de mot de passe. Il existe deux façons de spécifier quelle entrée correspondre :
_confirm à l'attribut name de la deuxième entrée.name de la première entrée en argument de la règle de confirmation dans la deuxième entrée confirm:name_of_input_1 (plus spécifique).Remarque : 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 comprend la plupart des caractères accentués, tels que ä, ù ou ś.
Vérifie si une valeur contient des caractères alphabétiques ou des chiffres. 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 comprend la plupart des caractères accentués, tels que ä, ù ou ś.
Vérifie si une valeur contient un nombre.
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 comprend la plupart des caractères accentués, tels que ä, ù ou ś.
Détermine si une date est après 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 de caractères pouvant être analysées par Date.parse().
Détermine si une date est avant 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 de caractères pouvant être analysées par Date.parse().
Détermine si une date est entre (et y compris) 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 de caractères pouvant être analysées par Date.parse().
Assure que le format de la date d'une entrée 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) avec zéro autorisé |
| DD | Représentation du jour du mois sur deux chiffres (01-31) |
| D | Représentation du jour du mois sur un chiffre (1-31), zéro autorisé |
| YY | Représentation de l'année sur deux chiffres |
| YYYY | Représentation de l'année sur quatre chiffres |
Les entrées de date natives produisent toujours le même format YYYY-MM-DD ... même si elles affichent les dates selon la langue du navigateur. Utiliser cette règle pour spécifier un format différent entraînerait une entrée qui ne peut jamais être valide.
Vérifie si l'entrée contient une adresse e-mail valide.
Vérifie si la valeur de l'entrée se termine par une sous-chaîne donnée.
Vérifie que la valeur de l'entrée correspond à au moins l'un des arguments fournis.
Vérifie que la valeur de l'entrée est supérieure à une longueur donnée, ou entre deux valeurs de longueur. Il fonctionne pour valider les tableaux (comme les listes), les objets (comme les groupes), ou les longueurs de chaînes. Peut également être utilisé pour simuler les attributs natifs maxlength et minlength.
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 comprend 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 d'eux jusqu'à ce qu'une correspondance soit trouvée.
Au lieu de passer des chaînes dans la propriété de validation pour une correspondance simple, vous pouvez utiliser des barres obliques / pour passer votre propre expression régulière.
Lors de l'utilisation de la chaîne String Syntax, 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 la syntaxe alternative Array Syntax.
Vérifie qu'un Number est inférieur ou égal à une valeur maximale. La valeur maximale est par défaut 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 est par défaut 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 que les données d'entrée 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 fassent passer la règle required, vous pouvez passer trim en argument de la règle :
Vérifie plusieurs entrées et réussit si l'une d'entre elles a une valeur.
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 comprend la plupart des caractères accentués, tels que ä, ù ou ś.
Vérifie si la valeur d'entrée semble être une URL correctement formatée, y compris le protocole. Cela ne vérifie pas si l'URL se résout réellement.
Les règles de validation sont des fonctions qui acceptent un nœud central et renvoient une valeur booléenne — true pour réussir et false pour échouer. De plus, tous les arguments passés à la règle de validation sont disponibles en tant qu'arguments 1-n. En écrire une est simple — par exemple :
/**
* Fichier : my-custom-rules/monday.js
*
* Une règle de validation artificielle qui garantit que la valeur d'entrée est monday ou mon.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
export default mondayComme mentionné dans la section indices de règle 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 d'entrée est vide, sont synchrones et bloquantes. Si vous souhaitez que les valeurs 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 garantit que la valeur d'entrée est monday ou mon.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
// remplacer les comportements de règle par défaut pour votre règle personnalisée
monday.blocking = false
monday.skipEmpty = false
monday.debounce = 20 // millisecondes
monday.force = true
export default mondayVous pouvez également remplacer ces comportements au cas par cas avec indices de règle.
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.
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é, vous pouvez utiliser votre règle de validation n'importe où dans votre projet.
<FormKit validation="required|monday" />Pour ajouter une validation à une entrée spécifique, utilisez la prop validation-rules.
Vos règles personnalisées ont probablement besoin d'un message personnalisé — la prochaine section de la documentation couvrira cela.
Il existe plusieurs façons de personnaliser votre message de validation. La plus basique consiste à 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 entrée FormKit en fournissant un objet de chaînes ou de fonctions.
Pour remplacer un message de validation sur une seule entrée 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. 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 (d'abord disponible à partir de : validation-label, label, puis name). |
| node | Le noyau FormKit node. |
Réécrivons l'exemple ci-dessus en utilisant une fonction au lieu d'une chaîne pour encore plus de contrôle de 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: {
en: {
validation: {
required({ name }) {
return `Veuillez remplir le champ ${name}.`
}
}
}
}
})).mount('#app')Si vous souhaitez afficher les messages de validation d'une entrée en dehors du composant <FormKit />, vous pouvez utiliser le composant <FormKitMessages /> en passant le nœud d'entrée en tant que prop. L'utilisation de ce composant désactive l'affichage par défaut des messages (situés sous l'entrée) et les déplace vers l'emplacement où se trouve le composant <FormKitMessages /> :
Pour obtenir tous les messages de validation d'un nœud central d'entrée, vous pouvez utiliser la fonction getValidationMessages exportée depuis @formkit/validation. Cette fonction vérifiera récursivement le nœud donné et tous les enfants pour les messages de validation et renverra une Map de nœuds centraux aux messages de validation, ce qui la rend idéale pour une utilisation avec des formulaires :