Element.ariaNotify() — Methode · JavaScript-Referenz

Signatur

Element.prototype.ariaNotify(announcement, options)

Beschreibung

ariaNotify() schickt eine Textmeldung direkt an die Barrierefreiheits-Schnittstelle des Browsers. Hilfstechnologien wie Screenreader lesen sie dann vor. Bisher brauchte man dafür eine versteckte aria-live-Region, deren Inhalt man per Skript änderte. Das funktioniert je nach Browser und Screenreader unterschiedlich zuverlässig, etwa wenn die Region erst spät ins DOM eingefügt wird oder derselbe Text zweimal kommt. ariaNotify() ersetzt diesen Umweg durch einen einzigen, klar festgelegten Aufruf.

Die Methode eignet sich für Rückmeldungen, die im sichtbaren DOM keine passende Entsprechung haben. Beispiele:

„In die Zwischenablage kopiert“
„Datei gespeichert“
„3 Treffer gefunden“
Statusmeldungen in Editoren, Spielen oder Canvas-Anwendungen

Das Element, auf dem die Methode aufgerufen wird, legt den Kontext fest. Die Sprache der Ansage kommt zum Beispiel aus dem nächsten lang-Attribut. Außerdem kann die Hilfstechnologie Ansagen aus nicht relevanten Bereichen herausfiltern. Die Methode gibt es auch auf Document als document.ariaNotify().

Mit options.priority legst du die Dringlichkeit fest. Mit "normal" (Standard) kommt die Meldung ans Ende der Warteschlange. Mit "high" wird sie vor allen wartenden Meldungen mit normaler Priorität angesagt, unterbricht aber keine Ansage, die gerade läuft. Wann und wie genau vorgelesen wird, entscheiden Browser und Screenreader. Wie laut, wie schnell und ob überhaupt, lässt sich nicht garantieren.

Parameter

Name	Typ	Default	Beschreibung
$announcement Pflicht	string		Der Text, den der Screenreader vorlesen soll. Er sollte kurz, eindeutig und ohne Markup sein.
$options	object	{}	Optionales Objekt mit Einstellungen für die Ansage.
$options.priority	"normal" \| "high"	"normal"	Dringlichkeit der Meldung. `"normal"` hängt die Meldung hinten an die Warteschlange an. `"high"` setzt sie vor alle wartenden Meldungen mit normaler Priorität.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Du erfährst also nicht, ob und wann die Meldung tatsächlich vorgelesen wurde.

Beispiele

Rückmeldung nach dem Kopieren in die Zwischenablage

const button = document.querySelector('#copy-link');

button.addEventListener('click', async () => {
  await navigator.clipboard.writeText(location.href);
  // Blinde Nutzer bekommen so eine Bestätigung, obwohl sich sichtbar nichts ändert
  button.ariaNotify('Link in die Zwischenablage kopiert');
});

Dringende Fehlermeldung mit hoher Priorität

const form = document.querySelector('#checkout');

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  try {
    const res = await fetch('/api/order', { method: 'POST', body: new FormData(form) });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    form.ariaNotify('Bestellung erfolgreich abgeschickt');
  } catch (err) {
    // Vor allen wartenden Meldungen mit normaler Priorität ansagen
    form.ariaNotify('Fehler: Die Bestellung konnte nicht gesendet werden', { priority: 'high' });
  }
});

Funktionsprüfung mit Fallback auf eine aria-live-Region

const liveRegion = Object.assign(document.createElement('div'), {
  className: 'visually-hidden'
});
liveRegion.setAttribute('aria-live', 'polite');
document.body.append(liveRegion);

const announce = (el, text, priority = 'normal') => {
  if ('ariaNotify' in Element.prototype) {
    el.ariaNotify(text, { priority });
    return;
  }
  // Fallback: Inhalt leeren und neu setzen, damit die Änderung erkannt wird
  liveRegion.setAttribute('aria-live', priority === 'high' ? 'assertive' : 'polite');
  liveRegion.textContent = '';
  setTimeout(() => { liveRegion.textContent = text; }, 50);
};

const results = document.querySelector('#results');
announce(results, `${results.children.length} Treffer gefunden`);

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist experimentell. Stand heute gibt es sie in Chromium-Browsern ab Version 136 (Chrome, Edge). Firefox und Safari unterstützen sie noch nicht. Prüfe deshalb immer vorher mit 'ariaNotify' in Element.prototype und sieh eine aria-live-Region als Fallback vor.
Keine Rückmeldung: Die Methode gibt nichts zurück und wirft auch bei fehlendem Screenreader keinen Fehler. Ob die Meldung angekommen ist, lässt sich nicht prüfen.
Kein Ersatz für semantisches HTML: Wichtige Informationen sollten zusätzlich sichtbar im DOM stehen, etwa als Fehlertext neben dem Feld. Eine Ansage ist flüchtig und lässt sich nicht noch einmal anhören.
Nicht übertreiben: Viele oder schnell aufeinanderfolgende Meldungen, besonders mit priority: 'high', überfordern Screenreader-Nutzer. Fasse Meldungen zusammen und bremse sie gegebenenfalls, zum Beispiel bei Live-Suchergebnissen.
Sprache: Der Text wird in der Sprache vorgelesen, die das lang-Attribut des Elements oder eines Vorfahren angibt. Setze es korrekt.
Ältere Entwürfe der Spezifikation hatten andere Optionen, etwa interrupt und type. Die sind überholt. Verlass dich nur auf priority.

Siehe auch

Document.ariaNotify() Element Element.setAttribute() Element.ariaLive Element.role FileSystemEntry.moveTo() Selection.setPosition()