HTMLOutputElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLOutputElement.prototype.setCustomValidity(message)

Beschreibung

setCustomValidity() legt für ein <output>-Element eine eigene Fehlermeldung fest. Ist der übergebene Text nicht leer, wird das Flag validity.customError auf true gesetzt. Mit einem leeren String ("") wird der Fehler wieder entfernt.

Die Methode ist Teil der Constraint Validation API, die alle Formular-Steuerelemente gemeinsam haben (input, select, textarea, button, fieldset, output …). Beim <output>-Element gibt es aber eine Besonderheit: Es wird nie bei der Formularprüfung berücksichtigt. willValidate ist immer false. Deshalb hält ein gesetzter Fehler das Formular nicht vom Absenden ab, und checkValidity() sowie reportValidity() geben immer true zurück.

Wofür ist die Methode dann nützlich? Man kann damit einen Fehlerzustand an einem berechneten Ergebnis speichern. Das ist praktisch bei Rechnern, Summen oder Vorschau-Werten, die mit <output> angezeigt werden. Eigener Code kann dann validity.customError abfragen und passend reagieren. Soll der Browser das Absenden wirklich verhindern, muss man setCustomValidity() auf den beteiligten <input>-Feldern aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die Fehlermeldung. Ein nicht leerer String kennzeichnet das Element als fehlerhaft (`validity.customError === true`). Ein leerer String `""` entfernt den Fehler. Andere Werte werden in einen String umgewandelt. Aus `null` wird also `"null"`, und das zählt als Fehler.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Fehler setzen und wieder entfernen

const out = document.createElement('output');

out.setCustomValidity('Ergebnis ungültig');
console.log(out.validity.customError); // true
console.log(out.willValidate);         // false – output wird nie geprüft
console.log(out.checkValidity());      // true

// Fehler entfernen
out.setCustomValidity('');
console.log(out.validity.customError); // false

true false true false

Rechner: Fehlerzustand am Ergebnis speichern

// HTML:
// <form id="calc">
//   <input id="a" type="number" value="10"> /
//   <input id="b" type="number" value="0"> =
//   <output id="result" for="a b"></output>
//   <p id="hint" role="alert"></p>
// </form>

const form = document.querySelector('#calc');
const a = document.querySelector('#a');
const b = document.querySelector('#b');
const result = document.querySelector('#result');
const hint = document.querySelector('#hint');

const update = () => {
  const divisor = b.valueAsNumber;
  if (divisor === 0) {
    result.value = '–';
    result.setCustomValidity('Division durch 0 ist nicht möglich.');
  } else {
    result.value = (a.valueAsNumber / divisor).toFixed(2);
    result.setCustomValidity('');
  }
  // Der Browser zeigt die Meldung nicht an, das macht eigener Code:
  hint.textContent = result.validity.customError ? 'Division durch 0 ist nicht möglich.' : '';
};

form.addEventListener('input', update);
update();

Anzeige: „–“ und der Hinweis „Division durch 0 ist nicht möglich.“

Absenden wirklich verhindern: Fehler auf das Eingabefeld legen

const b = document.querySelector('#b');
const result = document.querySelector('#result');

b.addEventListener('input', () => {
  const msg = b.valueAsNumber === 0 ? 'Bitte keine 0 als Divisor.' : '';
  b.setCustomValidity(msg);      // blockiert das Absenden
  result.setCustomValidity(msg); // markiert zusätzlich das Ergebnis
  b.reportValidity();
});

Bei 0 zeigt der Browser am Eingabefeld die Blase „Bitte keine 0 als Divisor.“

// Wichtig · Fallstricke

Keine Wirkung auf das Absenden: <output> wird bei der Formularprüfung nie berücksichtigt (willValidate === false). Ein gesetzter Fehler verhindert das Absenden deshalb nicht, und der Browser zeigt auch keine Fehlerblase an.
validationMessage bleibt leer: Weil das Element nicht geprüft wird, gibt validationMessage laut Spezifikation einen leeren String zurück. Den Fehlertext sollte man daher selbst speichern, wenn man ihn anzeigen möchte.
CSS: Die Pseudoklassen :invalid und :valid gelten nur für Elemente, die geprüft werden. Für die Gestaltung eines fehlerhaften <output> eignet sich deshalb eine eigene Klasse oder ein Attribut wie aria-invalid="true" besser.
Zurücksetzen nicht vergessen: Der Fehler bleibt bestehen, bis man ausdrücklich setCustomValidity("") aufruft. Er verschwindet auch nicht, wenn sich der Wert ändert.
Barrierefreiheit: Fehlermeldungen sollten zusätzlich in einem Bereich mit role="alert" oder aria-live erscheinen, damit Screenreader sie vorlesen.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Ältere Versionen von Internet Explorer kennen <output> nicht.

Siehe auch

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