HTMLObjectElement.setCustomValidity() — Methode · JavaScript-Referenz

Signatur

HTMLObjectElement.prototype.setCustomValidity(message)

Beschreibung

Die Methode setCustomValidity() gehört zur Constraint-Validation-API und ist bei allen listed Formularelementen vorhanden, also auch bei HTMLObjectElement. Mit ihr legst du eine eigene Fehlermeldung fest. Jeder nicht-leere String markiert das Element als fehlerhaft (validity.customError). Der leere String "" entfernt den Fehler wieder.

Wichtige Besonderheit: Laut HTML-Spezifikation sind <object>-Elemente niemals Kandidaten für die Constraint Validation. Deshalb ist willValidate immer false, checkValidity() und reportValidity() geben immer true zurück, und validationMessage bleibt ein leerer String. Eine hier gesetzte Meldung verhindert das Absenden des Formulars also nicht, und der Browser zeigt auch keine Fehler-Sprechblase an.

Die Methode gibt es vor allem, damit alle Formularelemente dieselbe Schnittstelle haben. So kannst du generischen Code schreiben, der über form.elements läuft und überall setCustomValidity() aufruft, ohne vorher den Elementtyp zu prüfen. Wenn du eingebettete Inhalte wirklich validieren willst, prüfst du das selbst im submit-Handler oder überträgst den Status auf ein validierbares Element, zum Beispiel ein verstecktes Pflicht-<input>.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Die eigene Fehlermeldung. Ein nicht-leerer String setzt einen benutzerdefinierten Fehler, `""` entfernt ihn. Andere Werte werden in einen String umgewandelt (z. B. `null` → `"null"`).

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück.

Beispiele

Meldung setzen und wieder entfernen

const obj = document.createElement('object');
document.body.append(obj);

obj.setCustomValidity('Die Einbettung konnte nicht geladen werden.');
console.log(obj.willValidate);        // object nimmt nie an der Validierung teil
console.log(obj.checkValidity());
console.log(JSON.stringify(obj.validationMessage));

// Fehler zurücksetzen
obj.setCustomValidity('');

false true ""

Generischer Validierungs-Helfer über form.elements

// <form id="upload"><input name="title" required><object data="preview.pdf"></object></form>
const form = document.querySelector('#upload');

const resetCustomErrors = (formEl) => {
  for (const el of formEl.elements) {
    // funktioniert auch beim <object>, ohne den Typ zu prüfen
    if (typeof el.setCustomValidity === 'function') {
      el.setCustomValidity('');
    }
  }
};

resetCustomErrors(form);
console.log(form.checkValidity());

false (wenn das Pflichtfeld "title" leer ist)

Ladefehler der Einbettung auf ein validierbares Feld übertragen

// <form id="f"><object id="doc" data="vertrag.pdf" type="application/pdf"></object>
//   <input id="docOk" type="hidden"><button>Senden</button></form>
const form = document.querySelector('#f');
const obj = document.querySelector('#doc');
const marker = document.querySelector('#docOk');
let loaded = false;

obj.addEventListener('load', () => { loaded = true; });
obj.addEventListener('error', () => { loaded = false; });

form.addEventListener('submit', (event) => {
  const msg = loaded ? '' : 'Das Dokument muss geladen sein, bevor du absendest.';
  obj.setCustomValidity(msg); // nur für Konsistenz, blockiert nichts
  if (!loaded) {
    event.preventDefault();
    alert(msg); // hidden-Inputs zeigen keine Browser-Sprechblase
  }
});

// Wichtig · Fallstricke

Keine Wirkung auf das Absenden: Weil <object> nie an der Constraint Validation teilnimmt, blockiert eine gesetzte Meldung das Formular nicht, und der Browser zeigt sie nicht an. checkValidity() gibt trotzdem true zurück.
Den Fehler musst du ausdrücklich mit setCustomValidity('') entfernen. Er verschwindet nicht von selbst.
Das Argument ist Pflicht. Ein Aufruf ohne Argument wirft einen TypeError. null wird zum String \"null\" und setzt damit einen Fehler.
Kompatibilität: Die Methode wird von allen aktuellen Browsern unterstützt (Chrome, Firefox, Safari, Edge).
Wenn du die Meldung einem Benutzer anzeigst, füge sie nicht über innerHTML ein. Verwende textContent, sonst riskierst du XSS.

Siehe auch

HTMLObjectElement.reportValidity() HTMLObjectElement.checkValidity() HTMLObjectElement.getSVGDocument() HTMLSelectElement.setCustomValidity() HTMLOutputElement.setCustomValidity()