Embora você possa usar os inputs do FormKit individualmente, geralmente você vai querer agrupá-los em um formulário. Para fazer isso, basta envolver seus inputs em um <FormKit type="form">.
O tipo form irá coletar ativamente todos os valores dos inputs filhos, usando o name de cada input como o nome da propriedade no objeto de dados resultante (assim como em grupos). Você também pode ler e escrever nos valores do formulário usando v-model assim como faria em qualquer input.
Um <FormKit type="form"> rastreia o estado de validação do formulário e impede que os usuários o enviem se algum input estiver inválido.
Como uma conveniência, o form gera automaticamente um botão de envio button, e os temas fornecidos também incluem um spinner de carregamento. Você pode alterar este botão com as props submit-label e submit-attrs, ou desativá-lo com :actions="false". Você pode passar qualquer prop do FormKit para submit-attrs. No exemplo abaixo, passamos classes, atributos data, texto de ajuda e até mesmo indicamos ao botão de envio incluído para não ser ignorado:
<FormKit
type="form"
submit-label="Atualizar"
:submit-attrs="{
inputClass: 'minha-classe-input',
wrapperClass: 'minha-classe-wrapper',
'data-theme': `dark`,
help: 'Texto de ajuda do meu botão',
ignore: false
}"
></FormKit>
Excluindo a funcionalidade do backend, aqui está um formulário totalmente funcional com inputs (form, text, email, password), texto de ajuda, etiquetas, validação com mensagens personalizadas e tratamento de erros e envio:
Você pode preencher um formulário inteiro fornecendo uma prop value para o <FormKit type="form">. A prop value deve ser um objeto de pares de nome de input para valor de input. Você também pode usar v-model para preencher um formulário se precisar de vinculação de dados bidirecional:
Certifique-se de usar v-model em um ref ou em uma propriedade de um objeto reactive. Não use v-model no próprio objeto reativo, pois isso leva a comportamentos inesperados.
Formulários geralmente são enviados através de ações do usuário, como clicar em um botão de envio ou pressionar a tecla enter em um campo de texto dentro do formulário. Ao enviar, o formulário (em sequência):
@submit-raw.submitted como verdadeiro em todas as entradas — exibindo quaisquer erros de validação restantes (independentemente da validation-visibility).@submit-invalid é disparado.@submit.@submit retornar uma Promise, define o estado do formulário como loading até que ela seja resolvida.Usar dados v-model no seu manipulador de envio pode levar a mutações indesejadas no formulário. O FormKit coleta automaticamente os dados do formulário para você, então use a cópia não vinculada dos dados do seu formulário que é passada para o seu manipulador de envio em vez disso.
O método mais comum de envio de formulário em um SPA moderno é uma requisição XHR (pense em axios ou fetch). O FormKit é bem adequado para essa tarefa:
@submit 1) os dados do formulário coletados como um único objeto pronto para requisição (sem necessidade de v-model), e 2) o núcleo do input form, como uma conveniência.loading se torna verdadeiro em context.state.loading e um spinner é exibido no tema genesis).Para enviar um formulário via requisição de página, simplesmente não inclua o manipulador @submit. Assim como no HTML nativo, você também pode fornecer um atributo action e, opcionalmente, um atributo method.
Embora enviar um formulário usando qualquer método padrão de HTML seja válido (como clicar em um botão submit ou pressionar enter em uma entrada de texto) — você também pode enviar um formulário programaticamente. Existem 2 maneiras de fazer isso:
this.$formkit.submit('form-id') (submitForm('form-id') para a API de composição).$formkit.submit()node.submit()Você também pode enviar um formulário programaticamente chamando node.submit() no núcleo do formulário (ou em qualquer entrada dentro do formulário). Para fazer isso, você precisa obter uma instância do núcleo do componente.
Para desativar todas as entradas em um determinado formulário, incluindo o botão de enviar, você pode usar a propriedade disabled.
Ao usar um manipulador @submit assíncrono, o FormKit desativará automaticamente o formulário (e definirá o estado para loading) enquanto o manipulador de envio estiver pendente.
Você pode reiniciar o seu formulário (ou qualquer entrada) para o seu estado inicial chamando $formkit.reset(formId).
Ao usar a API de composição, você pode acessar diretamente a função de reinicialização importando-a do núcleo: import { reset } from '@formkit/core'.
É importante notar que o "estado inicial" de um formulário não é necessariamente um formulário vazio. Se você tem um :value padrão ou v-model no formulário ou em entradas individuais no formulário, o FormKit automaticamente os mescla para produzir seu valor inicial e restaurará esse estado mesclado ao reiniciar.
Opcionalmente, você pode fornecer um segundo argumento para reset(formId, initialState) se preferir um estado de reinicialização alternativo.
Os formulários não serão enviados até que todas as entradas no formulário estejam passando pelas suas regras de validação.
Além de não disparar o evento de envio, uma mensagem é exibida acima do botão de enviar indicando que o formulário ainda está incompleto. Você pode personalizar esta mensagem usando a propriedade incomplete-message ou desativá-la definindo a propriedade como false.
Se você deseja alterar a mensagem de incompleto em todos os formulários do seu projeto, você pode modificar a mensagem de localização i18n para ui.incomplete.
Quando um usuário tenta enviar um formulário contendo entradas que falharam nas validações, o evento @submit-invalid é disparado.
Por exemplo, poderíamos usar esse evento para alertar nossos usuários sobre as regras de validação que falharam.
A validade de todas as entradas dentro de um formulário é rastreada automaticamente no objeto de contexto. Isso pode ser útil ao criar várias interfaces. Por exemplo, se você quisesse que um botão de envio fosse desabilitado até que todas as entradas sejam válidas, você poderia usar a propriedade state.valid para fazer isso.
No exemplo acima, extraímos o objeto de contexto do slot #default, mas existem outras maneiras também. O objeto de contexto está disponível no núcleo de cada entrada na propriedade node.context, e você pode obter o núcleo de uma entrada de várias maneiras.
Com o FormKit, adicionar validação de front-end ao seu formulário é fácil — mas e quanto aos erros produzidos pelo seu framework de backend ou aqueles que você deseja atribuir manualmente? Existem dois tipos de erros que você pode atribuir a um formulário:
Erros de formulário (aqueles que se aplicam a todo o formulário) podem ser definidos de três maneiras.
errors em um <FormKit type="form">.node.setErrors().$formkit.setErrors().errorsComo com qualquer entrada do FormKit, você pode atribuir erros diretamente usando a propriedade errors. Esses erros estão sempre visíveis (não sujeitos a validation-visibility).
node.setErrors()Definir os erros do seu formulário usando node.setErrors é conveniente, pois o manipulador de envio recebe o objeto node do formulário como seu segundo argumento. node.setErrors() aceita 2 argumentos — um array para erros de formulário e um objeto com chaves para erros de entrada:
$formkit.setErrors()Alternativamente, você pode definir erros diretamente em um formulário atribuindo um id a ele e depois chamando $formkit.setErrors('id', ['Erro do formulário aqui']). O método setErrors deve receber o id do formulário e pode lidar com 1 ou 2 argumentos adicionais — os erros do formulário e os erros de entrada:
Por padrão, os erros que foram definidos nas entradas usando setErrors() são automaticamente limpos quando um usuário altera o valor dessa entrada. Você pode alterar esse comportamento padrão definindo a propriedade preserve-errors.
Para limpar todos os erros do formulário (independentemente da propriedade preserve-errors) chame node.clearErrors().
Se você preferir preservar os erros por padrão, pode alterar o comportamento padrão modificando a opção de configuração preserveErrors. Isso pode ser feito globalmente ou para um único formulário:
Ao usar a API de composição do Vue 3, você pode acessar setErrors e clearErrors importando-os diretamente de @formkit/vue.import { setErrors, clearErrors } from '@formkit/vue'
Erros de entrada (aqueles a serem exibidos com entradas específicas em um formulário) podem ser aplicados de três maneiras:
errors em cada entrada individual.input-errors no formulário (também funciona com grupos e listas).$formkit.setErrors() (veja exemplo acima).errorsA maneira mais básica de exibir erros em um formulário é usando a propriedade errors que está disponível em cada entrada FormKit.
input-errorsVocê também pode definir convenientemente mensagens de erro para todas as entradas do seu formulário (ou grupo ou lista) usando a propriedade input-errors. A propriedade aceita um objeto de erros, onde as chaves são nomes de entrada (endereços de nós relativos são suportados) e o valor é um erro ou array de erros a serem aplicados a essa entrada.
Pode ser útil para acessibilidade fornecer um resumo das mensagens de validação e erros no topo do seu formulário. O FormKit oferece um componente <FormKitSummary /> para renderizar esse resumo para você.
Este componente irá renderizar automaticamente todas as mensagens de validação e erros de um formulário com links de salto para as entradas às quais se aplicam. Esses erros são mostrados apenas após o envio do formulário, mas estão envolvidos em uma região aria-live para garantir que os leitores de tela sejam notificados quando os erros se apresentarem. Além disso, a página irá rolar automaticamente para a caixa de resumo e focar no primeiro erro listado.
<FormKitSummary /> não é um componente registrado globalmente — você deve importá-lo:
import { FormKitSummary } from '@formkit/vue'
O componente de resumo deve geralmente estar aninhado no formulário que está resumindo. Se você deseja mover o resumo para um local diferente na página, você pode fazer isso fornecendo o nó central do formulário como a propriedade node.
Por padrão, as mensagens de validação e erros de um formulário são colocadas diretamente acima da seção de ações do formulário. No entanto, você pode optar por renderizá-las em qualquer lugar da sua página usando o componente <FormKitMessages />. <FormKitMessages /> não é um componente registrado globalmente — você deve importá-lo:
import { FormKitMessages } from '@formkit/vue'
Existem duas maneiras de usar <FormKitMessages />:
Coloque um componente <FormKitMessages /> em qualquer lugar dentro do seu formulário, e as mensagens do formulário serão automaticamente movidas para essa localização:
nodePara mover mensagens para qualquer lugar no DOM — até mesmo fora do formulário — você pode passar o nó central do formulário como uma propriedade para <FormKitMessages />. Neste exemplo, usamos as mensagens para criar um popup estilo toast:
O componente <FormKitMessages /> tem algumas opções adicionais de configuração:
| Propriedade | Padrão | Descrição |
|---|---|---|
node | herdado | O nó central para renderizar mensagens. Por padrão, isso é herdado do nó pai (se existir). |
sectionsSchema | {} | Substitui as seções internas messages e message (mesma estrutura padrão que a seção de mensagens de outras entradas). |
defaultPosition | false | Por padrão, FormKitMessages move as mensagens renderizadas para uma nova localização. Se você gostaria de renderizar as mensagens em ambas as localizações, defina esta propriedade como true. |
Quando uma entrada é desmontada de um formulário — por exemplo, ao usar v-if — sua chave e valor são removidos dos dados do formulário. No entanto, em algumas circunstâncias, pode ser preferível manter o par chave/valor mesmo após a entrada ter sido removida. Isso pode ser realizado usando a propriedade preserve:
O FormKit fornece alguns composables para ajudá-lo a acessar os dados e o contexto do formulário. Estes estão disponíveis para importação a partir do pacote @formkit/vue:
O useFormKitContext é um composable que retorna o objeto de contexto do formulário como um Ref do vue sempre que ele estiver disponível. Este deve ser usado em um componente que é filho de um componente <FormKit> (como o formulário). O primeiro argumento é um caminho de travessia opcional que permite navegar até qualquer nó dentro da sua árvore de formulário. O segundo argumento é um callback de efeito opcional que será invocado sempre que o contexto estiver disponível.
Semelhante ao useFormKitContext, este composable encontra qualquer objeto de contexto <FormKit> se esse componente tiver sido dado um id explícito. Opcionalmente, você pode fornecer um callback de efeito que será invocado sempre que o nó estiver disponível.
Busca qualquer nó FormKit que tenha um id explícito. Ele retorna um Ref que será preenchido com o nó central sempre que ele for montado. Opcionalmente, você pode fornecer um callback de efeito que será invocado sempre que o nó estiver disponível.
O próprio nó não é reativo e deve ser usado para ações imperativas como node.submit(). O objeto de contexto é reativo e deve ser usado para ler e reagir ao estado do formulário.
Formulários são tecnicamente considerados tipos de input — portanto, eles compartilham muitas das props universais que os inputs padrão usam.
| Prop | Type | Padrão | Descrição |
|---|---|---|---|
| disabled | Boolean | false | Disables the form submit button and all the inputs in the form. |
| incomplete-message | String/Boolean | {locale}.ui.incomplete | The message that is shown to near the submit button when a user attempts to submit a form, but not all inputs are valid. |
| submit-attrs | Object | {} | Attributes or props that should be passed to the built-in submit button. |
| submit-behavior | String | disabled | Async submit handlers automatically disable the form while pending, you can change this by setting this prop to 'live'. |
| submit-label | String | Submit | The label to use on the built-in submit button. |
| actions | Boolean | true | Whether or not to include the actions bar at the bottom of the form (ex. you want to remove the submit button and use your own, set this to false). |
| Mostrar Universal props | |||
| 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.. |
| Section-key | Descrição |
|---|---|
| form | Responsável por renderizar a tag form e ouvir eventos de envio. |
| actions | Responsável por um contêiner na parte inferior do formulário com ações do formulário como o botão de envio. |
| submit | Responsável por um botão de envio — por padrão um tipo de entrada FormKit submit. |
| Mostrar Universal section keys | |
| 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. |
Todos os inputs do FormKit são projetados levando em consideração as seguintes considerações de acessibilidade. Ajude-nos a melhorar continuamente a acessibilidade para todos, relatando problemas de acessibilidade aqui: