Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

HTMLFormElement.reportValidity() — validar um formulário e comunicar erros

HTMLFormElement.reportValidity() verifica as restrições de validação dos controlos associados a um formulário e pode comunicar erros ao utilizador. Devolve um valor booleano e não submete o formulário por si só.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

form.reportValidity()

HTMLFormElement.reportValidity é um método da interface de formulários definido pelo HTML Living Standard, não pelo ECMAScript. A chamada form.reportValidity() não recebe argumentos e devolve sincronicamente true se todos os controlos sujeitos a validação forem válidos, ou false se pelo menos um não for válido.

O método executa a validação interativa de restrições como required. Desencadeia eventos invalid nos controlos inválidos. O navegador pode comunicar erros cujo tratamento não tenha sido cancelado; o aspeto e o texto das mensagens dependem do navegador. Chamar event.preventDefault() num gestor de invalid suprime a comunicação nativa desse erro, mas não altera o resultado false.

Ao contrário de reportValidity(), checkValidity() verifica as restrições sem comunicar erros de forma interativa, embora também desencadeie invalid. Nenhum dos métodos submete o formulário. Os controlos desativados através de disabled são excluídos da validação; a validação do lado do cliente não substitui a verificação dos dados no servidor.

Esta é uma API do navegador: a presença de Node 24 não comprova a sua disponibilidade. No ambiente de destino, verifica typeof HTMLFormElement !== 'undefined' && typeof HTMLFormElement.prototype.reportValidity === 'function'. O exemplo cancela invalid deliberadamente para verificar os resultados booleanos sem depender da interface das mensagens de validação.

Exemplos

(() => {
  const form = document.createElement('form');
  const input = document.createElement('input');
  input.required = true;
  input.setAttribute('aria-label', 'Name');
  form.append(input);
  document.body.append(form);

  // Suppress native validation UI for deterministic console checks.
  input.addEventListener('invalid', event => event.preventDefault());

  console.log(form.reportValidity());
  input.value = 'Ada';
  console.log(form.reportValidity());

  form.remove();
})();

Resultado

false
true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes