Plugin Zod

• Instalação
• Uso
  • Para validação de formulário
  • Além da validação FormKit
  • Para definir erros no formulário

Com o pacote @formkit/zod, você pode facilmente habilitar a validação dos seus formulários FormKit com o seu esquema Zod. Isso oferece uma maneira conveniente de ter tipos isomórficos e garantir que seu front-end e back-end estejam usando as mesmas regras de validação.

Ao validar com um esquema Zod, todos os erros de validação serão mapeados para suas entradas correspondentes, exibidos ou ocultados com base na propriedade validation-visibility do seu formulário/entrada, e impedirão o envio quando os dados do formulário não passarem na validação com Zod.

Instalação

Para usar este plugin com o FormKit, instale @formkit/zod:

yarn add @formkit/zod

Depois de instalar o pacote @formkit/zod, você precisará registrar o plugin em uma base por formulário e cada formulário que requer validação com um esquema Zod criará uma nova instância do plugin usando a função createZodPlugin.

Uso

Para usar o plugin Zod, precisamos importar a função createZodPlugin de @formkit/zod, chamar a função createZodPlugin para criar nosso zodPlugin e submitHandler, e então adicioná-los ao nosso formulário FormKit.

A função createZodPlugin recebe dois argumentos:

• zodSchema: O esquema Zod que você gostaria de usar para validar o formulário.
• submitCallback: uma função que você gostaria de executar uma vez que a validação tenha sido bem-sucedida no seu formulário — é aqui que você lidaria com o envio dos seus dados para o seu back-end ou outras tarefas relacionadas ao envio. Seus dados de formulário serão fornecidos com suporte completo do TypeScript com base no seu esquema Zod.

A função createZodPlugin retornará uma tupla de:

• zodPlugin: O plugin que deve ser aplicado à propriedade plugins do formulário alvo.
• submitHandler: O manipulador de envio que deve ser anexado à ação @submit do seu formulário. Quando os dados do formulário passarem na validação do seu esquema Zod fornecido, seu submitCallback será acionado.

Para validação de formulário

Aqui está um exemplo de uso de um esquema Zod para validar um formulário FormKit. É importante que os names das entradas FormKit correspondam aos valores esperados para o seu esquema Zod.

Agora o seu formulário FormKit usará o seu Esquema Zod para validação — e todas as mensagens estarão adjacentes a cada entrada FormKit como se fossem validações nativas do FormKit!

Além da validação FormKit

Usar o Zod para validar o seu formulário não significa que você tenha que abrir mão das mensagens de validação integradas do FormKit. Se você adicionar validação FormKit às suas entradas FormKit, então os erros de validação do Zod só serão exibidos se todas as validações do FormKit forem satisfeitas e restarem validações insatisfeitas do Zod.

Isso tem algumas vantagens:

• Você pode usar as regras integradas do FormKit, como confirm, que não têm equivalentes fáceis de usar dentro do Zod.
• Suas mensagens podem ser traduzidas para um dos muitos idiomas existentes em @formkit/i18n sem nenhum esforço adicional da sua parte.
• As mensagens de validação integradas do FormKit são escritas para serem contextualmente conscientes dos nomes das suas entradas e sabendo que serão anexadas diretamente às suas entradas correspondentes — então elas são mais precisas e fáceis de entender do que seus equivalentes genéricos do Zod.

Aqui está o mesmo formulário de antes, mas agora usando mensagens de validação FormKit além da validação do esquema Zod.

Para definir erros no formulário

Se você precisar definir erros no seu formulário, pode fazer isso com a função node.setZodErrors que é disponibilizada pelo zodPlugin. A função node.setZodErrors aceita um objeto ZodError e mapeará os erros para cada entrada. Quaisquer erros que não correspondam serão mostrados como erros no nível do formulário.