Le schéma FormKit est un format de données sérialisable en JSON pour stocker les structures DOM et les 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émas. Cela permet de stocker les 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émas au composant <FormKitSchema> en utilisant la prop :schema.
<FormKitSchema :schema="yourSchemaArray" />Examinons rapidement un exemple :
Nous voyons de nombreuses fonctionnalités ci-dessus, y compris les props $el et $cmp, le raccourci de prop $formkit, la validation, le rendu conditionnel, les étiquettes, le texte d'aide et plusieurs types d'entrées. Nous détaillerons 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 emplacements et la portée des données — le tout garanti pour être sérialisé en une 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 attribué avec la propriété children :
Remarquez dans l'exemple ci-dessus que l'attribut style est unique en ce sens qu'il doit être défini comme un objet de paires 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 prop library :
Pour passer des composants concrets via la prop library, il est préférable d'envelopper votre bibliothèque avec la signature markRaw de Vue.
En plus du tableau de schéma (et de la bibliothèque facultative), l'objet FormKitSchema peut également inclure une prop data. Les valeurs de l'objet de données peuvent ensuite être référencées directement dans votre schéma — et votre schéma conservera la réactivité de l'objet de données d'origine.
Pour référencer une valeur de l'objet de données, il suffit d'utiliser un signe dollar $ suivi du nom de la propriété de l'objet de données. Les références peuvent être utilisées dans attrs, props, les conditionnels et en tant que 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 d'origine — et vous pouvez même passer des références de données en tant qu'arguments de cette fonction !
Tout comme JavaScript — vous pouvez accéder aux propriétés d'un objet profondément imbriqué en utilisant la syntaxe point object.property :
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 la forme d'expressions logiques booléennes, de comparaison et arithmétiques. Ces expressions peuvent être utilisées partout où une référence de données peut être utilisée (attrs, props, 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 il 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 vaut mieux les considérer comme un langage de templating. Les expressions sont compilées en JavaScript fonctionnel lors de la 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 booléen |
|| | OU booléen |
=== | Égalité stricte |
!== | Inégalité stricte |
== | Égalité faible |
!= | Inégalité faible |
>= | 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 les nœuds et les attributs de schéma conditionnels. 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 approximativement à un v-if dans Vue. Si l'expression attribuée à la propriété if est vraie, le nœud est rendu, sinon il ne l'est pas :
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 :
if/then/else sur attrs et propsVous pouvez également utiliser des instructions if/then/else pour afficher 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é à laquelle attribuer la valeur de l'itération en cours. Facultativement, vous pouvez également capturer l'index ou la propriété de l'itération en cours :
Parfois, les expressions de schéma doivent convertir une chaîne en nombre. Par exemple, les clés sont toujours des valeurs de chaîne pendant une itération, donc dans l'exemple ci-dessus, il était nécessaire de convertir $key en entier avant de l'ajouter à 1. Pour effectuer cette conversion, nous avons simplement multiplié par 1 : $key * 1 avant d'effectuer notre addition.
Les schémas peuvent rendre le contenu des slots du composant <FormKitSchema> n'importe où dans le schéma où un nœud de schéma normal peut être rendu. Tous les slots avec portée sont automatiquement fournis au schéma sous l'objet de référence $slots :
Parfois, il peut ê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 :
Parfois, il peut être nécessaire d'empêcher un attribut ou une prop donnée d'être 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 supprimé, 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 entre en jeu est le rendu des composants FormKit. Le composant <FormKit> a une prop sections-schema qui permet aux utilisateurs de transmettre des parties de schéma à fusionner avec différentes sections de leur entrée. Dans ce cas limite, nous voulons passer les morceaux de schéma au composant <FormKit> sous la forme d'un objet JavaScript brut. Pour ce faire, nous préfixons à nouveau la prop sectionsSchema avec __raw__ :
Remarquez que si vous supprimez le préfixe __raw__ de l'exemple ci-dessus, le préfixe n'a plus d'effet — cela est dû au fait 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 pour presque n'importe quel objectif — l'objectif principal est de permettre aux développeurs de créer des formulaires complexes et dynamiques à l'aide d'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 type $cmp du schéma :
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 faciliter cela, FormKit prend en charge un quatrième type de nœud $formkit, qui est un sucre syntaxique pour le format $cmp complet.
Lors de l'utilisation du raccourci $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 déclarée explicitement. Cela permet au schéma de répondre de manière conditionnelle à l'état de vos propres entrées :
Pour afficher 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"> :