ElementInternals.ariaLive — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaLive

Beschreibung

Die Eigenschaft ariaLive des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-live. Sie kennzeichnet ein Element als Live-Region: Ändert sich der Inhalt, sagen assistive Technologien wie Screenreader die Änderung an, ohne dass der Fokus dorthin wandern muss. Der Wert legt fest, wie dringlich die Ansage ist.

Anders als Element.ariaLive setzt die Eigenschaft auf ElementInternals kein sichtbares Attribut im DOM. Sie legt die Standard-Semantik eines Custom Elements fest. Setzt der Nutzer des Elements selbst aria-live im Markup, hat dieses Attribut Vorrang. So kann eine Komponente wie <toast-message> oder <status-bar> sinnvolle Vorgaben mitbringen, ohne das Light DOM mit Attributen zu füllen.

Erlaubte Werte sind:

"off": keine Ansage (Standard, außer bei bestimmten Rollen)
"polite": Ansage, sobald der Nutzer gerade nichts anderes tut; für Statusmeldungen
"assertive": sofortige Ansage, die laufende Ausgaben unterbricht; nur für dringende Meldungen

Die Eigenschaft ist lesbar und schreibbar. Setzt man null, wird die Standard-Semantik wieder entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Einer der Werte "off", "polite" oder "assertive". null, wenn kein Wert gesetzt wurde.

Beispiele

Statusanzeige als höfliche Live-Region

class StatusBar extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Standard-Semantik: Statusrolle, höfliche Ansage
    this.#internals.role = 'status';
    this.#internals.ariaLive = 'polite';
  }

  set message(text) {
    this.textContent = text;
  }
}

customElements.define('status-bar', StatusBar);

const bar = document.createElement('status-bar');
document.body.append(bar);
bar.message = 'Änderungen gespeichert.';
console.log(bar.hasAttribute('aria-live'));

false

Dringlichkeit abhängig vom Meldungstyp umschalten

class ToastMessage extends HTMLElement {
  static observedAttributes = ['type'];
  #internals = this.attachInternals();

  attributeChangedCallback(name, oldValue, newValue) {
    if (name === 'type') {
      // Fehler sofort ansagen, alles andere höflich
      this.#internals.ariaLive = newValue === 'error' ? 'assertive' : 'polite';
      this.#internals.role = newValue === 'error' ? 'alert' : 'status';
    }
  }

  get liveMode() {
    return this.#internals.ariaLive;
  }
}

customElements.define('toast-message', ToastMessage);

const toast = document.createElement('toast-message');
toast.setAttribute('type', 'error');
console.log(toast.liveMode);
toast.setAttribute('type', 'info');
console.log(toast.liveMode);

assertive polite

Feature-Erkennung und Zurücksetzen

class LiveCounter extends HTMLElement {
  #internals = this.attachInternals();

  connectedCallback() {
    if ('ariaLive' in this.#internals) {
      this.#internals.ariaLive = 'polite';
    } else {
      // Fallback für ältere Browser: sichtbares Attribut setzen
      if (!this.hasAttribute('aria-live')) this.setAttribute('aria-live', 'polite');
    }
  }

  mute() {
    // Standard-Semantik entfernen
    if ('ariaLive' in this.#internals) this.#internals.ariaLive = null;
  }
}

customElements.define('live-counter', LiveCounter);

// Wichtig · Fallstricke

Das Attribut hat Vorrang: Ein vom Nutzer gesetztes aria-live am Host-Element überschreibt den Wert aus ElementInternals. Der Wert der Eigenschaft ändert sich dabei nicht, nur die Semantik, die im Barrierefreiheitsbaum ankommt.
Kein Attribut im DOM: Die Semantik ist in den DevTools nur im Accessibility-Bereich zu sehen, nicht bei den Attributen. CSS-Selektoren wie [aria-live] greifen deshalb nicht.
Die Live-Region muss früh existieren: Viele Screenreader sagen Änderungen nur an, wenn die Live-Region schon vor der Inhaltsänderung im Barrierefreiheitsbaum stand. Setzen Sie ariaLive daher im Konstruktor oder in connectedCallback, nicht erst direkt vor dem Aktualisieren des Textes.
"assertive" sparsam einsetzen: Der Wert unterbricht laufende Ansagen und kann Nutzer stark stören. Die Rollen alert und status bringen bereits implizit assertive bzw. polite mit.
Keine Prüfung des Werts: Ungültige Zeichenketten werden ohne Fehler gespeichert, von assistiven Technologien aber ignoriert.
attachInternals() funktioniert nur bei autonomen Custom Elements und darf pro Element nur einmal aufgerufen werden. Sonst wird eine NotSupportedError-DOMException geworfen.
Browser-Unterstützung: ARIA-Reflexion auf ElementInternals gibt es in Chromium ab Version 81, in Safari ab 16.4 und in Firefox ab 119. Für ältere Browser ist eine Feature-Erkennung mit 'ariaLive' in internals sinnvoll.

Siehe auch

ElementInternals.ariaLevel ElementInternals.ariaLabel ElementInternals.ariaBusy ElementInternals.ariaHidden ElementInternals.ariaSort