ElementInternals.ariaInvalid — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaInvalid

Beschreibung

Die Eigenschaft ariaInvalid der Schnittstelle ElementInternals entspricht dem ARIA-Zustand aria-invalid. Sie teilt assistiven Technologien wie Screenreadern mit, ob der eingegebene Wert eines Formularelements als ungültig gilt. Über ElementInternals legt ein autonomes Custom Element diesen Wert intern fest. Dadurch muss es kein Attribut auf sich selbst setzen, das Nutzer der Komponente sehen oder überschreiben könnten.

Mögliche Werte sind die Zeichenketten "true", "false", "grammar" (Grammatikfehler) und "spelling" (Rechtschreibfehler). Mit null entfernen Sie den Standardwert. Der Browser wertet ausschließlich Zeichenketten aus. Ein boolesches true wird zwar in "true" umgewandelt, sollte aber aus Gründen der Lesbarkeit nicht verwendet werden.

Wofür braucht man das? Vor allem bei formularassoziierten Custom Elements (static formAssociated = true). Nach der eigenen Validierung, etwa mit internals.setValidity(), synchronisieren Sie den ARIA-Zustand, damit Screenreader den Fehler ansagen. Setzt der Autor der Seite selbst ein aria-invalid-Attribut auf das Element, hat dieses Vorrang vor dem internen Wert. Der Wert aus ElementInternals ist also nur ein Standardwert.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"`, `"false"`, `"grammar"`, `"spelling"` oder `null`, um den Standardwert zu entfernen.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell intern gesetzte Wert von aria-invalid oder null, wenn kein Wert gesetzt ist. Ein Attribut am Host-Element wird dabei nicht ausgelesen.

Beispiele

Standardwert im Konstruktor setzen

class FancyInput extends HTMLElement {
  static formAssociated = true;

  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'textbox';
    // Anfangszustand: gültig
    this.internals.ariaInvalid = 'false';
  }
}

customElements.define('fancy-input', FancyInput);

const el = document.createElement('fancy-input');
console.log(el.internals.ariaInvalid);
console.log(el.getAttribute('aria-invalid'));

false null

ARIA-Zustand mit der Validierung synchronisieren

class EmailField extends HTMLElement {
  static formAssociated = true;
  #internals;
  #input;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    const root = this.attachShadow({ mode: 'open' });
    root.innerHTML = '<input type="email">';
    this.#input = root.querySelector('input');
    this.#input.addEventListener('input', () => this.#validate());
  }

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

    if (value && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) {
      this.#internals.setValidity({ typeMismatch: true }, 'Bitte eine gültige E-Mail-Adresse eingeben.', this.#input);
      this.#internals.ariaInvalid = 'true';
    } else {
      this.#internals.setValidity({});
      this.#internals.ariaInvalid = 'false';
    }
    console.log('aria-invalid:', this.#internals.ariaInvalid);
  }
}

customElements.define('email-field', EmailField);

aria-invalid: true // nach Eingabe von "abc" aria-invalid: false // nach Eingabe von "a@b.de"

Rechtschreibfehler melden und Wert entfernen

class SpellBox extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
  }

  markSpelling(hasError) {
    // Bei Fehler "spelling", sonst den Standardwert entfernen
    this.internals.ariaInvalid = hasError ? 'spelling' : null;
  }
}

customElements.define('spell-box', SpellBox);

const box = new SpellBox();
box.markSpelling(true);
console.log(box.internals.ariaInvalid);
box.markSpelling(false);
console.log(box.internals.ariaInvalid);

spelling null

// Wichtig · Fallstricke

Nur ein Standardwert: Ein explizites aria-invalid-Attribut am Host-Element überschreibt den Wert aus ElementInternals. Umgekehrt gilt das nicht.
Nur für autonome Custom Elements: attachInternals() wirft bei eingebauten Elementen und bei angepassten eingebauten Elementen (is="…") einen NotSupportedError. Pro Element ist nur ein einziger Aufruf erlaubt.
Kein automatischer Abgleich: setValidity() setzt ariaInvalid nicht mit. Sie müssen beides selbst synchron halten.
Nicht zu früh als ungültig markieren: Setzen Sie "true" nicht schon beim ersten Laden eines leeren Pflichtfelds. Sonst sagt der Screenreader einen Fehler an, bevor der Nutzer überhaupt etwas eingegeben hat.
Unbekannte Werte: Nicht erkannte Zeichenketten wie "yes" werden gespeichert, von assistiven Technologien aber als "true" interpretiert. Ein leerer String zählt dagegen als "false".
Kompatibilität: Firefox unterstützt die ARIA-Eigenschaften von ElementInternals erst ab Version 119. Für ältere Browser prüfen Sie mit 'ariaInvalid' in ElementInternals.prototype und setzen als Rückfalllösung das Attribut am Element selbst.

Siehe auch

ElementInternals.ariaCurrent ElementInternals.ariaDisabled ElementInternals.ariaLevel ElementInternals.ariaModal ElementInternals.ariaAtomic