Vamos começar criando nosso primeiro formulário FormKit! Vamos aprender algumas das principais características do FormKit e como elas beneficiam você. Também vamos pegar algumas dicas legais ao longo do caminho - como gerenciar o estado do formulário sem usar v-model.
Este guia pressupõe que você esteja familiarizado com a API de Composição do Vue.
Uma das principais características do FormKit é sua API de componente único - o componente <FormKit />. Este único componente dá acesso a todos os tipos de input. E enquanto alguns tipos podem estender e adicionar recursos, eles compartilham a mesma funcionalidade básica. Você pode aprender mais sobre inputs aqui.
Mesmo sem qualquer prop, o componente <FormKit /> já deu ao nosso input um ótimo ponto de partida, com uma marcação acessível, um tipo de input text básico, e recursos adicionais que serão explicados em seções posteriores.
Por padrão, o componente <FormKit /> usará type="text" se nenhum type for especificado. O type é como especificamos que input queremos. Assim como inputs nativos, temos inputs como text, select, checkbox e assim por diante. No entanto, não estamos limitados apenas a inputs "nativos", o FormKit Pro adiciona controles não nativos como os tipos repeater, taglist e autocomplete, que podem lidar com interações mais complexas.
Se você olhar para o HTML gerado pelo exemplo anterior, verá que o FormKit já criou uma marcação acessível. No entanto, como não especificamos as propriedades name e id, elas foram geradas automaticamente para nós: name: "text_1" id="input_0". Mesmo assim, como uma boa prática, devemos sempre especificar pelo menos o name, pois facilita o uso de inputs dentro de um formulário. O name é usado pelos tipos form e group para coletar valores de, e passar valores para, seus filhos com base no name:
Nosso input ainda está faltando algumas funcionalidades de acessibilidade chave como um label, help, e talvez até mesmo um placeholder. FormKit aceita todos estes como props, e produz os atributos aria corretos. Leitores de tela agora anunciarão o nome do input, o texto de ajuda, e que o input está pronto para edição:
Às vezes você quer adicionar um valor inicial a um input, como fornecer um ponto de partida sensato, ou preencher dados pré-salvos de um banco de dados. Fazemos isso com a prop value.
Vamos começar a construir um exemplo que podemos adicionar a este guia. Imaginando que estamos construindo um "formulário de criação de personagem" para um jogo. Vamos atribuir ao nosso personagem uma classificação de força. Poderíamos usar o input range com um valor predefinido de 5 quando o usuário abre o formulário pela primeira vez:
A validação é uma das principais características do FormKit. Ela ajuda o usuário a saber se o valor que estão submetendo está correto. Adicionar validação é uma brisa, com muitas regras de validação poderosas já implementadas para você. Vamos usar a prop validation para garantir que o personagem não seja muito forte ou muito fraco. A prop validation-visibility nos permite controlar quando mostrar mensagens de validação ao usuário — seja imediatamente, quando o usuário desfoca o input, ou na submissão do formulário. O estado de validade real é calculado em tempo real e sempre atualizado — simplesmente escolhemos quando expor as mensagens:
Note que as props min e max acima são props de navegador integradas para um input de range, e representam o topo e o fundo do controle deslizante de range.
Suponha que nosso "backend" requer que dados como strength sejam convertidos para um número. Por padrão, FormKit segue o comportamento de inputs "nativos" HTML, tornando todos os valores como "strings". Para corrigir isso, podemos usar uma das características mais legais do FormKit — plugins — que podem ser pensados como middleware para inputs. Com um plugin, que são apenas funções, podemos mudar como o valor do nosso input é retornado:
Primeiro, vamos criar um formulário básico e adicionar mais campos para termos conteúdo para trabalhar. Adicionaremos mais recursos a ele em cada seção, como validação, agrupamento e alteração de valores com base em outros campos.
Usaremos um dos campos chamado form, que facilitará o agrupamento e a validação dos campos. Você só precisa envolver todos os seus campos dentro de um <FormKit type="form">:
O tipo form coletará ativamente todos os valores dos campos filhos usando o name de cada campo como um objeto de dados para você (assim como group).
O primeiro recurso de um formulário que exploraremos é que temos um evento @submit pronto para facilitar nossa vida quando chegar a hora de enviar nosso formulário. O evento @submit nos dá como primeiro argumento todos os campos descendentes que o formulário coletou dos campos. Não há necessidade de usar vários v-models para coletar os dados do formulário. Vamos adicionar nosso manipulador de envio createCharacter():
Como uma conveniência ao usar type="form", o form exibe um botão de envio automaticamente. Para o nosso caso, um texto "Enviar" não mostra a intenção do formulário corretamente. Para corrigir isso, podemos usar a prop submit-label, que é um recurso específico do form, simplesmente adicionando submit-label="Create Character" para mostrar a intenção do formulário:
<FormKit type="form" @submit="createCharacter" submit-label="Criar Personagem">
<!-- Resto do nosso formulário de criação -->
</FormKit>
Embora o formulário funcione agora, podemos ver que alguns campos relacionados estão separados (ou seja, os dados do formulário têm uma estrutura plana onde todos os dados do formulário são irmãos). Suponha que nosso backend precisa de todos os atributos dentro de uma propriedade attributes. Podemos usar o tipo group para agrupar campos relacionados juntos por um name comum.
Assim como o tipo form, você pode envolver todos os seus campos dentro de um <FormKit type="group" name: "attributes">. Não se esqueça de adicionar a propriedade name:
E é isso! Poderíamos parar aqui para uma introdução de como formulários e campos funcionam com o FormKit. No entanto, vamos adicionar algumas melhorias de UX e usar isso para nos expor a conceitos e recursos adicionais que você pode usar para levar seus formulários para o próximo nível.
Uma coisa que podemos fazer para melhorar este formulário é alterar os atributos padrão do personagem com base na classe de personagem selecionada. Para isso, usaremos alguns novos recursos:
getNode obtém o núcleo de uma entrada usando seu id como identificador. Cada entrada tem um núcleo associado.events escutam as alterações de uma determinada entrada.input em um nó nos permite atualizar o valor dele.Com esses recursos combinados, podemos obter o núcleo de uma entrada, ouvir e responder a events, e atualizar um valor de outro campo usando a função input:
O código agora ficou um pouco menos legível, então vamos extrair a lógica para outro arquivo para criar um plugin. Note que estamos colocando o novo updateAttributesPlugin apenas na entrada class, então ele não afetará nenhuma outra entrada. Também aprenderemos outro recurso útil chamado traversal usando a função at de um nó:
A função at usa o atributo name em vez do id que getNode usa.
Vamos supor que, enquanto diferentes personagens são melhores em diferentes atributos, nenhum deve ser muito poderoso. Podemos fazer isso criando um orçamento de pontos e adicionando validação de grupo ao group de atributos para garantir que eles não excedam 20 pontos no total. Vamos aprender um novo recurso - regras personalizadas - para realizar isso:
Por padrão, o tipo group não produz nenhuma marcação, então para mostrar erros de validação precisamos adicioná-la manualmente.
Às vezes, os formulários precisam mostrar ou ocultar campos dependendo do valor de outra entrada. Podemos fazer isso aprendendo 2 novos conceitos:
FormKit recebem seu objeto de contexto na #default prop de slot.group - O valor de uma entrada group (e form) é um objeto com os valores de seus filhos, identificados pelos names dos filhos.Ao usar a renderização condicional, note que o Vue precisa de dicas para saber que um elemento DOM precisa de uma nova renderização, em vez de tentar reutilizá-lo. Podemos adicionar uma propriedade key única ao elemento para ajudar o Vue.
Então, vamos pegar o objeto de contexto da entrada group e extrair o value: #default="{ value }". Queremos adicionar um pequeno easter egg para nossos usuários se eles decidirem mudar todos os atributos para 1:
E isso conclui nossa introdução ao FormKit! Agora você está pronto para começar a usá-lo!
Existem alguns tópicos que recomendamos que você explore a seguir, que você pode ler em qualquer ordem ou mesmo mais tarde depois de experimentar o FormKit por si mesmo: