Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

HTMLInputElement.setCustomValidity — un errore di convalida personalizzato

HTMLInputElement.setCustomValidity imposta o cancella l’errore personalizzato di un campo del modulo. Una stringa vuota cancella quell’errore, ma non disattiva gli altri vincoli.

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

Sintassi

input.setCustomValidity(message)

HTMLInputElement.setCustomValidity è un metodo dell’API di convalida dei moduli del browser, definito dall’HTML Living Standard e non da ECMAScript. È supportato nei motori browser attuali; la presenza di Node 24 non dimostra che questa API sia disponibile.

Chiamando input.setCustomValidity(message) con una stringa non vuota, input.validity.customError viene impostato su true. Passando "" si cancella solo l’errore personalizzato: i vincoli come required restano validi. Il metodo restituisce undefined, non un risultato della convalida.

Il metodo non mostra messaggi da solo. checkValidity() controlla la validità senza mostrare indicazioni di errore. Se il campo non supera la convalida, reportValidity() restituisce false e il browser segnala il problema all’utente solo se l’evento invalid non viene annullato. Annullare l’evento non cambia il valore restituito. Gli elementi esclusi dalla convalida possono mantenere un errore personalizzato, anche se non bloccano l’invio convalidato di un modulo.

Dopo una modifica del valore, ricalcola la regola e cancella esplicitamente ogni errore non più attuale, di solito in un gestore dell’evento input. Nell’esempio, il false false finale significa che non c’è un errore personalizzato, ma required non è soddisfatto. La convalida lato client non sostituisce quella lato server.

Esempi

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());

Risultato

true false
false true
false false

Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.

Fonti