ElementInternals.ariaAtomic — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaAtomic

Beschreibung

Die Eigenschaft ariaAtomic des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-atomic. Sie gibt an, ob unterstützende Technologien wie Screenreader bei einer Änderung in einer Live-Region (aria-live) den gesamten Bereich ("true") oder nur die geänderten Knoten ("false") ansagen sollen.

Anders als element.ariaAtomic bzw. das Attribut aria-atomic setzt der Wert über ElementInternals die Standard-Semantik eines autonomen Custom Elements, und zwar ohne ein sichtbares Attribut im DOM anzulegen. Setzt die Person, die das Element verwendet, selbst ein aria-atomic-Attribut, hat dieses Vorrang. So kann eine Komponente sinnvolle Standardwerte mitbringen, die sich trotzdem überschreiben lassen.

Typische Einsatzfälle sind Web Components für Statusmeldungen, Toasts, Uhren, Zähler oder Warenkorb-Summen. Dort ergibt ein Teil der Ansage ohne den Rest keinen Sinn (z. B. „3 Artikel, 42,90 €“).

Rückgabewert

Typ

string | null

Beschreibung

Einer der Strings "true" oder "false", oder null, wenn kein Wert gesetzt ist. Beim Setzen wird jeder Wert in einen String umgewandelt. Mit null wird der Standardwert entfernt.

Beispiele

Standard-Semantik für eine Status-Komponente festlegen

class StatusMessage extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Standard-ARIA-Semantik festlegen, ohne Attribute ins DOM zu schreiben
    this.#internals.role = 'status';
    this.#internals.ariaLive = 'polite';
    this.#internals.ariaAtomic = 'true';
  }
  set message(text) {
    this.textContent = text;
  }
  get atomic() {
    return this.#internals.ariaAtomic;
  }
}
customElements.define('status-message', StatusMessage);

const el = document.createElement('status-message');
document.body.append(el);
el.message = 'Gespeichert um 14:32 Uhr';
console.log(el.atomic);
console.log(el.hasAttribute('aria-atomic'));

true false

Warenkorb-Zusammenfassung komplett ansagen lassen

class CartSummary extends HTMLElement {
  #internals = this.attachInternals();
  connectedCallback() {
    this.#internals.role = 'region';
    this.#internals.ariaLive = 'polite';
    // Gesamten Inhalt vorlesen, nicht nur die geänderte Zahl
    this.#internals.ariaAtomic = 'true';
    this.update(0, 0);
  }
  update(count, total) {
    const price = total.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' });
    this.innerHTML = `<span>${count}</span> Artikel – <span>${price}</span>`;
  }
}
customElements.define('cart-summary', CartSummary);

const cart = document.createElement('cart-summary');
document.body.append(cart);
cart.update(3, 42.9); // Screenreader: „3 Artikel – 42,90 €“

Standardwert durch Attribut überschreiben und zurücksetzen

class LiveLog extends HTMLElement {
  internals = this.attachInternals();
  constructor() {
    super();
    this.internals.role = 'log';
    this.internals.ariaAtomic = 'false'; // nur neue Einträge ansagen
  }
}
customElements.define('live-log', LiveLog);

const log = document.createElement('live-log');
// Das Attribut der Seite hat Vorrang vor dem Wert aus ElementInternals
log.setAttribute('aria-atomic', 'true');
console.log(log.internals.ariaAtomic); // Wert aus ElementInternals bleibt unverändert

log.internals.ariaAtomic = null; // Standardwert entfernen
console.log(log.internals.ariaAtomic);

false null

// Wichtig · Fallstricke

Nur für autonome Custom Elements: attachInternals() funktioniert nur bei Klassen, die von HTMLElement erben. Bei eingebauten Elementen wie <div> und bei erweiterten eingebauten Elementen (is="…") wird ein NotSupportedError ausgelöst. Außerdem darf attachInternals() pro Element nur einmal aufgerufen werden.
Keine Spiegelung ins DOM: Der Wert erscheint nicht als Attribut. Deshalb greifen CSS-Selektoren wie [aria-atomic="true"] nicht, und getAttribute() liefert null.
Vorrang: Ein explizit gesetztes aria-atomic-Attribut oder element.ariaAtomic überschreibt den Wert aus ElementInternals. Die Eigenschaft von ElementInternals selbst ändert sich dadurch nicht.
Nur mit Live-Region sinnvoll: Ohne aria-live oder eine Live-Rolle (status, log, alert, timer) hat ariaAtomic keine praktische Wirkung. Bei role="status" und role="alert" ist aria-atomic implizit schon true.
Nur Strings: Setze die Strings "true" oder "false", keine Booleans. Ein Boolean wird zwar in einen String umgewandelt, das ist aber schlechter Stil.
Browser-Unterstützung: ARIA-Reflexion auf ElementInternals gibt es in Chromium seit Version 81, in Safari seit 16.4 und in Firefox seit 119. Für ältere Browser kann man per Feature-Erkennung ('ariaAtomic' in ElementInternals.prototype) prüfen und als Ersatz das Attribut setzen.
Wie sich Live-Regionen verhalten, hängt stark vom Screenreader ab. Teste mit NVDA, JAWS und VoiceOver.

Siehe auch

ElementInternals.ariaModal ElementInternals.ariaSort ElementInternals.ariaValueMin ElementInternals.ariaBusy ElementInternals.ariaHasPopup