Validação

Dados errados entram por descuido, não por maldade: um NIF com oito dígitos, um email sem arroba, um desconto de 300 %, um registo gravado sem o campo que o resto do processo precisa. Validar é fechar essas portas — e no Keplin fecham-se em duas camadas, que convém não confundir.

Camada	Onde se define	Quando actua	O que apanha
O modelo	No editor da tabela (ver Tabelas e campos)	Em qualquer escrita, venha de onde vier	O que nunca pode acontecer aos dados.
As regras dos campos	No inspector de cada campo de formulário, categoria Validação	Quando o utilizador grava um formulário	O que a pessoa está a escrever, com a mensagem certa ao lado do campo.

A regra prática: o que é verdade sobre os dados vive no modelo; o que é ajuda ao utilizador vive no formulário. Um campo obrigatório é as duas coisas — desliga-se Permite NULL no modelo e liga-se Obrigatório no campo do ecrã.

#O que o modelo garante

Estas não são "regras de validação" com esse nome, mas são a única defesa que não se contorna: valem para os ecrãs, para as APIs, para os scripts e para quem escrever directamente na base de dados.

Peça	O que impede
Permite NULL desligado	Um registo sem valor nessa coluna.
Tipo da coluna	Texto num campo de data, letras num número.
Tamanho / Precisão · Escala	Texto maior do que a coluna, ou dinheiro com casas decimais a mais.
Chave primária (PK)	Registos duplicados e registos que não se conseguem identificar.
Índice unique	Dois clientes com o mesmo NIF, dois utilizadores com o mesmo email.
Coluna do tipo enum	Um estado que não existe na lista.
Relação física + Ao apagar o pai	Filhos órfãos, ou eliminações que arrastam o que não devem.

#As regras dos campos de formulário

Todos os campos de formulário — Caixa de texto, Área de texto, Número, Sim/Não, Lista, Data, Cor, Ficheiro — têm no inspector a categoria Validação. É aí que se declara o que aquele campo aceita.

Para chegar lá:

1. Abre o ecrã no designer.
2. Selecciona o campo — no canvas, ou pelo separador Estrutura do inspector.
3. No separador Propriedades, abre a categoria Validação.

#Obrigatório

O interruptor Obrigatório é a primeira e mais usada das regras: o campo tem de vir preenchido. É também a única que fala do vazio — todas as outras deixam passar um campo vazio, porque o vazio é assunto do Obrigatório.

#As regras standard

Conforme o tipo de campo, a categoria mostra as regras que fazem sentido:

Regra	Onde aparece	O que verifica
Máscara	Caixa de texto	O formato enquanto se escreve: # dígito, A letra, N alfanumérico, * qualquer — o resto é texto fixo. Ex.: +351 ### ### ###.
Mín. caracteres	Caixa de texto, Área de texto	Comprimento mínimo do texto.
Máx. caracteres	Caixa de texto, Área de texto	Comprimento máximo do texto.
Padrão (regex)	Caixa de texto, Área de texto	Uma expressão regular que o valor tem de cumprir. Ex.: ^[A-Z]{2}\d{4}$.
Formato	Caixa de texto	Nenhum, É email, É telefone ou É número. São exclusivos: um valor não pode ser email e telefone ao mesmo tempo.
Valor mín.	Número	O menor valor aceite.
Valor máx.	Número	O maior valor aceite.
Igual ao campo	Todos os campos	O valor tem de ser igual ao de outro campo do ecrã — a confirmação de palavra-passe, o email repetido.

#Validação por código

Debaixo das regras standard está a linha Validação, que diz Sem validação — definir ou Definida — editar. O botão … abre um editor de código para as regras que os campos não cobrem: um NIF com dígito de controlo, um IBAN, uma data que tem de ser posterior a outra, uma regra de negócio que só a tua empresa tem.

O código recebe value — o valor actual do campo — e devolve:

• true (ou nada) se o valor é válido;
• uma string com a mensagem de erro a mostrar, se não é.

const s = String(value ?? "").replace(/\D/g, "");
if (s.length !== 9) return "O NIF tem de ter 9 dígitos";
return true;

Dentro deste código tens também o keplin disponível — dá para comparar com outro campo, com um valor da sessão ou com dados já carregados no ecrã. É TypeScript, com sugestões enquanto escreves (Ctrl+Espaço); o editor recusa gravar código que não seja executável.

#Quando é que a validação corre

A validação de um formulário corre ao gravar — quando o botão de gravar manda gravar o datastore do registo. A ordem é sempre a mesma, por campo:

1. Obrigatório — o campo está preenchido?
2. As regras standard — comprimento, formato, mínimo, máximo, padrão, igualdade.
3. A validação por código — a tua regra.

O primeiro erro ganha: assim que uma regra falha, é a mensagem dessa regra que aparece por baixo do campo e as seguintes não chegam a correr. Se algum campo falhar, nada é gravado — o registo fica como estava e a pessoa continua no formulário, com os erros à vista.

Também se pode validar um campo à mão, a partir do código de um evento — por exemplo, para verificar um campo assim que ele muda em vez de esperar pelo fim. Isso é assunto de Eventos e o SDK.

#As mensagens

As mensagens das regras standard são as da plataforma, escritas na língua da app: Campo obrigatório., Email inválido., Mínimo {min} caracteres., Valor máximo: {max}., Os valores não coincidem., Formato inválido. Não se editam uma a uma — se precisas de dizer as coisas de outra maneira, o sítio é a validação por código, onde a mensagem é a string que devolves.

A língua sai das definições da app (Definições da app ▸ Traduções): a mesma app em português e em inglês mostra os erros na língua de quem está a usar.

#O que a validação NÃO é

#Porque não…?

• Porque não vejo a categoria Validação neste widget? Só os campos de formulário validam. Um Botão, uma Etiqueta ou uma Tabela não têm valor para validar.
• Porque é que a regra não dispara com o campo vazio? É de propósito: as regras standard ignoram o vazio, que é o território do Obrigatório. Liga-o.
• Porque gravou na mesma um registo inválido? Ou o campo não estava ligado ao datastore (sem ligação, não entra na validação), ou o valor foi escrito por outra via — uma API, um script, uma importação. Vê o que o modelo garante, em cima nesta página.
• Porque é que o Padrão (regex) não bate? É uma expressão regular na sintaxe habitual, e cada carácter conta: ^[A-Z]{2}\d{4}$ aceita PT1234 e recusa pt1234. Testa a expressão antes de a colar.
• Porque não gravou a minha validação por código? O editor recusa código que não seja executável — corrige o erro assinalado e grava outra vez.
• Porque é que a mensagem aparece em inglês? A língua da app está em inglês. Muda-a em Definições da app ▸ Traduções.