As Entradas do FormKit são semelhantes às entradas HTML, mas turbinadas com recursos muito necessários, como rótulos, texto de ajuda, validação e mensagens de erro (e muito mais). Semelhante a como a tag <input> do HTML usa vários atributos type (ou seja, <input type="text"> vs <input type="checkbox">), o FormKit usa a prop type para todas as entradas. Na verdade, com o FormKit, existe apenas 1 componente que você precisa aprender:
As Entradas do FormKit não estão limitadas ao que está disponível no HTML "nativo". Nosso pacote separado FormKit Pro fornece acesso a tipos de entrada "sintéticos", como repeater, autocomplete, mask, rating e mais. Claro, você também pode escrever suas próprias entradas criando entradas personalizadas.
Embora você esteja livre para usar as entradas do FormKit por si só, geralmente você vai querer agrupá-las em um formulário:
<FormKit type="form">
<!-- ... suas entradas de formulário -->
</FormKit>
O tipo de formulário fornece uma série de recursos, incluindo coleta de valores, definição de valor inicial, envio de formulário, tratamento de erros, estados de carregamento e mais.
Existem 4 maneiras de definir o valor de uma entrada:
value (Nota: define apenas o valor inicial).v-model.node.input() do FormKit.FormKit pai.valueVocê pode definir o valor inicial de uma única entrada ou de um grupo de entradas usando a prop value.
A prop value deve ser usada apenas para definir o valor inicial de uma entrada. Ela não reagirá a mudanças após o componente ter sido criado.
v-modelUsar v-model permite a vinculação de dados reativos bidirecionais com qualquer entrada do FormKit.
node.input()No coração de cada entrada do FormKit está uma instância do objeto node do FormKit, e usar o método node.input() é o mecanismo mais eficiente para modificar o valor de qualquer entrada (leia mais sobre obter uma instância do objeto node).
As chamadas para node.input() são amortecidas e, portanto, assíncronas (use a prop delay para alterar o comprimento da amortização). Você pode await node.input(val) para determinar quando a entrada foi estabilizada.
Entradas parentais como list, group e form também são capazes de definir diretamente os valores de qualquer um de seus filhos. Na verdade, o valor de um pai é apenas o valor agregado de seus filhos. Você pode usar qualquer um dos métodos acima (value prop, v-model, ou node.input()) para definir o valor dos filhos.
Em quase todos os casos, os atributos definidos no componente <FormKit> serão passados para o elemento <input> real no coração do componente, em vez de quaisquer elementos DOM de embrulho. Por exemplo:
Discutimos a validação em mais detalhes em sua própria página de documentação — mas basta dizer que adicionar regras de validação às entradas no FormKit é tão fácil quanto adicionar a prop validation:
Para desempenho, todas as entradas do FormKit suportam debouncing como um recurso de primeira classe. Enquanto o valor de uma entrada muda a cada tecla pressionada (tecnicamente o evento input), este valor atualizado recentemente é apenas definido internamente — regras de validação, grupos, listas, formulários e (a maioria) plugins ainda não estão “cientes” de que uma mudança foi feita.
Internamente, o FormKit debounces o evento input. Quando o debounce "se acalma", o novo valor é “comprometido” e o resto do aplicativo é então notificado através do evento commit do nó de entrada. O atraso padrão do debounce é de 20 milissegundos e pode ser ajustado com a prop delay ou opção de configuração.
Para ilustrar isso, vamos pegar o value do group a partir da prop do slot #default e observar como ele não é atualizado até depois do nosso delay de 1000ms:
O padrão da prop delay é 20 milissegundos. No entanto, as entradas group e list usam 0 milissegundos por padrão para evitar que o atraso do debounce se “acumule” em cada nível de profundidade.
Os erros de validação não são a única maneira de definir erros em uma entrada. Você também pode definir explicitamente mensagens de erro em uma entrada usando a prop errors.
Os erros definidos explicitamente são não bloqueantes, o que significa que eles não impedem o formulário de ser enviado da maneira que os erros de validação fazem. Você pode ler mais sobre o tratamento de erros na documentação do formulário.
Os inputs do FormKit aceitam tanto props universais (aqueles que se aplicam a todos os inputs do FormKit), quanto props específicos do input. A tabela a seguir é uma lista completa de props disponíveis para todos os inputs do FormKit.
| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| config | Object | {} | Opções de configuração a serem fornecidas para o nó do input e qualquer nó descendente deste input. |
| delay | Number | 20 | Número de milissegundos para debounce do valor do input antes de despachar o commit hook. |
| dirtyBehavior | string | touched | Determina como o indicador "dirty" deste input é definido. Pode ser configurado como touched ou compare - touched (o padrão) é mais performático, mas não detectará quando o formulário corresponder novamente ao seu estado inicial. |
| errors | Array | [] | Array de strings para exibir como mensagens de erro neste campo. |
| help | String | '' | Texto para o texto de ajuda associado ao input. |
| id | String | input_{n} | O ID único do input. Fornecer um ID também permite acesso global ao nó do input. |
| ignore | Boolean | false | Impede que um input seja incluído em qualquer pai (grupo, lista, formulário etc). Útil ao usar inputs para a interface do usuário em vez de valores reais. |
| index | Number | undefined | Permite que um input seja inserido no índice fornecido, se o pai for uma lista. Se o valor do input for indefinido, ele herda o valor dessa posição de índice. Se ele tiver um valor, ele o insere nos valores da lista no índice fornecido. |
| label | String | '' | Texto para o elemento label associado ao input. |
| name | String | input_{n} | O nome do input como identificado no objeto de dados. Isso deve ser único dentro de um grupo de campos. |
| parent | FormKitNode | contextual | Por padrão, o pai é um grupo, lista ou formulário de envolvimento, mas essa prop permite a atribuição explícita do nó pai. |
| prefix-icon | String | '' | Especifica um ícone para colocar na seção prefixIcon. |
| preserve | boolean | false | Preserva o valor do input em um grupo pai, lista ou formulário quando o input é desmontado. |
| preserve-errors | boolean | false | Por padrão, os erros definidos em inputs usando setErrors são automaticamente limpos no input. Definir essa prop como true mantém o erro até que ele seja explicitamente limpo. |
| sections-schema | Object | {} | Um objeto de chaves de seção e valores parciais de esquema, em que cada esquema parcial é aplicado à seção respectiva. |
| suffix-icon | String | '' | Especifica um ícone para colocar na seção suffixIcon. |
| type | String | text | O tipo de input a ser renderizado pela biblioteca. |
| validation | String, Array | [] | As regras de validação a serem aplicadas ao input. |
| validation-visibility | String | blur | Determina quando mostrar as regras de validação com falha de um input. Os valores válidos são blur, dirty e live. |
| validation-label | String | {label prop} | Determina qual rótulo usar nas mensagens de erro de validação, por padrão, usa a propriedade label, se disponível, caso contrário, usa a propriedade name. |
| validation-rules | Object | {} | Regras de validação personalizadas adicionais para disponibilizar na propriedade de validação. |
| value | Any | undefined | Inicializa o valor do input e/ou de seus filhos. Não é reativo. Pode inicializar grupos inteiros (formulários) e listas.. |
Os inputs do FormKit emitem tanto eventos universais (aqueles que são emitidos de todos os inputs), quanto eventos específicos do input. A tabela a seguir é uma lista completa de eventos emitidos por todos os inputs do FormKit.
| Event | Payload | Descrição |
|---|---|---|
| input | any | Emitted when the core node’s commit hook is completed. Has it’s own debounce to reduce noise. Includes the core node as the second argument. |
| input-raw | any | Emitted on every core node’s commit hook. Includes the core node as the second argument. |
| node | FormKitNode | Emitted when the component’s setup is complete. This is the internal FormKitNode object at the heart of the input. |
Os acima são eventos Vue emitidos por @formkit/vue. @formkit/core também emite seus próprios eventos como parte do ciclo de vida de nós centrais.
Os inputs são compostos por pedaços de HTML chamados "seções". Cada seção tem uma "chave" que pode ser usada para direcionar a seção para uma variedade de propósitos, como:
{section-key}-class="your-class"<template #{section-key}>Muitas chaves de seção estão universalmente disponíveis, enquanto outras são específicas para um determinado tipo de input (você pode definir as suas próprias para inputs personalizados também). A tabela a seguir é uma lista completa daquelas que estão geralmente disponíveis em todos os inputs:
| Section-key | Descrição |
|---|---|
| outer | O elemento de envolvimento mais externo. |
| wrapper | Um invólucro ao redor do rótulo e do input. |
| label | O rótulo do input. |
| prefix | Por padrão, não gera saída, mas permite conteúdo diretamente antes de um elemento input. |
| prefixIcon | Um elemento para gerar um ícone antes da seção de prefixo. |
| inner | Um invólucro ao redor do próprio elemento input. |
| suffix | Por padrão, não gera saída, mas permite conteúdo diretamente após um elemento input. |
| suffixIcon | Um elemento para gerar um ícone após a seção de sufixo. |
| input | O próprio elemento input. |
| help | O elemento que contém o texto de ajuda. |
| messages | Um invólucro ao redor de todas as mensagens. |
| message | O elemento (ou muitos elementos) que contém uma mensagem - na maioria das vezes mensagens de validação e erros. |
Às vezes, você pode achar necessário reestruturar o HTML dentro de um input do FormKit, como adicionar, editar, mover ou remover seções. Isso pode ser feito exportando o input (usando a ferramenta CLI), fazendo as alterações desejadas e, em seguida, usando o input modificado em seu projeto. Leia o guia sobre exportação de inputs para aprender como.
Os inputs podem ter sua estrutura substituída com slots. Você pode direcionar precisamente onde o conteúdo do seu slot vai com chaves de seção. Os slots são então passados para o objeto de contexto para uso em seu template.
Por exemplo, se quiséssemos usar um slot para definir o rótulo de um input, poderíamos usar um slot label para isso:
Uma desvantagem de usar slots é que você geralmente precisa recriar recursos não relacionados para fazer a alteração desejada. Por exemplo, usar slots exigiria que você reimplementasse quaisquer classes aplicadas a essas seções (o que pode ser feito usando context.classes.sectionName).
Para ajudar a resolver essa limitação, o FormKit também é capaz de substituir/se estender seletivamente o esquema subjacente de cada seção, permitindo modificação estrutural complexa muitas vezes sem perda de funcionalidade.
FormKit fornece um mecanismo adicional para alterar a estrutura de uma entrada FormKit chamada "esquema de seções". Por trás dos panos, todas as entradas FormKit são alimentadas pelo esquema FormKit — um formato de dados compatível com JSON para criar e armazenar estrutura e lógica DOM. Isso permite uma enorme flexibilidade estrutural porque todas as entradas podem ter partes de seu esquema estendidas via chaves de seção sem a substituição total do template.
Por exemplo, por padrão, FormKit usa uma lista não ordenada (<ul> e <li>) para exibir mensagens de validação — mas talvez você precise usar tags <div>. Você pode alterar essas tags usando a prop schema sem ter que recriar qualquer funcionalidade:
Para acessibilidade e flexibilidade, FormKit usa vários elementos de wrapper como os das seções wrapper e inner #sections. No entanto, talvez em algumas entradas você precise remover um elemento de wrapper para garantir que outros elementos estejam adjacentes. Você pode fazer isso fornecendo um valor null como o elemento do esquema:
Os esquemas de seção também podem alterar o conteúdo sendo exibido usando lógica de esquema avançada. Você poderia, por exemplo, exibir um valor especial quando o valor de sua entrada corresponde a uma string específica: