Configuração
- Introdução
- O que são nós centrais?
- O que são opções de nó?
- O que são props de nó?
- O que é configuração de nó?
Introdução
O FormKit usa um sistema de configuração hierárquico único que é bem adequado para formulários. Para entender como essa configuração funciona, existem 4 perguntas que precisamos responder:
O que são nós centrais?
Cada componente <FormKit> tem sua própria instância de um nó central. Este nó é responsável por quase toda a funcionalidade do componente. Existem 3 tipos de nós centrais: entradas, listas e grupos (formulários são apenas um tipo de grupo!).
Não existe uma instância global do FormKit que controla a aplicação. Em vez disso, você pode pensar em cada nó como sua própria pequena aplicação - completa com sua própria configuração.
Uma última coisa sobre nós - todos eles podem ter nós pais. Grupos e listas também podem ter filhos. Por exemplo, um formulário de login pode ter dois filhos - as entradas de email e senha. Você pode desenhar essa relação como um simples diagrama de árvore:
O que são opções de nó?
Ao criar uma dessas "mini aplicações" que chamamos de nós centrais, algumas opções podem ser passadas. Exceto em casos de uso extremamente avançados, você não estará criando seus próprios nós centrais - isso normalmente é feito para você pelo componente <FormKit>. No entanto, pode ser útil definir algumas das opções de nó globalmente. Isso é feito com o plugin @formkit/vue - 💡 as opções de nó central são as mesmas que as opções do plugin @formkit/vue.
Por exemplo, em um registro típico do FormKit Vue, usamos defaultConfig que é apenas uma função que retorna opções de nó central:
import { createApp } from 'vue'
import App from 'App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
// 👀 defaultConfig é apenas uma função que retorna opções de nó central!
createApp(App).use(plugin, defaultConfig)
Opções de nó disponíveis
A seguir, uma lista de todas as opções disponíveis que podem ser usadas ao registrar o FormKit ou criar um nó individualmente. As opções que são passadas para o plugin @formkit/vue serão aplicadas a cada nó central do componente <FormKit> quando ele for criado.
createNode({
/**
* Usado para renomear o componente global "FormKit".
*/
alias: 'FormKit',
/**
* Este array é normalmente construído para você pelo componente FormKit.
*/
children: [],
/**
* Um objeto de configurações. Continue lendo para mais informações sobre isso.
*/
config: {},
/**
* O nome do nó - normalmente isso é mapeado para o nome da sua entrada.
*/
name: 'inputName',
/**
* Parent - isso é normalmente definido para você pelo componente FormKit.
*/
parent: null,
/**
* Uma matriz de funções de plugin
*/
plugins: [],
/**
* Valores padrão de prop, continue lendo para aprender mais.
*/
props: {},
/**
* Usado para renomear o componente global "FormKitSchema".
*/
schemaAlias: 'FormKitSchema',
/**
* Todos são apenas 1 de 3 valores: 'input', 'group', ou 'list'
*/
type: 'input',
/**
* O valor inicial do nó.
*/
value: 'foobar',
})
O que é defaultConfig?
Desenvolvedores familiarizados com o FormKit notarão que a lista acima de opções de nó difere um pouco dos valores que podem ser passados para a função defaultConfig.
Muitos dos recursos do FormKit, como validação, entradas e suporte Vue, são fornecidos por plugins de primeira parte. A função defaultConfig configura muitos desses plugins antes de serem entregues ao plugin Vue como opções de nó. Portanto, defaultConfig pode aceitar qualquer uma das opções de nó acima, mas também alguns extras:
defaultConfig({
/**
* Regras de validação para adicionar ou substituir.
* Veja a documentação de validação.
*/
rules: {},
/**
* Locais para registrar.
* Veja a documentação de internacionalização.
*/
locales: {},
/**
* Definições de entrada para adicionar ou substituir.
* Veja a documentação sobre entradas personalizadas.
*/
inputs: {},
/**
* Mensagens de local explícitas para substituir.
* Veja a documentação de internacionalização.
*/
messages: {},
/**
* O local atualmente ativo. Esta é realmente uma configuração, mas
* defaultConfig aceita como um valor de nível superior para melhorar o DX.
*/
locale: 'en',
/**
* Qualquer uma das opções de nó acima são aceitas.
*/
...nodeOptions,
})
O que são props de nó?
Todos os nós principais têm um objeto props (node.props). O núcleo do FormKit e qualquer plugin de terceiros ou código podem ler e escrever valores neste objeto. Na verdade, quase todos os recursos do FormKit referenciam node.props para determinar como devem operar.
Por exemplo, o plugin de validação olha para node.props.validation para determinar se há alguma regra que precisa ser executada. Então a verdadeira questão é — como essas props estão sendo definidas? Existem 3 mecanismos principais para definir props:
- Atribuição direta
- Props de componente
- Opções globais
- Opções do provedor
Vamos ver como podemos definir as regras de validação de uma entrada (node.props.validation) dessas três maneiras:
1. Atribuição direta
Se você tem uma instância de nó, pode atribuir diretamente a ela um valor de prop:
2. Props de componente
Qualquer prop passada para a entrada <FormKit> é atribuída ao objeto node.props (você sabe como funciona).
3. Opções globais
Ao registrar o plugin @formkit/vue (ou usando @formkit/nuxt com um formkit.config.ts) você pode fornecer valores de prop para serem injetados em todos os componentes <FormKit>.
4. Opções do provedor
Semelhante às opções globais, o componente <FormKitProvider> permite que você especifique quais opções de configuração "globais" devem ser injetadas em seus filhos. Esta técnica pode ser usada para criar uma configuração "escopada" para uma seção específica de um aplicativo, substituir opções globais para uma seção específica de um aplicativo, ou fornecer um carregamento mais direcionado da biblioteca FormKit.
Ao usar o componente <FormKitProvider>, todas as opções definidas globalmente (do plugin global) são removidas e apenas as opções fornecidas pelo provedor são usadas em qualquer componente <FormKit> dentro de seu escopo.
O módulo @formkit/nuxt com autoImport: true habilitado automaticamente envolve seus componentes que usam FormKit em um componente <FormKitProvider>. Isso impede que o formkit seja incluído em seu pacote de entrada.
O que é configuração de nó?
Props são bastante poderosas, mas além de node.props, todos os nós principais têm um objeto de configuração node.config. É aqui que entra a hierarquia de configuração. O objeto node.config age como valores iniciais para node.props. Se uma propriedade específica for solicitada, como node.props.validation, e essa propriedade não for explicitamente definida usando qualquer um dos métodos discutidos acima, então o FormKit verificará o objeto node.config para ver se ele tem um valor. Se não tiver um valor, então ele verifica recursivamente o objeto de configuração do nó pai - depois o objeto de configuração do avô - e assim por diante - até que um valor seja encontrado ou ele atinja um nó sem pai.
O que isso significa na prática? Quando você combina a estrutura em árvore dos formulários (e seus respectivos nós principais) e esta configuração hierárquica, você pode fazer algumas coisas bastante interessantes. Por exemplo, aqui definimos a visibilidade da validação de um formulário inteiro:
Vale a pena notar que os plugins têm seu próprio modelo de herança que difere de config e props, e é descrito em mais detalhes na documentação principal.