ElementInternals.ariaBusy — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaBusy

Beschreibung

Die Eigenschaft ariaBusy des ElementInternals-Interfaces entspricht dem ARIA-Zustand aria-busy. Sie zeigt unterstützenden Technologien wie Screenreadern, dass ein Element oder sein Inhalt gerade geändert oder nachgeladen wird. Solange der Wert "true" ist, können Screenreader mit dem Vorlesen von Änderungen warten, bis die Aktualisierung fertig ist.

Anders als Element.ariaBusy ändert die Eigenschaft auf ElementInternals kein sichtbares Attribut im DOM. Sie legt stattdessen die Standard-Semantik eines Custom Elements fest. So kann ein Web Component seinen Ladezustand selbst an den Barrierefreiheitsbaum melden, ohne dem Host-Element Attribute hinzuzufügen, die der Nutzer der Komponente vielleicht nicht erwartet. Setzt der Autor der Seite selbst ein aria-busy-Attribut am Host, hat dieses Vorrang.

Typische Einsatzfälle:

Datentabellen, die Daten nachladen
Feeds mit endlosem Scrollen
Diagramme und Live-Bereiche, die in mehreren Schritten neu aufgebaut werden

Du erhältst das ElementInternals-Objekt über this.attachInternals() im Konstruktor des Custom Elements.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"` (Element wird gerade aktualisiert), `"false"` (keine laufende Aktualisierung) oder `null` (Standard-Semantik entfernen).

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Wert als Zeichenkette, also "true" oder "false". Wenn nichts gesetzt wurde, kommt null zurück.

Beispiele

Ladezustand eines Custom Elements melden

class DataList extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'list';
  }

  async connectedCallback() {
    // Screenreader mitteilen: Inhalt wird gerade aufgebaut
    this.#internals.ariaBusy = 'true';
    try {
      const res = await fetch('https://jsonplaceholder.typicode.com/users');
      const users = await res.json();
      this.innerHTML = users
        .map((u) => `<div role="listitem">${u.name}</div>`)
        .join('');
    } finally {
      // Aktualisierung abgeschlossen
      this.#internals.ariaBusy = 'false';
    }
  }
}

customElements.define('data-list', DataList);

Wert auslesen und zurücksetzen

class BusyBox extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
  }
}
customElements.define('busy-box', BusyBox);

const box = document.createElement('busy-box');
document.body.append(box);

console.log(box.internals.ariaBusy);          // Anfangswert
box.internals.ariaBusy = 'true';
console.log(box.internals.ariaBusy);
console.log(box.hasAttribute('aria-busy'));   // kein DOM-Attribut!
box.internals.ariaBusy = null;                // Standard-Semantik entfernen
console.log(box.internals.ariaBusy);

null "true" false null

Busy-Zustand zusätzlich per CSS stylen (Custom State)

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

  setBusy(isBusy) {
    this.#internals.ariaBusy = String(isBusy);
    // ariaBusy erzeugt kein Attribut, daher Custom State für CSS
    if (isBusy) this.#internals.states.add('busy');
    else this.#internals.states.delete('busy');
  }
}
customElements.define('live-chart', LiveChart);

// CSS: live-chart:state(busy) { opacity: 0.5; }
const chart = document.querySelector('live-chart');
chart?.setBusy(true);
setTimeout(() => chart?.setBusy(false), 1000);

// Wichtig · Fallstricke

Kein DOM-Attribut: Wenn du internals.ariaBusy setzt, entsteht kein aria-busy-Attribut. CSS-Selektoren wie [aria-busy="true"] treffen deshalb nicht zu. Verwende dafür CustomStateSet (:state(...)).
Vorrang des Autors: Setzt die einbindende Seite ein aria-busy-Attribut direkt am Host, überschreibt es den Wert aus ElementInternals.
Zeichenkette statt Boolean: Der Wert ist ein String. Schreibst du internals.ariaBusy = false, wird daraus "false". Zum Entfernen musst du null setzen.
Richtiges Zurücksetzen: Setze den Wert nach der Aktualisierung zuverlässig wieder auf "false", am besten in einem finally-Block. Sonst ignorieren Screenreader weitere Änderungen möglicherweise dauerhaft.
attachInternals() lässt sich pro Element nur einmal aufrufen und funktioniert nur bei autonomen Custom Elements, nicht bei erweiterten eingebauten Elementen (is="...").
Kompatibilität: Die ARIA-Eigenschaften auf ElementInternals gibt es in Chromium seit Version 83, in Safari seit 16.4 und in Firefox seit 119. Ältere Browser ignorieren die Eigenschaft; prüfe das bei Bedarf mit 'ariaBusy' in ElementInternals.prototype.

Siehe auch

ElementInternals.ariaColSpan ElementInternals.ariaLive ElementInternals.ariaSort ElementInternals.ariaLabel ElementInternals.ariaLevel