CKTIS / JavaScript
ValidityState: validade global e motivos de erro
Consulta `element.validity` para distinguir um campo válido de um valor obrigatório em falta, de um formato incorreto ou de um valor demasiado curto introduzido pelo utilizador.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const state = input.validity;
state.valid;
state.valueMissing;
state.typeMismatch;
state.tooShort;element.validity devolve um objeto ValidityState associado a um controlo de formulário. As suas propriedades booleanas são só de leitura e refletem o estado atual: guardar o objeto não fixa os seus valores. É uma API da plataforma Web, não do ECMAScript.
valid só é true se nenhum indicador de erro estiver ativo, incluindo os não descritos aqui, como customError. Vários indicadores podem ser true ao mesmo tempo. valueMissing é true quando falta o valor exigido por required, por exemplo, num campo obrigatório de correio eletrónico deixado vazio.
typeMismatch é true quando um valor não vazio não cumpre as regras de sintaxe HTML de type="email" ou type="url". No tipo de correio eletrónico, multiple permite uma lista de endereços separados por vírgulas. Um campo de correio eletrónico obrigatório vazio tem valueMissing, não typeMismatch. A verificação da sintaxe não confirma que o endereço exista.
tooShort é true quando minlength se aplica a um input ou textarea, o indicador de alteração (dirty value flag) está ativo, a última alteração do valor foi feita pelo utilizador e o valor não vazio exposto pela API tem menos unidades de código UTF-16 do que o mínimo. minlength por si só não torna o campo obrigatório. Atribuir .value não provoca este erro, mesmo que chames depois checkValidity() ou reportValidity().
Usa valid para verificar o estado global do campo e os indicadores de erro para escolher a mensagem. Volta a validar os dados submetidos no servidor: é possível contornar a validação do navegador.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>ValidityState example</title>
</head>
<body>
<label for="email">Email:</label>
<input id="email" type="email" required minlength="8" autocomplete="off">
<button type="button">Next</button>
<script>
(() => {
const input = document.getElementById('email');
const state = input.validity;
const log = (step) => console.log([
step, state.valid, state.valueMissing, state.typeMismatch, state.tooShort
].join(' '));
input.value = '';
log('empty');
input.value = 'not-an-email';
log('wrong-format');
input.value = 'a@b.co';
log('scripted-short');
input.value = '';
input.addEventListener('change', () => log('user-short'), { once: true });
})();
</script>
</body>
</html>Resultado
empty false true false false wrong-format false false true false scripted-short true false false false user-short false false false true
Abre o exemplo como página HTML num navegador e consulta o resultado na consola do navegador. Depois das três primeiras linhas, escreve `a@b.co` no campo e prime Tab. Após a etiqueta do passo, as colunas são `valid`, `valueMissing`, `typeMismatch` e `tooShort`, por esta ordem. O mesmo endereço de seis unidades de código tem sintaxe válida em ambos os casos, mas só viola `minLength = 8` após a edição manual.
Lições relacionadas
- JavaScript · Lição 22 · Intermédio · Versão: 3