API de Validação de Restrições do JavaScript

JavaScript é uma linguagem essencial para o desenvolvimento web, permitindo conteúdo dinâmico e interação aprimorada com o usuário. Um aspecto fundamental do JavaScript em formulários web é a API de Validação de Restrições do HTML5. Este guia explora a API em profundidade — seus métodos, o objeto ValidityState e como construir mensagens personalizadas e feedback em tempo real — com exemplos práticos tanto para desenvolvedores iniciantes quanto experientes.

Esta página se baseia no conteúdo sobre como trabalhar com formulários no DOM e sobre o evento e método submit. Se você precisar ler ou enviar os dados do formulário após a validação, consulte propriedades e métodos de formulário e FormData.

Introdução à API de Validação de Restrições do HTML5

A API de Validação de Restrições do HTML5 fornece validação nativa no lado do cliente para elementos de formulário, detectando erros antes que o formulário seja enviado. As restrições são declaradas diretamente no HTML por meio de atributos como required, type="email", min, max, minlength, maxlength, step e pattern. O navegador as aplica automaticamente e as expõe ao JavaScript para que você possa personalizar a experiência.

A validação no lado do cliente torna os formulários mais responsivos e reduz as idas desnecessárias ao servidor. No entanto, ela não é uma barreira de segurança — um usuário pode ignorá-la completamente desabilitando o JavaScript ou criando sua própria requisição. Sempre valide novamente no servidor.

A superfície da API de Validação de Restrições

Todo elemento associado a formulários (<input>, <textarea>, <select>, <button>, <fieldset> e o próprio <form>) expõe o mesmo pequeno conjunto de membros.

Métodos

• element.checkValidity() — retorna true se o elemento satisfaz todas as suas restrições, caso contrário false. Em caso de falha, também dispara um evento invalid no elemento.
• element.reportValidity() — semelhante a checkValidity(), mas adicionalmente exibe o balão de erro nativo do navegador para o primeiro campo inválido. Útil quando você deseja a UI nativa sem uma mensagem personalizada.
• element.setCustomValidity(message) — define uma string de erro personalizada. Uma string não vazia marca o elemento como inválido; uma string vazia ('') limpa o erro personalizado e permite que o elemento seja válido novamente.
• form.checkValidity() / form.reportValidity() — valida todos os controles do formulário de uma vez.

Propriedades

• element.validity — um objeto ValidityState somente leitura que descreve por que o campo é inválido.
• element.validationMessage — a mensagem localizada que o navegador exibiria para o estado inválido atual (vazia quando válido).
• element.willValidate — true se o elemento será verificado durante a validação (campos desabilitados e readonly são ignorados).

O objeto ValidityState

element.validity expõe um boolean para cada tipo de falha, além de valid:

Inspecionar esses sinalizadores permite adaptar a mensagem ao problema exato:

const input = document.querySelector('#age');
const v = input.validity;

if (v.valueMissing) {
  input.setCustomValidity('Age is required.');
} else if (v.rangeUnderflow) {
  input.setCustomValidity('You must be at least 18.');
} else {
  input.setCustomValidity(''); // clears the custom error
}

Configurando sua primeira validação

Antes de mergulhar em regras complexas, comece pelo básico: verificar se um campo required não está vazio.

<form id="registrationForm" novalidate>
    <label for="username">Username:</label>
    <input type="text" id="username" required />
    <button type="submit">Register</button>
    <span id="usernameError" style="color: red;"></span>
    <span id="registerSuccess" style="color: green; display: none;">Registration successful!</span>
</form>

<script>
document.getElementById('registrationForm').addEventListener('submit', function(event) {
    event.preventDefault();
    const input = document.getElementById('username');
    const usernameError = document.getElementById('usernameError');
    const registerSuccess = document.getElementById('registerSuccess');

    if (!input.checkValidity()) {
        usernameError.textContent = 'Username is required.';
        registerSuccess.style.display = 'none'; // Hide success message if visible
    } else {
        usernameError.textContent = ''; // Clear error message
        registerSuccess.textContent = 'Registration successful!';
        registerSuccess.style.display = 'block'; // Show success message
        input.value = ''; // Reset the username input
    }
});
</script>

Este trecho de código demonstra a configuração básica em que a verificação input.checkValidity() é usada para tornar um campo obrigatório. O formulário acionará uma mensagem de erro se o campo de nome de usuário for deixado vazio.

Implementando mensagens de validação personalizadas

Indo além das mensagens de alerta padrão do navegador, você pode criar uma experiência de usuário mais integrada exibindo mensagens de erro personalizadas dentro do layout HTML. Veja como implementar isso:

Observe que a validação de email padrão do HTML5 pode não exigir um domínio de nível superior, permitindo que entradas como w3docs@aol sejam aceitas como válidas. Para garantir que endereços de email incluam um domínio, adicionamos um padrão mais restrito .+@.+\..+ ao campo de email. Esta expressão regular exige pelo menos um ponto após o símbolo @, correspondendo mais de perto aos formatos de email do mundo real. (Para aprender a sintaxe de expressões regulares por trás dos padrões, consulte âncoras para início e fim de string.)

<form id="contactForm" novalidate>
    <label for="email">Email:</label>
    <input type="email" id="email" pattern=".+@.+\..+" required />
    <button type="submit">Submit</button>
    <span id="emailError" style="color: red"></span>
    <span id="successMessage" style="color: green; display: none;">Submission successful!</span>
</form>

<script>
document.getElementById("contactForm").addEventListener("submit", function (event) {
    event.preventDefault(); // Prevent default form submission

    const email = document.getElementById("email");
    const errorMessage = document.getElementById("emailError");
    const successMessage = document.getElementById("successMessage");

    if (!email.checkValidity()) {
        errorMessage.textContent = "Please enter a valid email address, including a domain."; // Display custom error message
        successMessage.style.display = "none"; // Hide success message if visible
    } else {
        errorMessage.textContent = ""; // Clear the error message
        successMessage.textContent = "Submission successful!";
        successMessage.style.display = "block"; // Show success message
        email.value = ""; // Reset the email input
    }
});
</script>

Este código melhora a experiência do usuário fornecendo feedback imediato e inline sobre a validade da entrada de email.

Aprimorando validações de formulário com padrões

Às vezes, validações mais específicas são necessárias, como verificar se uma entrada está em conformidade com um determinado padrão. Isso é comumente usado para números de telefone, CEPs e campos semelhantes. O atributo pattern é implicitamente ancorado — o valor inteiro deve corresponder — portanto, [0-9]{3}-[0-9]{3}-[0-9]{4} aceita 123-456-7890, mas rejeita 1234567890.

<form id="signupForm" novalidate>
    <label for="phone">Phone (XXX-XXX-XXXX):</label>
    <input type="tel" id="phone" pattern="[0-9]{3}-[0-9]{3}-[0-9]{4}" required />
    <button type="submit">Sign Up</button>
    <span id="phoneError" style="color:red;"></span>
    <span id="successMessage" style="color:green; display:none;">Submission successful!</span>
</form>

<script>
document.getElementById('signupForm').addEventListener('submit', function(event) {
    const phone = document.getElementById('phone');
    const phoneError = document.getElementById('phoneError');
    const successMessage = document.getElementById('successMessage');

    if (!phone.checkValidity()) {
        phoneError.textContent = 'Please enter a phone number in the format XXX-XXX-XXXX.';
        successMessage.style.display = 'none'; // Hide success message if present
    } else {
        phoneError.textContent = '';
        phone.value = ''; // Reset the input field
        successMessage.textContent = 'Submission successful!';
        successMessage.style.display = 'block'; // Show success message
    }
});
</script>

Este exemplo usa o atributo pattern para especificar que o número de telefone deve corresponder a um formato específico, aprimorando a qualidade dos dados coletados pelo formulário.

Validação em tempo real com o objeto ValidityState

Aguardar até o envio pode parecer lento. Ao ouvir o evento input e ler os sinalizadores de validity, você pode fornecer feedback enquanto o usuário digita e criar uma mensagem para a falha exata:

<form id="profileForm" novalidate>
    <label for="user">Username (3-12 letters/digits):</label>
    <input type="text" id="user" pattern="[A-Za-z0-9]{3,12}" required />
    <span id="userMsg" style="color:red;"></span>
</form>

<script>
const user = document.getElementById('user');
const msg = document.getElementById('userMsg');

user.addEventListener('input', function () {
    const v = user.validity;
    if (v.valueMissing) {
        msg.textContent = 'Username is required.';
    } else if (v.patternMismatch) {
        msg.textContent = 'Use 3-12 letters or digits only.';
    } else {
        msg.textContent = ''; // valid
    }
});
</script>

Aqui, valueMissing e patternMismatch vêm diretamente do objeto ValidityState, portanto um único manipulador reporta a razão precisa sem reimplementar manualmente as regras.

Combinando regras declarativas e personalizadas

Algumas verificações — como "as senhas devem coincidir" — não podem ser expressas com atributos HTML. Use setCustomValidity() para integrá-las ao mesmo pipeline de validação:

const password = document.getElementById('password');
const confirm = document.getElementById('confirm');

confirm.addEventListener('input', function () {
    if (confirm.value !== password.value) {
        confirm.setCustomValidity('Passwords do not match.');
    } else {
        confirm.setCustomValidity(''); // clear so the field becomes valid
    }
});

Como o erro personalizado participa de checkValidity(), o manipulador de envio do formulário não precisa de nenhum caso especial — o campo com senhas não coincidentes simplesmente é reportado como inválido como qualquer outro.

Conclusão

A API de Validação de Restrições do HTML5 é uma ferramenta poderosa para desenvolvedores web que desejam implementar validação de formulários no lado do cliente. Ela não apenas melhora a experiência do usuário fornecendo feedback imediato, como também reduz a carga no servidor. Seguindo os exemplos fornecidos neste guia, você pode criar formulários web mais robustos, eficientes e fáceis de usar. Para feedback em tempo real, considere também ouvir os eventos input ou change junto com o manipulador de envio.

Prática