0Pricing
HTML Academy · Aula

Fundamentos da API de validação de restrições

Leia o estado de validade e as mensagens personalizadas com a API de validação de restrições.

Fundamentos da API de validação de restrições é uma aula grátis de HTML Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de HTML Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de HTML Academy inclui 4 aulas no total.

O que é a Constraint Validation API?

A Constraint Validation API é uma interface JavaScript para ler e definir o estado de validação de um formulário:

  • Verificar se um campo é válido
  • Identificar qual restrição específica falhou
  • Definir mensagens de erro personalizadas
  • Acionar programaticamente a interface de validação do navegador

Propriedade validity

Todo controle de formulário tem um objeto validity com sinalizadores booleanos específicos:

const input = document.getElementById('email');
const v = input.validity;

console.log(v.valid);         // true if all constraints pass
console.log(v.valueMissing);  // true if required but empty
console.log(v.typeMismatch);  // true if type doesn't match (e.g. bad email)
console.log(v.patternMismatch); // true if pattern fails
console.log(v.tooShort);      // true if shorter than minlength
console.log(v.tooLong);       // true if longer than maxlength
console.log(v.rangeUnderflow); // true if less than min
console.log(v.rangeOverflow);  // true if more than max

Método checkValidity

checkValidity() retorna true/false e dispara o evento invalid:

const form = document.getElementById('my-form');

// Check entire form:
if (!form.checkValidity()) {
  console.log('Form has errors');
}

// Check individual field:
const email = document.getElementById('email');
if (!email.checkValidity()) {
  console.log('Email is invalid');
}
// The 'invalid' event fires on invalid fields

Método reportValidity

reportValidity() exibe a interface de validação nativa do navegador:

const input = document.getElementById('username');

// Shows native browser error tooltip if invalid:
const valid = input.reportValidity();
console.log(valid);  // true or false

// On a form: validates all fields and shows first error:
document.getElementById('form').reportValidity();

Propriedade validationMessage

validationMessage retorna o texto da mensagem de erro do navegador:

const email = document.querySelector('input[type=email]');
email.value = 'not-an-email';

console.log(email.validationMessage);
// e.g. "Please include an '@' in the email address..."

console.log(email.validity.typeMismatch); // true

setCustomValidity

setCustomValidity(message) define um erro de validação personalizado:

const username = document.getElementById('username');

// Check availability on blur:
username.addEventListener('blur', async () => {
  const res = await fetch(`/check-username?name=${username.value}`);
  const { taken } = await res.json();

  if (taken) {
    username.setCustomValidity('This username is already taken.');
  } else {
    username.setCustomValidity('');  // empty string = clear the error
  }
});

Limpando a validade personalizada

É necessário limpar a validade personalizada quando o usuário corrige o problema:

const input = document.getElementById('username');

input.addEventListener('input', () => {
  // Clear custom error when user starts typing again:
  input.setCustomValidity('');
});

input.addEventListener('blur', async () => {
  // Re-validate on blur:
  const taken = await checkUsername(input.value);
  input.setCustomValidity(taken ? 'Username taken' : '');
});

Evento invalid

O evento invalid é disparado nos controles de formulário que falham na validação:

document.querySelectorAll('input').forEach(input => {
  input.addEventListener('invalid', (e) => {
    e.preventDefault();  // prevent default browser tooltip
    // Show your custom error UI instead:
    showError(input, input.validationMessage);
  });
});

Propriedade willValidate

willValidate é true se o elemento participa da validação de restrições:

document.querySelectorAll(':input').forEach(el => {
  if (el.willValidate) {
    console.log(el.name, 'will be validated');
  }
});
// Disabled, hidden, or output elements return willValidate = false

Usando validity na validação personalizada

Um exemplo completo de validação personalizada:

<form id="signup" novalidate>
  <input type="email" id="email" name="email" required>
  <span id="email-err" role="alert"></span>
  <button type="submit">Sign Up</button>
</form>

<script>
const form = document.getElementById('signup');
const email = document.getElementById('email');
const err = document.getElementById('email-err');

form.addEventListener('submit', (e) => {
  e.preventDefault();
  err.textContent = '';

  if (email.validity.valueMissing) {
    err.textContent = 'Email is required.';
    email.focus();
    return;
  }
  if (email.validity.typeMismatch) {
    err.textContent = 'Enter a valid email address.';
    email.focus();
    return;
  }
  // Submit...
});
</script>

Resumo dos sinalizadores de ValidityState

Todos os sinalizadores de ValidityState:

  • valueMissing — obrigatório, mas vazio
  • typeMismatch — formato do tipo incorreto
  • patternMismatch — a expressão regular do padrão falha
  • tooShort / tooLong — minlength/maxlength
  • rangeUnderflow / rangeOverflow — min/max
  • stepMismatch — não é um valor de incremento válido
  • customError — mensagem de setCustomValidity definida
  • badInput — o navegador não consegue interpretar o valor

Verificação rápida

Como exibir programaticamente a janela nativa de erro de validação do navegador?

Recapitulação: Constraint Validation API

Princípios essenciais da Constraint Validation API:

  • input.validity — objeto ValidityState com sinalizadores específicos
  • checkValidity() — retorna true/false e dispara o evento invalid
  • reportValidity() — verifica e exibe a interface de erro nativa
  • validationMessage — o texto do erro do navegador
  • setCustomValidity(msg) — define um erro personalizado; use uma string vazia para limpar

Perguntas Frequentes

A aula “Fundamentos da API de validação de restrições” é grátis?

Sim — o texto completo de “Fundamentos da API de validação de restrições” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de HTML Academy, atualize para CoddyKit PRO. O curso de HTML Academy inclui 4 aulas no total.

O que vou aprender em “Fundamentos da API de validação de restrições”?

Leia o estado de validade e as mensagens personalizadas com a API de validação de restrições. Você pratica HTML Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar HTML Academy?

Nenhuma experiência prévia é necessária. HTML Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Fundamentos da API de validação de restrições”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de HTML Academy?

Sim. Cada aula de HTML Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. required pattern min max e maxlength
  2. O atributo novalidate
  3. Fundamentos da API de validação de restrições
  4. Validação com HTML5 versus JavaScript: compromissos
← Voltar para HTML Academy