ElementInternals.willValidate — Eigenschaft · JavaScript-Referenz

Signatur

get ElementInternals.willValidate

Beschreibung

Die schreibgeschützte Eigenschaft willValidate der Schnittstelle ElementInternals zeigt an, ob ein formularassoziiertes Custom Element gerade ein Kandidat für die Einschränkungsvalidierung ist. Sie entspricht der gleichnamigen Eigenschaft nativer Formularelemente wie HTMLInputElement.willValidate.

Ein Element nimmt nicht an der Validierung teil (false), wenn es davon ausgeschlossen ist. Bei formularassoziierten Custom Elements ist das der Fall, wenn:

das Element deaktiviert ist, entweder über das Attribut disabled oder über ein deaktiviertes übergeordnetes <fieldset>,
das Element das Attribut readonly trägt,
das Element in einem <datalist> liegt.

Die Eigenschaft ist nützlich, um in eigenen Komponenten zu entscheiden, ob sich Validierungslogik, Fehlermeldungen oder Aufrufe von setValidity() und reportValidity() überhaupt lohnen. Solange willValidate den Wert false hat, liefert checkValidity() immer true, und das Formular wird trotz gesetzter Fehlerzustände abgeschickt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element an der Einschränkungsvalidierung teilnimmt, sonst false.

Beispiele

Formularassoziiertes Element anlegen und willValidate abfragen

class RatingInput extends HTMLElement {
  static formAssociated = true;

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

  get willValidate() {
    return this.internals.willValidate;
  }
}
customElements.define('rating-input', RatingInput);

const form = document.createElement('form');
const rating = document.createElement('rating-input');
form.append(rating);
document.body.append(form);

console.log(rating.willValidate);

true

Ausschluss durch disabled und readonly

class TagInput extends HTMLElement {
  static formAssociated = true;
  constructor() {
    super();
    this.internals = this.attachInternals();
  }
}
customElements.define('tag-input', TagInput);

const el = document.createElement('tag-input');
document.body.append(el);

console.log(el.internals.willValidate); // true

el.setAttribute('disabled', '');
console.log(el.internals.willValidate); // false

el.removeAttribute('disabled');
el.setAttribute('readonly', '');
console.log(el.internals.willValidate); // false

true false false

Validierung nur ausführen, wenn sie relevant ist

class EmailField extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
    const shadow = this.attachShadow({ mode: 'open' });
    this.input = document.createElement('input');
    this.input.type = 'email';
    shadow.append(this.input);
    this.input.addEventListener('input', () => this.#update());
  }

  #update() {
    const value = this.input.value;
    this.internals.setFormValue(value);

    // Ohne Teilnahme an der Validierung keine Fehlermeldung zeigen
    if (!this.internals.willValidate) {
      this.internals.setValidity({});
      return;
    }

    if (!value.includes('@')) {
      this.internals.setValidity(
        { typeMismatch: true },
        'Bitte eine gültige E-Mail-Adresse eingeben.',
        this.input
      );
    } else {
      this.internals.setValidity({});
    }
  }
}
customElements.define('email-field', EmailField);

// Wichtig · Fallstricke

Nur für formularassoziierte Elemente: Fehlt in der Klasse static formAssociated = true, wirft der Zugriff auf willValidate eine DOMException vom Typ NotSupportedError.
Nicht automatisch öffentlich: ElementInternals ist an das Element gebunden, wird aber nicht von außen bereitgestellt. Wenn Formular-Code element.willValidate wie bei nativen Feldern abfragen soll, musst du einen eigenen Getter anlegen (siehe Beispiel 1).
Ein Formular ist nicht nötig: willValidate kann auch true sein, wenn das Element nicht in einem <form> liegt.
Fehlerzustände bleiben erhalten: Ein mit setValidity() gesetzter Fehler wird nicht gelöscht, wenn das Element ausgeschlossen wird (zum Beispiel durch disabled). Er wird nur ignoriert. Mit formDisabledCallback() kannst du auf solche Zustandswechsel reagieren.
Browserunterstützung: ElementInternals und die Formular-Funktionen sind erst seit Safari 16.4 überall verfügbar. Für ältere Browser gibt es Polyfills, etwa element-internals-polyfill.

Siehe auch

ElementInternals.validity ElementInternals.ariaInvalid ElementInternals.ariaLive ElementInternals.ariaHidden ElementInternals.ariaLabel