Configuration

• Introduction
• Qu'est-ce que les nœuds principaux ?
• Qu'est-ce que les options de nœud ?
  • Options de nœud disponibles
  • Qu'est-ce que defaultConfig ?
• Qu'est-ce que les props de nœud ?
  • 1. Affectation directe
  • 2. Props de composant
  • 3. Options globales
  • 4. Options du fournisseur
• Qu'est-ce que la configuration de nœud ?

Introduction

FormKit utilise un système de configuration hiérarchique unique qui est bien adapté aux formulaires. Pour comprendre comment fonctionne cette configuration, nous devons répondre à 4 questions :

1. Qu'est-ce que les nœuds principaux ?
2. Qu'est-ce que les options de nœud ?
3. Qu'est-ce que les propriétés de nœud ?
4. Qu'est-ce que la configuration de nœud ?

Qu'est-ce que les nœuds principaux ?

Chaque composant <FormKit> a sa propre instance d'un nœud principal. Ce nœud est responsable de presque toutes les fonctionnalités du composant. Il existe 3 types de nœuds principaux : les entrées, les listes et les groupes (les formulaires ne sont qu'un type de groupe !).

Il n'y a pas d'instance FormKit globale qui contrôle l'application. Au lieu de cela, vous pouvez considérer chaque nœud comme sa propre petite application - avec sa propre configuration.

Une dernière chose à propos des nœuds - ils peuvent tous avoir des nœuds parents. Les groupes et les listes peuvent également avoir des enfants. Par exemple, un formulaire de connexion pourrait avoir deux enfants - les entrées de courrier électronique et de mot de passe. Vous pouvez représenter cette relation par un simple diagramme d'arbre :

Qu'est-ce que les options de nœud ?

Lors de la création de l'une de ces "mini applications" que nous appelons nœuds principaux, certaines options peuvent être passées. Sauf dans des cas d'utilisation extrêmement avancés, vous ne créerez pas vos propres nœuds principaux - cela est normalement fait pour vous par le composant <FormKit>. Cependant, il peut être utile de définir certaines des options de nœud globalement. Cela se fait avec le plugin @formkit/vue - 💡 les options de nœud principal sont les mêmes que les options du plugin @formkit/vue.

Par exemple, dans une inscription typique de FormKit Vue, nous utilisons defaultConfig qui est juste une fonction qui renvoie les options de nœud principal :

import { createApp } from 'vue'
import App from 'App.vue'
import { plugin, defaultConfig } from '@formkit/vue'

// 👀 defaultConfig est juste une fonction qui renvoie les options de nœud principal !
createApp(App).use(plugin, defaultConfig)

Options de nœud disponibles

Voici une liste de toutes les options disponibles qui peuvent être utilisées lors de l'enregistrement de FormKit ou de la création d'un nœud individuellement. Les options qui sont passées au plugin @formkit/vue seront appliquées à chaque nœud principal du composant <FormKit> lorsqu'il est créé.

createNode({
  /**
   * Utilisé pour renommer le composant global "FormKit".
   */
  alias: 'FormKit',
  /**
   * Ce tableau est normalement construit pour vous par le composant FormKit.
   */
  children: [],
  /**
   * Un objet de paramètres de configuration. Continuez à lire pour en savoir plus à ce sujet.
   */
  config: {},
  /**
   * Le nom du nœud - normalement, cela correspond au nom de votre entrée.
   */
  name: 'inputName',
  /**
   * Parent - cela est normalement défini pour vous par le composant FormKit.
   */
  parent: null,
  /**
   * Un tableau de fonctions de plugin
   */
  plugins: [],
  /**
   * Valeurs par défaut des propriétés, continuez à lire pour en savoir plus.
   */
  props: {},
  /**
   * Utilisé pour renommer le composant global "FormKitSchema".
   */
  schemaAlias: 'FormKitSchema',
  /**
   * Tous ne sont que l'une des 3 valeurs : 'input', 'group', ou 'list'
   */
  type: 'input',
  /**
   * La valeur initiale du nœud.
   */
  value: 'foobar',
})

Qu'est-ce que defaultConfig ?

Les développeurs familiers avec FormKit remarqueront que la liste ci-dessus des options de nœud diffère légèrement des valeurs qui peuvent être passées à la fonction defaultConfig.

De nombreuses fonctionnalités de FormKit, comme la validation, les entrées, et le support de Vue sont fournies grâce à des plugins de première partie. La fonction defaultConfig configure beaucoup de ces plugins avant qu'ils ne soient remis au plugin Vue en tant qu'options de nœud. Ainsi, defaultConfig peut accepter n'importe laquelle des options de nœud ci-dessus, mais aussi quelques extras :

defaultConfig({
  /**
   * Règles de validation à ajouter ou à remplacer.
   * Voir la documentation sur la validation.
   */
  rules: {},
  /**
   * Locales à enregistrer.
   * Voir la documentation sur l'internationalisation.
   */
  locales: {},
  /**
   * Définitions d'entrée à ajouter ou à remplacer.
   * Voir la documentation sur les entrées personnalisées.
   */
  inputs: {},
  /**
   * Messages de locale explicites à remplacer.
   * Voir la documentation sur l'internationalisation.
   */
  messages: {},
  /**
   * La locale actuellement active. Il s'agit en fait d'un paramètre de configuration, mais
   * defaultConfig l'accepte comme une valeur de premier niveau pour améliorer le DX.
   */
  locale: 'en',
  /**
   * Toutes les options de nœud ci-dessus sont acceptées.
   */
  ...nodeOptions,
})

Qu'est-ce que les props de nœud ?

Tous les nœuds centraux ont un objet props (node.props). Le cœur de FormKit, et tout plugin tiers ou code peuvent lire et écrire des valeurs dans cet objet. En fait, presque chaque fonctionnalité de FormKit fait référence à node.props pour déterminer comment elle doit fonctionner.

Par exemple, le plugin de validation regarde node.props.validation pour déterminer s'il y a des règles qu'il doit exécuter. La vraie question est donc — comment ces props sont-elles définies ? Il existe 3 mécanismes principaux pour définir les props :

• Affectation directe
• Props de composant
• Options globales
• Options du fournisseur

Voyons comment nous pouvons définir les règles de validation d'une entrée (node.props.validation) de ces trois façons :

1. Affectation directe

Si vous avez une instance de nœud, vous pouvez lui attribuer directement une valeur de prop :

2. Props de composant

Toutes les props passées à l'entrée <FormKit> sont attribuées à l'objet node.props (vous connaissez la procédure).

3. Options globales

Lors de l'enregistrement du plugin @formkit/vue (ou en utilisant @formkit/nuxt avec un formkit.config.ts) vous pouvez fournir des valeurs de prop à injecter dans tous les composants <FormKit>.

4. Options du fournisseur

Semblable aux options globales, le composant <FormKitProvider> vous permet de spécifier quelles options de configuration "globales" doivent être injectées dans ses enfants. Cette technique peut être utilisée pour créer une configuration "limitée" pour une section spécifique d'une application, remplacer les options globales pour une section spécifique d'une application, ou fournir un chargement plus ciblé de la bibliothèque FormKit.

Lors de l'utilisation du composant <FormKitProvider>, toutes les options définies globalement (à partir du plugin global) sont supprimées et seules les options fournies par le fournisseur sont utilisées sur tous les composants <FormKit> dans son champ d'application.

Qu'est-ce que la configuration de nœud ?

Les props sont assez puissantes, mais en plus de node.props, tous les nœuds centraux ont un objet de configuration node.config. C'est là qu'intervient la hiérarchie de configuration. L'objet node.config agit comme des valeurs initiales pour node.props. Si une prop donnée est demandée, comme node.props.validation, et que cette propriété n'est pas explicitement définie en utilisant l'une des méthodes discutées ci-dessus, alors FormKit vérifiera l'objet node.config pour voir s'il a une valeur. S'il n'a pas de valeur, alors il vérifie récursivement l'objet de configuration du parent du nœud - puis l'objet de configuration du grand-parent - et ainsi de suite - jusqu'à ce qu'une valeur soit trouvée ou qu'il atteigne un nœud sans parent.

Qu'est-ce que cela signifie en pratique ? Lorsque vous combinez la structure en arbre des formulaires (et leurs nœuds centraux correspondants) et cette configuration hiérarchique, vous pouvez faire des choses assez excitantes. Par exemple, ici nous définissons la visibilité de la validation d'un formulaire entier :

Il convient de noter que les plugins ont leur propre modèle d'héritage qui diffère de config et props, et qui est décrit plus en détail dans la documentation de base.