ElementInternals.validationMessage — Eigenschaft · JavaScript-Referenz

Signatur

get ElementInternals.prototype.validationMessage

Beschreibung

Die schreibgeschützte Eigenschaft validationMessage von ElementInternals liefert den Text, der beschreibt, warum ein formularassoziiertes Custom Element (Klasse mit static formAssociated = true) die Validierung nicht besteht. Sie entspricht der gleichnamigen Eigenschaft nativer Formularelemente wie HTMLInputElement.validationMessage.

Gesetzt wird die Nachricht ausschließlich über das zweite Argument von ElementInternals.setValidity(flags, message, anchor). Ist das Element gültig (alle Flags false oder setValidity({})), ist validationMessage ein leerer String. Nimmt das Element nicht an der Validierung teil (willValidate === false, z. B. weil es disabled oder readonly ist), wird ebenfalls ein leerer String zurückgegeben.

Typischer Einsatz: Eigene Fehleranzeigen im Shadow DOM rendern, die Nachricht nach außen über einen Getter auf dem Element verfügbar machen (so wie es native Eingabefelder tun) oder in Tests prüfen, ob die richtige Fehlermeldung aktiv ist. Den Text zeigt der Browser bei reportValidity() bzw. beim Absenden des Formulars in seiner nativen Fehlerblase an.

Rückgabewert

Typ

string

Beschreibung

Die aktuelle Validierungsnachricht; ein leerer String, wenn das Element gültig ist oder nicht validiert wird.

Beispiele

Pflichtfeld-Komponente mit Validierungsnachricht

class RatingInput extends HTMLElement {
  static formAssociated = true;
  #internals = this.attachInternals();
  #value = 0;

  connectedCallback() {
    this.#validate();
  }

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

  #validate() {
    if (this.#value < 1) {
      this.#internals.setValidity(
        { valueMissing: true },
        'Bitte vergeben Sie mindestens einen Stern.'
      );
    } else {
      this.#internals.setValidity({});
    }
  }

  // Nachricht wie bei nativen Elementen nach außen durchreichen
  get validationMessage() {
    return this.#internals.validationMessage;
  }
}
customElements.define('rating-input', RatingInput);

const el = document.createElement('rating-input');
document.body.append(el);
console.log(el.validationMessage);
el.value = 4;
console.log(JSON.stringify(el.validationMessage));

Bitte vergeben Sie mindestens einen Stern. ""

Eigene Fehleranzeige im Shadow DOM

class EmailField extends HTMLElement {
  static formAssociated = true;
  #internals = this.attachInternals();

  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open' });
    root.innerHTML = '<input type="email"><p class="error" aria-live="polite"></p>';
    this.input = root.querySelector('input');
    this.error = root.querySelector('.error');
    this.input.addEventListener('input', () => this.#update());
  }

  connectedCallback() { this.#update(); }

  #update() {
    const { value } = this.input;
    this.#internals.setFormValue(value);
    if (!value.includes('@')) {
      this.#internals.setValidity(
        { typeMismatch: true },
        'Die E-Mail-Adresse muss ein @ enthalten.',
        this.input // Anker für die native Fehlerblase
      );
    } else {
      this.#internals.setValidity({});
    }
    // Nachricht per textContent (nicht innerHTML) anzeigen
    this.error.textContent = this.#internals.validationMessage;
  }
}
customElements.define('email-field', EmailField);

Fehlermeldungen aller ungültigen Felder beim Absenden sammeln

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

form.addEventListener('submit', (event) => {
  const errors = [...form.elements]
    .filter((el) => el.willValidate && !el.checkValidity())
    .map((el) => `${el.name || el.localName}: ${el.validationMessage}`);

  if (errors.length) {
    event.preventDefault();
    console.log(errors.join('\n'));
  }
});

rating: Bitte vergeben Sie mindestens einen Stern.

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an validationMessage hat keine Wirkung. Die Nachricht wird ausschließlich über setValidity() gesetzt.
Nicht automatisch am Element: Custom Elements haben keine eigene validationMessage-Eigenschaft. Soll Code von außen darauf zugreifen (z. B. über form.elements wie im dritten Beispiel), muss man selbst einen Getter definieren.
Nachricht ist Pflicht bei Fehlern: Wird setValidity() mit mindestens einem true-Flag, aber ohne oder mit leerer Nachricht aufgerufen, wirft der Browser einen TypeError.
Nicht formularassoziiert: Fehlt static formAssociated = true, wirft der Zugriff eine NotSupportedError-DOMException.
Bei disabled, readonly oder innerhalb eines <datalist> ist willValidate false, und validationMessage liefert einen leeren String, selbst wenn Fehler-Flags gesetzt sind.
Sicherheit: Enthält die Nachricht Benutzereingaben, im Shadow DOM mit textContent statt innerHTML ausgeben, sonst droht XSS.
Kompatibilität: ElementInternals mit Formular-Features gibt es ab Chrome/Edge 77, Firefox 98 und Safari 16.4. Für ältere Browser gibt es z. B. den Polyfill element-internals-polyfill.

Siehe auch

ElementInternals.ariaAtomic ElementInternals.ariaColSpan ElementInternals.ariaPressed ElementInternals.ariaRowSpan ElementInternals.ariaSetSize