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

CKTIS / JavaScript

HTMLInputElement.setCustomValidity — um erro de validação personalizado

HTMLInputElement.setCustomValidity define ou limpa o erro personalizado de um campo de formulário. Uma cadeia vazia limpa esse erro, mas não desativa outras restrições.

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

input.setCustomValidity(message)

HTMLInputElement.setCustomValidity é um método da API de validação de formulários do navegador, definido pelo HTML Living Standard e não pelo ECMAScript. É suportado pelos motores de navegador atuais; a presença do Node 24 não comprova a disponibilidade desta API.

Ao chamar input.setCustomValidity(message) com uma cadeia não vazia, input.validity.customError passa a true. Passar "" limpa apenas o erro personalizado: restrições como required continuam a aplicar-se. O método devolve undefined, não um resultado de validação.

O método não apresenta uma mensagem por si só. checkValidity() verifica a validade sem apresentar indicações de erro. Se o campo não passar na validação, reportValidity() devolve false e o navegador só comunica o problema ao utilizador se o evento invalid não for cancelado. Cancelar o evento não altera o valor devolvido. Os elementos excluídos da validação podem manter um erro personalizado, embora não impeçam o envio validado de um formulário.

Depois de alterar um valor, volta a calcular a regra e limpa explicitamente qualquer erro desatualizado, normalmente num processador do evento input. No exemplo, o false false final significa que não existe um erro personalizado, mas que required não está satisfeito. A validação do lado do cliente não substitui a validação do lado do servidor.

Exemplos

const input = document.createElement("input");
input.required = true;
input.value = "admin";

function validate() {
  input.setCustomValidity(
    input.value === "admin" ? "Reserved name." : ""
  );
}

validate();
console.log(input.validity.customError, input.checkValidity());

input.value = "alex";
validate();
console.log(input.validity.customError, input.checkValidity());

input.value = "";
validate();
console.log(input.validity.customError, input.checkValidity());

Resultado

true false
false true
false false

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