Le schéma de FormKit est un format de données sérialisable en JSON pour stocker des structures DOM et des implémentations de composants, y compris les formulaires FormKit. Bien qu'il ait été créé spécifiquement pour la mise en œuvre et la génération de formulaires, le format est capable de générer n'importe quel balisage HTML ou d'utiliser n'importe quel composant tiers.
Les schémas sont rendus en utilisant le composant <FormKitSchema> de FormKit, qui n'est pas enregistré globalement par défaut. Vous devrez l'importer :
import { FormKitSchema } from '@formkit/vue'
FormKit est livré avec un support de première classe pour générer des formulaires à l'aide de schéma. Cela rend possible le stockage de formulaires générés dans des bases de données, des fichiers, ou même des codes QR ! Pour générer un formulaire, passez votre tableau de schéma au composant <FormKitSchema> en utilisant la propriété :schema.
<FormKitSchema :schema="yourSchemaArray" />
Jetons un coup d'œil à un exemple rapide :
Nous voyons de nombreuses fonctionnalités ci-dessus, y compris les propriétés $el et $cmp, le raccourci de la propriété $formkit, la validation, le rendu conditionnel, les étiquettes, le texte d'aide et plusieurs types d'entrées. Nous allons déballer toutes ces fonctionnalités dans le reste de cette page.
Un schéma est un tableau d'objets ou de chaînes (appelés "nœuds de schéma"), où chaque élément du tableau définit un seul nœud de schéma. Il existe 3 types de nœuds de schéma :
$el.$cmp.$formkit. Sucre syntaxique pour le format $cmp complet.Les schémas prennent en charge des fonctionnalités avancées telles que la logique conditionnelle, les opérateurs booléens, les boucles, les slots et le ciblage de données — tous garantis pour être sérialisés en chaîne.
Les éléments HTML sont définis en utilisant la propriété $el. Vous pouvez utiliser $el pour rendre n'importe quel élément HTML. Les attributs peuvent être ajoutés avec la propriété attrs, et le contenu est assigné avec la propriété children :
Remarquez dans l'exemple ci-dessus que l'attribut style est unique en ce qu'il doit être défini comme un objet de paires de style à valeur plutôt que comme une chaîne.
Les composants peuvent être définis avec la propriété $cmp. La propriété $cmp doit être une chaîne de caractères qui fait référence à un composant défini globalement ou à un composant passé
dans FormKitSchema avec la propriété library :
Pour passer des composants concrets via la propriété library, il est préférable d'encapsuler votre bibliothèque avec la signature markRaw de Vue.
En plus du tableau de schéma (et de la bibliothèque optionnelle), l'objet FormKitSchema peut également inclure une propriété data. Les valeurs de l'objet data peuvent alors être référencées directement dans votre schéma — et votre schéma maintiendra la réactivité de l'objet de données original.
Pour référencer une valeur de l'objet data, il suffit d'utiliser un signe dollar $ suivi du nom de la propriété de l'objet data. Les références peuvent être utilisées dans attrs, props, les conditionnels et comme children :
Remarquez dans l'exemple ci-dessus que nous avons utilisé un tableau pour concaténer "Hello" et "$location". Nous avons fait cela parce que les références de données et les expressions logiques dans le schéma doivent toujours commencer par un signe dollar $ — sinon elles sont traitées comme des littéraux de chaîne non analysés.
Les schémas prennent en charge l'appel de fonctions qui se trouvent dans vos données de référence originales — et vous pouvez même passer des références de données en tant qu'arguments de cette fonction !
Tout comme en JavaScript — vous pouvez accéder aux propriétés d'un objet profondément imbriqué en utilisant la syntaxe par points objet.propriété :
Les références de schéma peuvent avoir n'importe quelle structure ou propriétés, mais à la racine de l'objet de référence de données, il y a 2 mots réservés : $slots et $get.
Les schémas prennent également en charge la logique sous forme de logique booléenne, de comparaison et d'expressions arithmétiques. Ces expressions peuvent être utilisées partout où une référence de données peut être utilisée (attrs, props, les conditionnels et children) :
Les expressions doivent toujours commencer par un $. Si le premier élément d'une expression est une référence de données (ex : $count + 2), alors elle commence déjà par un $ et aucun étiquetage supplémentaire n'est nécessaire. Cependant, souvent le premier caractère d'une expression n'est pas un signe dollar — ces expressions doivent être "étiquetées" avec $: — par exemple $: ($count * 3) - 7.
Bien que cela ressemble beaucoup à JavaScript — les expressions de schéma ne sont pas du JavaScript. Il est préférable de les considérer comme un langage de templating. Les expressions sont compilées en JavaScript fonctionnel lors du setup mais la syntaxe n'est pas compatible 1-1 avec JavaScript. Cela améliore les performances et offre une couche de sécurité critique car seules les données et les fonctionnalités explicitement exposées peuvent être exécutées.
Les expressions de schéma sont limitées aux opérateurs suivants et aux parenthèses :
| Opérateur | Cas d'utilisation |
|---|---|
+ | Addition |
- | Soustraction |
* | Multiplication |
/ | Division |
% | Modulo |
&& | ET logique |
|| | OU logique |
=== | Égalité stricte |
!== | Inégalité stricte |
== | Égalité lâche |
!= | Inégalité lâche |
>= | Supérieur ou égal |
<= | Inférieur ou égal |
> | Supérieur |
< | Inférieur |
Le schéma FormKit peut tirer parti des références et des expressions pour rendre conditionnels les nœuds de schéma et les attributs. Ces conditionnels peuvent être ajoutés de deux manières :
if sur les nœuds $el et $cmp.if/then/elseifLes nœuds de schéma $el et $cmp peuvent utiliser une propriété if qui équivaut à peu près à un v-if dans Vue. Si l'expression assignée à la propriété if est vraie, le nœud est rendu, sinon il ne l'est pas :
Les nœuds de schéma conditionnels ou itératifs (lors de l'utilisation de if ou de for) devraient toujours inclure une propriété key explicite. Sans cette propriété, Vue pourrait réutiliser les nœuds DOM du rendu précédent, ce qui peut conduire à un comportement inattendu, des erreurs et des problèmes de performance.
if/then/elseL'objet if/then/else permet une logique conditionnelle plus complexe. Il peut être utilisé pour rendre conditionnellement des nœuds, une liste de nœuds de schéma, des valeurs de l'objet attrs ou des valeurs de l'objet props. Il est également possible d'imbriquer des objets if/then/else pour créer des structures plus complexes — similaires à une instruction else if en JavaScript.
if/then/else sur les nœuds de schémaVous pouvez utiliser l'objet if/then/else partout où vous utiliseriez normalement un nœud de schéma. Cela inclut le tableau de schéma racine, ou la propriété children d'un autre nœud de schéma :
Les nœuds de schéma conditionnels ou itératifs (lors de l'utilisation de if ou de for) devraient toujours inclure une propriété key explicite. Sans cette propriété, Vue pourrait réutiliser les nœuds DOM du rendu précédent, ce qui peut conduire à un comportement inattendu, des erreurs et des problèmes de performance.
if/then/else sur attrs et propsVous pouvez également utiliser des instructions if/then/else pour sortir conditionnellement les valeurs de attrs ou props :
Les nœuds de schéma $el et $cmp prennent en charge les boucles. La syntaxe de boucle est similaire à v-for dans Vue et attend un objet ou un tableau à parcourir et une propriété pour assigner la valeur de l'itération courante. Facultativement, vous pouvez également capturer l'index ou la propriété de l'itération courante :
Les nœuds de schéma conditionnels ou itératifs (lors de l'utilisation de if ou de for) devraient toujours inclure une propriété key explicite. Sans cette propriété, Vue pourrait réutiliser les nœuds DOM du rendu précédent, ce qui peut conduire à un comportement inattendu, des erreurs et des problèmes de performance.
Les schémas peuvent rendre le contenu d'un emplacement du composant <FormKitSchema> n'importe où dans le schéma où un nœud de schéma normal peut être rendu. Tous les emplacements à portée sont automatiquement fournis au schéma sous l'objet de référence $slots :
À l'intérieur d'un nœud de schéma $formkit, il est également possible de transmettre du contenu aux emplacements FormKit préexistants comme label ou prefix à l'intérieur de la propriété __raw__sectionsSchema du nœud. Lisez plus sur les valeurs brutes ci-dessous, et sectionsSchema dans la documentation des entrées.
Il peut parfois être nécessaire de passer un objet d'attributs ou de props variables ou inconnus à un $cmp ou $el. Dans Vue, nous ferions cela en utilisant v-bind — dans le monde des schémas, nous utilisons la propriété bind :
Il peut parfois être nécessaire d'empêcher qu'un attribut ou une prop donnée soit analysée. Cela peut être fait en préfixant un attribut ou une prop avec __raw__ :
{
$cmp: 'PriceComponent',
props: {
__raw__price: '$2.99'
}
}
Dans l'exemple ci-dessus, le préfixe __raw__ sera retiré, et la valeur non analysée de $2.99 sera passée en tant que prop price au PriceComponent.
Un autre scénario où cela est utile est le rendu des composants FormKit. Le composant <FormKit> a une prop sections-schema qui permet aux utilisateurs de transmettre des fragments de schéma pour fusionner avec différentes sections de leur entrée. Dans ce cas limite, nous voulons passer les morceaux de schéma au composant <FormKit> en tant qu'objet JavaScript brut. Pour ce faire, nous préfixons à nouveau la prop sectionsSchema avec __raw__ :
Remarquez que si vous retirez le préfixe __raw__ de l'exemple ci-dessus, le préfixe n'a plus d'effet — c'est parce que la valeur de la prop sectionsSchema a été analysée lors de la création du composant au lieu d'être passée en tant qu'objet JavaScript.
Bien que les schémas puissent être utilisés à presque toutes fins — l'objectif principal est de donner aux développeurs le pouvoir de construire des formulaires complexes et dynamiques en utilisant un format de données sérialisable. L'utilisation du schéma avec les entrées FormKit couvre bien ce cas d'utilisation.
En supposant que vous avez enregistré globalement le composant FormKit — vous pouvez rendre vos entrées FormKit à partir du schéma en utilisant le nœud de schéma de type $cmp :
Bien que la syntaxe cmp soit généralisée et fonctionne pour n'importe quel composant Vue, elle est quelque peu verbeuse pour les entrées FormKit. Pour simplifier cela, FormKit prend en charge un quatrième type de nœud $formkit, qui est un sucre syntaxique pour le format complet $cmp.
Lorsque vous utilisez l'abréviation $formkit, l'objet props est aplati avec les propriétés de niveau supérieur (frères et sœurs de $formkit). Par exemple :
Le format de schéma a une fonction intégrée spécifique aux entrées FormKit : la fonction $get. Cette fonction intégrée permet au schéma d'accéder à l'objet contexte de toute autre entrée FormKit (même en dehors du formulaire immédiat) — à condition que l'entrée en question ait une propriété id explicitement déclarée. Cela permet au schéma de répondre conditionnellement à l'état de vos propres entrées :
Pour rendre un élément de formulaire, vous pouvez soit utiliser le nœud de schéma $formkit: 'form', soit envelopper votre composant <FormKitSchema> dans un composant <FormKit type="form"> :