Validação

O DYONA Form tem três mecanismos de validação relacionados, mas distintos:

1. required, uma propriedade direta do field.
2. validations, um array de regras declarativas.
3. Validação integrada para tipos de field específicos: type: 'email' e type: 'password' com passwordRules.

Experimente ao vivo

Quer ver essas regras de validação funcionando?

Abrir Validação no Lab →

required

Configure required: true para tornar um field obrigatório:

{
  name: 'username',
  label: 'Nome de usuário',
  type: 'text',
  required: true
}

O equivalente declarativo é {type: 'required'} dentro de validations. Essa forma pode personalizar o erro com message:

{
  name: 'username',
  label: 'Nome de usuário',
  type: 'text',
  validations: [{type: 'required', message: 'Escolha um nome de usuário.'}]
}

Se um field obrigatório estiver vazio, o formulário não é enviado.

validations

validations é um DyonaFieldValidation[] opcional:

validations?: DyonaFieldValidation[]

Cada entrada tem estes parâmetros:

{
  type: '...',
  value: ...,
  message: '...'
}

• type seleciona a regra.
• value fornece o limite ou padrão quando a regra precisa dele.
• message é opcional e substitui a mensagem padrão do DYONA Form para essa regra.

É possível declarar várias regras juntas:

validations: [
  {type: 'minLength', value: 4},
  {type: 'maxLength', value: 24}
]

min

min é válido apenas para type: 'number'. Define o menor valor numérico permitido, e value deve ser um número finito.

{
  name: 'employeeCount',
  label: 'Funcionários',
  type: 'number',
  validations: [
    {type: 'min', value: 1}
  ]
}

Valores menores que o mínimo configurado produzem um erro de validação.

max

max é válido apenas para type: 'number'. Define o maior valor permitido, e value deve ser numérico.

{
  name: 'employeeCount',
  label: 'Funcionários',
  type: 'number',
  validations: [
    {type: 'max', value: 500}
  ]
}

Valores maiores que o máximo configurado produzem um erro de validação.

minLength

minLength define a quantidade mínima de caracteres. É válido apenas para fields text, textarea, email e password. Seu value deve ser um inteiro maior ou igual a 0.

{type: 'minLength', value: 4}

maxLength

maxLength define a quantidade máxima de caracteres. É válido apenas para fields text, textarea, email e password, e seu value deve ser um inteiro maior ou igual a 0.

{type: 'maxLength', value: 24}

regex

regex valida o valor usando uma expressão regular. É válido apenas para fields text, textarea, email e password. Seu value deve ser uma string não vazia que represente uma RegExp válida.

{
  name: 'username',
  label: 'Nome de usuário',
  type: 'text',
  validations: [
    {type: 'regex', value: '^[a-z0-9.]+$'}
  ]
}

message

message?: string é uma propriedade opcional de uma validação declarativa:

validations: [
  {
    type: 'minLength',
    value: 4,
    message: 'O nome de usuário deve ter pelo menos 4 caracteres.'
  }
]

message é opcional. Quando contém texto válido, substitui a mensagem padrão gerada pelo DYONA Form para essa regra. Se estiver vazia ou contiver apenas espaços, o DYONA Form usa a mensagem padrão. Seu conteúdo pertence à aplicação consumidora, que é responsável por localizá-lo.

Validação de email

email não é um DyonaFieldValidationType. A validação do formato de email ocorre automaticamente quando um field usa type: 'email':

{
  name: 'email',
  label: 'Email',
  type: 'email',
  required: true
}

O DYONA Form valida o formato do email quando o field contém um valor.

Validação de password

passwordRules não pertence ao array validations. Configure-o diretamente em um field type: 'password':

passwordRules: {
  minLength?: number,
  requireUppercase?: boolean,
  requireLowercase?: boolean,
  requireNumber?: boolean,
  requireSymbol?: boolean
}

• minLength define o tamanho mínimo do password e deve ser um inteiro positivo maior que 0.
• requireUppercase é booleano e, quando é true, exige pelo menos uma letra maiúscula.
• requireLowercase é booleano e, quando é true, exige pelo menos uma letra minúscula.
• requireNumber é booleano e, quando é true, exige pelo menos um número.
• requireSymbol é booleano e, quando é true, exige pelo menos um símbolo.

{
  name: 'password',
  label: 'Senha',
  type: 'password',
  required: true,
  passwordRules: {
    minLength: 8,
    requireUppercase: true,
    requireLowercase: true,
    requireNumber: true,
    requireSymbol: true
  },
  showPasswordRules: true
}

showPasswordRules é booleano. Quando é true, mostra visualmente ao usuário as regras de password configuradas.

Fields opcionais

Quando um field não é required e está vazio, o DYONA Form não executa suas validações de conteúdo. Por exemplo, um email opcional vazio é válido; se contiver um valor, seu formato de email será validado.

Comportamento de erros

Quando uma validação falha, o DYONA Form mostra o erro abaixo do field. A tab correspondente reflete seus erros e há um resumo global navegável. Ao tentar salvar, o DYONA Form navega até o primeiro field inválido e dá foco a ele.

Obrigatório condicional

requiredWhen torna um field obrigatório conforme o valor de outro field:

{
  name: 'taxId',
  label: 'Identificação fiscal',
  type: 'text',
  requiredWhen: {
    field: 'accountType',
    operator: 'equals',
    value: 'business'
  }
}

A documentação completa de condições é abordada em sua própria seção.

Exemplo completo

import {DyonaForm, type DyonaFormSchema} from '@typhonsoftware/dyona-form';

const schema: DyonaFormSchema = {
  title: 'Criar conta',
  hideSingleTab: true,
  tabs: [{
    id: 'account',
    title: 'Conta',
    rows: [
      {columns: [
        {
          name: 'username', label: 'Nome de usuário', type: 'text', required: true,
          validations: [{type: 'minLength', value: 4}]
        },
        {name: 'email', label: 'Email', type: 'email', required: true}
      ]},
      {columns: [
        {
          name: 'password', label: 'Senha', type: 'password', required: true,
          passwordRules: {
            minLength: 8, requireUppercase: true, requireLowercase: true,
            requireNumber: true, requireSymbol: true
          },
          showPasswordRules: true
        },
        {
          name: 'employeeCount', label: 'Funcionários', type: 'number',
          validations: [{type: 'min', value: 1}, {type: 'max', value: 500}]
        }
      ]}
    ]
  }]
};

export function AccountForm() {
  return <DyonaForm locale="pt" schema={schema} />;
}