ElementInternals.checkValidity() — Methode · JavaScript-Referenz

Signatur

ElementInternals.prototype.checkValidity()

Beschreibung

Mit checkValidity() prüfen Sie den Gültigkeitszustand eines formularfähigen Custom Elements (static formAssociated = true). Die Methode wird über das ElementInternals-Objekt aufgerufen, das Sie mit this.attachInternals() erhalten. Sie entspricht HTMLInputElement.checkValidity() bei eingebauten Formularelementen.

Welche Regeln gelten, legen Sie vorher selbst mit internals.setValidity(flags, message, anchor) fest. checkValidity() liest diesen Zustand nur aus: Ist das Element gültig, gibt die Methode true zurück. Ist es ungültig, gibt sie false zurück und löst auf dem Element ein abbrechbares invalid-Event aus. Es wird keine Fehlermeldung angezeigt. Dafür gibt es reportValidity().

Typische Anwendungsfälle:

Eigene Eingabe-Komponenten wie Bewertungs-Sterne, Farbwähler oder Tag-Eingaben vor dem Absenden selbst prüfen.
Ein Formular mit eigenen Fehlerhinweisen statt der Browser-Sprechblasen prüfen.
Den Gültigkeitszustand eines Elements an öffentliche Methoden weitergeben, etwa an element.checkValidity().

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element gültig ist oder nicht validiert werden muss. false, wenn mindestens eine Regel verletzt ist. In diesem Fall wird zusätzlich ein invalid-Event ausgelöst.

Beispiele

Pflichtfeld-Komponente mit setValidity und checkValidity

class RatingInput extends HTMLElement {
  static formAssociated = true;
  #internals;
  #value = 0;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#updateValidity();
  }

  set value(v) {
    this.#value = Number(v);
    this.#internals.setFormValue(String(this.#value));
    this.#updateValidity();
  }

  #updateValidity() {
    if (this.#value < 1) {
      this.#internals.setValidity(
        { valueMissing: true },
        'Bitte eine Bewertung von 1 bis 5 wählen.'
      );
    } else {
      this.#internals.setValidity({});
    }
  }

  // Öffentliche API wie bei <input>
  checkValidity() {
    return this.#internals.checkValidity();
  }
}

customElements.define('rating-input', RatingInput);

const rating = document.createElement('rating-input');
console.log(rating.checkValidity());
rating.value = 4;
console.log(rating.checkValidity());

false true

Auf das invalid-Event reagieren

const rating = document.querySelector('rating-input');

rating.addEventListener('invalid', (event) => {
  // Eigene Fehlerdarstellung statt Browser-Sprechblase
  event.preventDefault();
  rating.classList.add('fehler');
  console.log('Ungültig:', rating.validationMessage ?? 'keine Meldung');
});

if (!rating.checkValidity()) {
  console.log('Formular wird nicht abgeschickt.');
}

Ungültig: Bitte eine Bewertung von 1 bis 5 wählen. Formular wird nicht abgeschickt.

Gültigkeit vor einem fetch-Aufruf prüfen

const form = document.querySelector('#feedback');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  // form.checkValidity() prüft auch formularfähige Custom Elements
  if (!form.checkValidity()) return;

  const response = await fetch('/api/feedback', {
    method: 'POST',
    body: new FormData(form)
  });
  console.log('Status:', response.status);
});

Status: 200

// Wichtig · Fallstricke

Nur bei formularfähigen Elementen: Fehlt static formAssociated = true, wirft der Aufruf eine NotSupportedError-DOMException.
Kein automatischer Zustand: Attribute wie required auf dem Custom Element werden nicht ausgewertet. Sie müssen die Gültigkeit selbst mit setValidity() setzen. Sonst ist das Element immer gültig.
Nicht validierte Elemente: Ein Element mit disabled, readonly oder in einem deaktivierten <fieldset> ist von der Validierung ausgenommen. Dann liefert die Methode true.
Keine Anzeige: checkValidity() zeigt keine Meldung an. Für die Browser-Sprechblase verwenden Sie reportValidity().
Nicht nach außen sichtbar: internals.checkValidity() ist nur innerhalb der Komponente erreichbar. Wenn Code von außen element.checkValidity() aufrufen soll, müssen Sie die Methode wie im Beispiel selbst weiterleiten.
Kompatibilität: Seit März 2023 in allen aktuellen Browsern verfügbar (Safari ab 16.4). Für ältere Safari-Versionen gibt es das Polyfill element-internals-polyfill.

Siehe auch

ElementInternals ElementInternals.reportValidity() ElementInternals.setValidity() ElementInternals.validity ElementInternals.validationMessage HTMLElement.attachInternals() HTMLInputElement.checkValidity()