O FormKit torna a validação de front-end simples, permitindo que você declare suas regras de validação diretamente nos seus inputs. É fácil escrever regras personalizadas também, mas você raramente precisará disso com mais de 20 regras prontas para produção.
Declarar quais regras de validação se aplicam a um determinado input é tão simples quanto fornecer uma propriedade validation. As regras podem ser declaradas usando duas sintaxes:
Regras de validação podem ser declaradas especificando cada nome de regra desejado separado por pipes |. Algumas regras também podem aceitar argumentos, que podem ser fornecidos após dois pontos :. Você pode usar vários argumentos separando-os por vírgulas:
Regras de validação também podem ser declaradas fornecendo um array. Cada elemento do array deve ser ele próprio um array onde o primeiro elemento é o nome da regra de validação em string, e os elementos restantes n são argumentos para essa regra.
Isso é especialmente útil se os argumentos fornecidos precisarem ser tipos de JavaScript reais — por exemplo, uma expressão regular (regex):
Regras de validação são sempre calculadas em tempo real — o que significa que um determinado campo sempre será válido ou inválido (é considerado inválido enquanto regras de validação assíncronas pendentes são executadas). No entanto — a visibilidade dos erros de validação é determinada pela propriedade validation-visibility.
| Visibilidade | Descrição |
|---|---|
| blur | (Padrão) Erros são mostrados após um usuário remover o foco de um input. |
| live | Erros são sempre visíveis. |
| dirty | Erros são mostrados após um usuário modificar o valor de um input. |
| submit | Erros são mostrados apenas após um usuário tentar enviar um formulário. |
Se um input está dentro de um formulário, então qualquer mensagem de validação restante será exibida ao usuário final quando ele tentar enviar o formulário.
Devido à herança de configuração do FormKit, você pode definir validation-visibility em um nível de form, group ou list usando a propriedade config, que ainda pode ser substituída individualmente em cada entrada:
As regras de validação operam de acordo com algumas características padrão, que você pode alterar caso a caso com "dicas de regras":
required|length:5, então a regra length não será executada até que a regra required esteja sendo cumprida.required é a única exceção).As características acima podem ser modificadas ao declarar suas regras usando "dicas". Dicas de regras são pequenos caracteres modificadores que você anexa ao início de uma declaração de regra para alterar seu comportamento padrão:
| Dica | Nome | Descrição |
|---|---|---|
(200) | Debounce | Aplica debounce na regra de validação pelo número dado de milissegundos. |
+ | Empty | Executa a regra de validação mesmo se a entrada estiver vazia (mas não força a regra). |
* | Force | Executa a regra de validação mesmo se uma regra anterior falhou. |
? | Optional | Torna uma regra de validação opcional (ela é não bloqueadora, significando que o formulário ainda pode ser enviado). |
(milli)Às vezes faz sentido aplicar debounce nas suas regras de validação. Para fazer isso, use a dica de debounce — um parêntese contendo uma duração em milissegundos — antes da sua regra:
+ VazioÀs vezes você quer que uma regra de validação seja executada mesmo quando uma entrada está vazia. Você pode usar a dica de vazio + para isso:
*A dica de forçar garante que uma regra de validação será executada mesmo se uma regra definida antes dela falhar (nota: isso não significa que ela será executada quando uma entrada estiver vazia). Observe como este exemplo exibirá ambas as mensagens de length e email:
?A dica opcional permite que uma regra de validação falha não impeça o envio do formulário. Neste exemplo, observe como o formulário não será enviado se as regras required ou confirm falharem, mas será enviado se a regra de length com dica opcional falhar:
Você pode usar dicas de regras juntas. Para fazer isso, basta colocar várias dicas antes da declaração da regra: required|*+(200)min:10.
O FormKit vem com mais de 20 regras de validação prontas para produção, cobrindo a maioria das necessidades de validação. Se você não encontrar uma que atenda ao seu requisito exato, você pode adicionar uma regra personalizada para atender às suas necessidades.
O valor deve ser yes, on, 1 ou true. Útil para entradas de caixa de seleção — frequentemente onde você precisa validar se alguém aceitou os termos.
Verifica se um valor contém apenas caracteres alfabéticos. Existem dois conjuntos de caracteres: latim e padrão. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto padrão inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Verifica se um valor é composto apenas por caracteres alfabéticos ou dígitos numéricos. Para a parte alfabética, você pode passar default ou latin - veja alpha acima.
Verifica se um valor é composto apenas por caracteres alfabéticos ou espaços. Para a parte alfabética, você pode passar default ou latin - veja alpha acima.
Verifica se um número está (inclusivamente) entre dois outros números. O valor de entrada deve ser um número, ou a regra de validação falhará.
Verifica se o valor de uma entrada corresponde ao valor de outra entrada — frequentemente usado para confirmações de senha. Existem duas maneiras de especificar qual entrada corresponder:
_confirm ao atributo name da segunda entrada.name da primeira entrada como um argumento para a regra de confirmação na segunda entrada confirm:name_of_input_1 (mais específico).Nota: as duas entradas devem estar no mesmo group ou form.
Verifica se um valor contém caracteres alfabéticos. Existem dois conjuntos de caracteres: latim e padrão. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto padrão inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Verifica se um valor contém caracteres alfabéticos ou dígitos numéricos. Para a parte alfabética, você pode passar default ou latin - veja contains alpha acima.
Verifica se um valor contém caracteres alfabéticos ou espaços. Para a parte alfabética, você pode passar default ou latin - veja contém alfa acima.
Verifica se um valor contém um caractere minúsculo. Existem dois conjuntos de caracteres: latino e default. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto default inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Verifica se um valor contém um número.
Verifica se um valor contém um símbolo.
Verifica se um valor contém um caractere maiúsculo. Existem dois conjuntos de caracteres: latino e default. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto default inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Determina se uma data é posterior à data atual ou a uma data fornecida como argumento da regra. As datas utilizadas podem ser objetos Date do JavaScript ou strings que podem ser analisadas por Date.parse().
Determina se uma data é anterior à data atual ou a uma data fornecida como argumento da regra. As datas utilizadas podem ser objetos Date do JavaScript ou strings que podem ser analisadas por Date.parse().
Determina se uma data está entre (e incluindo) as duas datas fornecidas como argumentos da regra. As datas utilizadas podem ser objetos Date do JavaScript ou strings que podem ser analisadas por Date.parse().
Garante que o formato da data de uma entrada corresponda a um formato de data específico. O formato deve ser especificado usando os seguintes tokens de formatação:
| Token | Valores válidos |
|---|---|
| MM | Representação de mês com dois dígitos (01-12) |
| M | Representação de mês com um dígito (1-12), zero à esquerda permitido |
| DD | Dia do mês com dois dígitos (01-31) |
| D | Dia do mês com um dígito (1-31), zero à esquerda permitido |
| YY | Ano com dois dígitos |
| YYYY | Ano com quatro dígitos |
Entradas de data nativas sempre geram o mesmo formato YYYY-MM-DD ... mesmo que exibam datas de acordo com a localidade do navegador. Usar esta regra para especificar um formato diferente resultaria em uma entrada que nunca poderia ser válida.
Verifica se a entrada contém um endereço de email válido.
Verifica se o valor da entrada termina com uma determinada substring.
Verifica se o valor da entrada corresponde a pelo menos um dos argumentos fornecidos.
Verifica se o valor da entrada tem um comprimento superior a um valor dado, ou entre dois valores de comprimento. Funciona para validar arrays (como listas), objetos (como grupos) ou comprimentos de strings. Pode ser usado para simular os atributos nativos maxlength e minlength.
Verifica se um valor consiste apenas de caracteres minúsculos. Existem dois conjuntos de caracteres: latim e padrão. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto padrão inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Verifica se a entrada corresponde a um valor ou padrão específico. Se você passar vários argumentos, ele verifica cada um até encontrar uma correspondência.
Em vez de passar strings dentro da propriedade de validação para correspondência simples, você pode modelar seu argumento com barras / para passar sua própria expressão regular.
Ao usar a Sintaxe de String você não pode escapar caracteres usados para definir as próprias regras de validação (|,:). Para usar esses caracteres em suas expressões regulares, você deve usar a alternativa Sintaxe de Array.
Verifica se um Number é menor ou igual a um valor máximo. O valor máximo padrão é 10.
Você também pode usar essa regra para validar se o comprimento de um Array é menor ou igual a um valor máximo.
Verifica se um Number é maior ou igual a um valor mínimo. O valor mínimo padrão é 1.
Você também pode usar essa regra para validar se o comprimento de um Array é maior ou igual a um valor mínimo.
Verifica para garantir que os dados de entrada não correspondam a um conjunto de valores predefinidos.
Verifica se a entrada é um número válido conforme avaliado por isNaN().
Verifica se a entrada está vazia.
Se você não quiser que espaços em branco façam a regra required passar, você pode passar trim como um argumento para a regra:
Verifica múltiplas entradas e passa se alguma delas tiver um valor.
Nota: as duas entradas devem estar no mesmo group ou form.
Verifica se a entrada começa com uma das opções fornecidas.
Verifica se um valor consiste apenas de símbolos.
Verifica se um valor consiste apenas de caracteres maiúsculos. Existem dois conjuntos de caracteres: latim e padrão. Caracteres latinos são estritamente [a-zA-Z], enquanto o conjunto padrão inclui a maioria dos caracteres acentuados, como ä, ù ou ś.
Verifica se o valor de entrada parece ser uma URL formatada corretamente, incluindo o protocolo. Isso não verifica se a URL realmente resolve.
Regras de validação são funções que aceitam um nó central e retornam um valor booleano — true para aprovado e false para reprovado. Além disso, quaisquer argumentos passados para a regra de validação estão disponíveis como argumentos 1-n. Escrever a sua própria é simples — por exemplo:
/**
* Arquivo: my-custom-rules/monday.js
*
* Uma regra de validação forçada que garante que o valor de entrada seja monday ou mon.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
export default monday
Como mencionado na seção dicas de regras de validação, regras de validação — incluindo suas regras personalizadas — operam de acordo com comportamentos padrão: elas são executadas em sequência, são ignoradas quando o valor de entrada está vazio, são síncronas e são bloqueantes. Se você quiser que os padrões da sua regra operem de maneira diferente, você pode sobrescrever esses comportamentos na sua regra de validação personalizada:
/**
* Uma regra de validação forçada que garante que o valor de entrada seja monday ou mon.
*/
const monday = function (node) {
return node.value === 'monday' || node.value === 'mon'
}
// sobrescreve os comportamentos padrão da regra para a sua regra personalizada
monday.blocking = false
monday.skipEmpty = false
monday.debounce = 20 // milissegundos
monday.force = true
export default monday
Você também pode sobrescrever esses comportamentos caso a caso com dicas de regras.
Uma vez que você tenha escrito uma função de validação — você precisa registrar a regra de validação com o FormKit — globalmente ou especificamente em uma entrada.
Regras de validação podem depender de valores de outras entradas na árvore do seu formulário. Para fazer isso, use a travessia de nó para localizar outro nó e acessar seu valor:
Regras de validação devem sempre ser funções puras. Use apenas os argumentos passados e não realize quaisquer efeitos colaterais.
Para usar uma regra de validação em qualquer lugar do seu projeto, você pode especificá-la onde quer que seu plugin FormKit esteja registrado com o Vue.
import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'
// prettier-ignore
createApp(App).use(plugin, defaultConfig({
rules: { monday },
})).mount('#app')
Uma vez instalada, você pode usar sua regra de validação em qualquer lugar do seu projeto.
<FormKit validation="required|monday" />
Para personalizar a mensagem de erro que aparece quando sua validação personalizada falha, siga as instruções aqui.
Para adicionar uma validação a um input específico, use a prop validation-rules.
Suas regras personalizadas provavelmente precisarão de uma mensagem personalizada — a próxima seção da documentação vai abordar isso.
Existem várias maneiras de personalizar sua mensagem de validação. A mais básica é usar a prop validation-label — permitindo que você altere o nome do campo conforme usado nas mensagens de validação predefinidas.
Se você precisar ser mais específico, tem duas opções:
Você pode facilmente substituir mensagens de validação diretamente no seu input FormKit fornecendo um objeto de strings ou funções.
Para substituir uma mensagem de validação em um único input FormKit, adicione a prop validation-messages com um objeto de nomes de regras e a mensagem correspondente.
Se você precisar de mais poder para suas regras de validação, pode usar uma função em vez de uma string. A função recebe um objeto de contexto.
| Comportamento | Descrição |
|---|---|
| args | Um array de argumentos passados para a regra. Por exemplo 'Vue', 'React', 'Angular' da regra is:Vue,React,Angular. |
| name | O nome do campo (primeiro disponível de: validation-label, label, depois name). |
| node | O núcleo node do FormKit. |
Vamos reescrever o exemplo acima usando uma função em vez de uma string para ainda mais controle da prop validation-messages:
Se houver mensagens de regras de validação que você gostaria de substituir (ou adicionar) em todo o seu projeto, você pode definir essas regras de mensagens ao registrar o FormKit sob a chave de idioma que deseja substituir:
import { createApp } from 'vue'
import App from './App.vue'
import { plugin, defaultConfig } from '@formkit/vue'
import monday from './my-custom-rules/monday'
// prettier-ignore
createApp(App).use(plugin, defaultConfig({
messages: {
en: {
validation: {
required({ name }) {
return `Por favor, preencha o campo ${name}.`
}
}
}
}
})).mount('#app')
Se você deseja renderizar as mensagens de validação de um input fora do componente <FormKit />, você pode utilizar o componente <FormKitMessages /> passando o nó do input como prop. Usar este componente desabilita a exibição padrão das mensagens (localizadas abaixo do input) e as move para onde o componente <FormKitMessages /> está localizado:
O FormKit 1.0.0 introduziu o componente FormKitSummary que oferece uma solução "pronta para uso" para exibir todas as mensagens de validação em um determinado formulário ou subárvore.
Para obter todas as mensagens de validação do núcleo do input, você pode usar a função getValidationMessages exportada de @formkit/validation. Esta função verificará recursivamente o nó fornecido e todos os filhos em busca de mensagens de validação e retornará um Map de nós centrais para mensagens de validação, tornando-a ideal para uso com formulários: