HTMLButtonElement.reportValidity() — Methode · JavaScript-Referenz

Signatur

HTMLButtonElement.prototype.reportValidity()

Beschreibung

Die Methode reportValidity() führt für ein <button>-Element dieselben Gültigkeitsprüfungen durch wie checkValidity(). Ist das Element gültig, gibt sie true zurück. Ist es ungültig, löst sie am Element ein abbrechbares invalid-Event aus, zeigt dem Nutzer die Fehlermeldung an (meist als Sprechblase direkt am Button) und gibt false zurück.

Bei Buttons gibt es keine Attribute wie required oder pattern. Ein Button ist deshalb praktisch nur dann ungültig, wenn per setCustomValidity() eine eigene Fehlermeldung gesetzt wurde. Typischer Einsatz: Ein Absende-Button wird absichtlich als ungültig markiert, etwa solange eine Bedingung außerhalb des Formulars nicht erfüllt ist (AGB nicht bestätigt, Upload läuft noch). Dann bekommt der Nutzer eine Meldung im gewohnten Stil des Browsers.

Wichtig: Nur Buttons vom Typ submit (der Standardtyp) nehmen an der Formularvalidierung teil. Buttons mit type="button" oder type="reset" sowie deaktivierte Buttons sind davon ausgeschlossen (willValidate ist false). Bei ihnen gibt reportValidity() immer true zurück.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Button gültig ist oder nicht an der Validierung teilnimmt. Sonst false. In diesem Fall wurde auch ein invalid-Event ausgelöst.

Beispiele

Eigene Fehlermeldung am Absende-Button anzeigen

// HTML: <form><button id="send">Absenden</button></form>
const button = document.querySelector('#send');

button.setCustomValidity('Bitte warten Sie, bis der Upload abgeschlossen ist.');
console.log(button.reportValidity()); // Meldung erscheint am Button

button.setCustomValidity(''); // Fehler zurücksetzen
console.log(button.reportValidity());

false true

Absenden blockieren, bis die AGB bestätigt sind

// HTML:
// <label><input type="checkbox" id="agb" form="none"> AGB gelesen</label>
// <form id="order"><button id="buy">Kaufen</button></form>
const agb = document.querySelector('#agb');
const buy = document.querySelector('#buy');

const updateValidity = () => {
  buy.setCustomValidity(agb.checked ? '' : 'Bitte bestätigen Sie zuerst die AGB.');
};

agb.addEventListener('change', updateValidity);
updateValidity();

buy.addEventListener('click', (event) => {
  if (!buy.reportValidity()) {
    event.preventDefault(); // zusätzliche Absicherung
  }
});

invalid-Event abfangen und eigene Anzeige nutzen

const button = document.querySelector('#send');
const hint = document.querySelector('#hint');

button.addEventListener('invalid', (event) => {
  event.preventDefault(); // Browser-Sprechblase unterdrücken
  hint.textContent = button.validationMessage;
});

button.setCustomValidity('Serververbindung fehlt.');
const ok = button.reportValidity();
console.log(ok, hint.textContent);

false Serververbindung fehlt.

Buttons, die nicht validiert werden

const plain = document.createElement('button');
plain.type = 'button';
plain.setCustomValidity('Wird ignoriert');

console.log(plain.willValidate);     // nimmt nicht teil
console.log(plain.reportValidity()); // immer true

false true

// Wichtig · Fallstricke

Nur Submit-Buttons: Bei type="button", type="reset" und bei disabled gibt die Methode immer true zurück. Eine mit setCustomValidity() gesetzte Meldung wird dann nicht angezeigt.
Fehler zurücksetzen: Eine eigene Meldung bleibt bestehen, bis sie mit setCustomValidity('') gelöscht wird. Sonst ist der Button dauerhaft ungültig, und auch das ganze Formular lässt sich nicht absenden.
Anzeige unterdrücken: Wird preventDefault() im invalid-Event aufgerufen, bleibt die Browser-Meldung aus. Der Rückgabewert ist trotzdem false.
Das Aussehen der Meldung hängt vom Browser ab und lässt sich nicht mit CSS gestalten. Für eigene Designs das invalid-Event abfangen.
Das Attribut novalidate am Formular beeinflusst nur das automatische Prüfen beim Absenden, nicht einen direkten Aufruf von reportValidity().
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome 40+, Firefox 49+, Safari 10.1+, Edge 17+). Der Internet Explorer kennt die Methode nicht.

Siehe auch

HTMLButtonElement.checkValidity() HTMLButtonElement.setCustomValidity() HTMLOutputElement.reportValidity() HTMLFormElement.reportValidity() HTMLInputElement.reportValidity()