Element.ariaAtomic — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaAtomic

Beschreibung

Die Eigenschaft ariaAtomic der Schnittstelle Element gehört zu den ARIA-Reflexionen (ARIAMixin). Sie liest und schreibt das HTML-Attribut aria-atomic direkt als String. Ein Umweg über getAttribute() und setAttribute() ist also nicht nötig.

Wirkung hat aria-atomic nur in Live-Bereichen, also in Elementen mit aria-live oder mit einer Rolle wie status, alert oder log. Die Werte im Überblick:

"true": Unterstützende Technologien lesen bei jeder Änderung den gesamten Bereich vor.
"false" (Standard): Vorgelesen werden nur die geänderten oder neu eingefügten Knoten.

"true" lohnt sich immer dann, wenn eine Teiländerung ohne Kontext unverständlich wäre. Beispiele sind ein Warenkorb-Zähler („3 Artikel im Warenkorb“), eine Uhrzeit oder eine Statusmeldung, die aus mehreren Textteilen besteht. Bei fortlaufenden Protokollen wie Chat-Verläufen bleibt man besser bei "false". Sonst wird bei jeder neuen Nachricht der ganze Verlauf erneut vorgelesen.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-atomic ("true" oder "false") oder null, wenn das Attribut nicht gesetzt ist. Wer null zuweist, entfernt das Attribut.

Beispiele

Wert lesen und setzen

// <div id="cart-status" role="status" aria-atomic="false"></div>
const status = document.querySelector('#cart-status');

console.log(status.ariaAtomic);

// Den gesamten Bereich bei jeder Änderung vorlesen lassen
status.ariaAtomic = 'true';
console.log(status.getAttribute('aria-atomic'));

false true

Warenkorb-Zähler als atomarer Live-Bereich

const createCartStatus = () => {
  const region = document.createElement('p');
  region.setAttribute('aria-live', 'polite');
  region.ariaAtomic = 'true';
  region.innerHTML = '<span class="count">0</span> Artikel im Warenkorb';
  document.body.append(region);
  return region;
};

const cartStatus = createCartStatus();

const updateCart = (count) => {
  // Geändert wird nur die Zahl – vorgelesen wird trotzdem der ganze Satz
  cartStatus.querySelector('.count').textContent = String(count);
};

updateCart(3);
// Screenreader liest: "3 Artikel im Warenkorb"

Attribut entfernen und Unterstützung prüfen

const clock = document.querySelector('#clock');

if ('ariaAtomic' in Element.prototype) {
  clock.ariaAtomic = null; // entfernt aria-atomic
  console.log(clock.hasAttribute('aria-atomic'));
} else {
  // Rückfall für ältere Browser
  clock.removeAttribute('aria-atomic');
}

false

// Wichtig · Fallstricke

Werte sind Strings, keine Booleans: Wer el.ariaAtomic = true schreibt, bekommt den String "true". Das funktioniert, false wird aber ebenfalls zum String "false". Zum Entfernen des Attributs muss man null zuweisen.
Nur in Live-Bereichen wirksam: Ohne aria-live oder eine Live-Rolle hat aria-atomic keine Wirkung. Bei den Rollen alert und status ist aria-atomic implizit true.
Live-Bereich vorher anlegen: Manche Screenreader melden Inhalte nur, wenn der Live-Bereich schon im DOM stand, bevor sich der Inhalt geändert hat.
Kompatibilität: Firefox unterstützt die ARIA-Reflexionen erst ab Version 119. Für ältere Browser ist setAttribute('aria-atomic', 'true') der sichere Rückfall.
Die Eigenschaft prüft den Wert nicht. Ungültige Strings werden unverändert ins Attribut geschrieben und von unterstützenden Technologien ignoriert.

Siehe auch

Element.role Element Element.ariaAutoComplete Element.ariaModal Element.ariaSort