Document.ariaNotify() — Methode · JavaScript-Referenz

Signatur

Document.prototype.ariaNotify(announcement, options)

Beschreibung

document.ariaNotify() gibt Webanwendungen eine direkte Möglichkeit, Screenreadern einen Text zum Vorlesen zu übergeben. Bisher ging das nur über ARIA-Live-Regionen (aria-live, role="status", role="alert"). Dabei schreibt man Text in ein verstecktes DOM-Element und hofft, dass die assistive Technologie die Änderung bemerkt. Das ist in der Praxis oft unzuverlässig, etwa wenn die Region zu spät eingefügt wird, derselbe Text zweimal gesetzt wird oder mehrere Regionen gleichzeitig reagieren.

Die Methode eignet sich besonders für Rückmeldungen, die zu keiner sichtbaren Änderung im DOM gehören. Typische Fälle sind Tastenkürzel wie „Fett formatiert“ in einem Editor, „In die Zwischenablage kopiert“, Fortschrittsmeldungen oder das Ergebnis einer Hintergrundaktion. Die Ansage wird in eine Warteschlange gestellt. Mit der Option priority: "high" kann eine dringende Meldung vor bereits wartende normale Meldungen gestellt werden.

Die Sprache der Ansage richtet sich nach dem lang-Attribut des Dokuments, also des <html>-Elements. Neben der Variante auf Document gibt es Element.prototype.ariaNotify(). Dort bestimmen der Kontext und die Sprache des Elements die Ansage.

Wichtig: Die Methode gibt keine Rückmeldung, ob tatsächlich etwas vorgelesen wurde. Ob und wie eine Ansage ausgegeben wird, entscheiden Browser, Barrierefreiheits-Schnittstelle und Screenreader. Wichtige Informationen sollten deshalb immer auch sichtbar dargestellt werden.

Parameter

Name	Typ	Default	Beschreibung
$announcement Pflicht	string		Der Text, den der Screenreader ansagen soll. Kurz und eindeutig formulieren.
$options	Object	{}	Optionales Objekt mit Einstellungen für die Ansage.
$options.priority	"normal" \| "high"	"normal"	`"normal"` hängt die Ansage hinten an die Warteschlange an. `"high"` stellt sie vor alle wartenden Ansagen mit normaler Priorität. Eine Ansage, die gerade läuft, wird dabei nicht zwingend unterbrochen.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Es gibt keine Bestätigung, ob die Ansage tatsächlich ausgegeben wurde.

Beispiele

Einfache Ansage mit Feature-Erkennung

// Meldung ansagen, falls die API verfügbar ist
const announce = (text, priority = 'normal') => {
  if (typeof document.ariaNotify === 'function') {
    document.ariaNotify(text, { priority });
    return true;
  }
  return false;
};

console.log(announce('Datei wurde gespeichert.'));

true (in Chromium 136+), sonst false

Rückmeldung zu Tastenkürzeln in einem Editor

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

editor.addEventListener('keydown', (event) => {
  if ((event.ctrlKey || event.metaKey) && event.key === 'b') {
    event.preventDefault();
    const isBold = editor.classList.toggle('bold');
    // Diese Änderung erzeugt keinen neuen Text im DOM, deshalb direkt ansagen
    document.ariaNotify(isBold ? 'Fett ein' : 'Fett aus');
  }
});

Dringende Fehlermeldung mit hoher Priorität

const saveDocument = async (data) => {
  try {
    const response = await fetch('/api/save', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    document.ariaNotify?.('Änderungen gespeichert.');
  } catch (error) {
    // Fehlermeldung vor wartende normale Ansagen stellen
    document.ariaNotify?.('Speichern fehlgeschlagen. Bitte erneut versuchen.', {
      priority: 'high'
    });
  }
};

saveDocument({ title: 'Entwurf' });

Rückfall auf eine ARIA-Live-Region

// Live-Region für Browser ohne ariaNotify()
const liveRegion = document.createElement('div');
liveRegion.setAttribute('aria-live', 'polite');
liveRegion.className = 'visually-hidden';
document.body.append(liveRegion);

const notify = (text) => {
  if ('ariaNotify' in document) {
    document.ariaNotify(text);
  } else {
    // Erst leeren, damit auch derselbe Text erneut angesagt wird
    liveRegion.textContent = '';
    setTimeout(() => { liveRegion.textContent = text; }, 50);
  }
};

notify('3 Suchergebnisse gefunden.');

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell und bisher nur in Chromium-Browsern verfügbar (Chrome und Edge ab Version 136). Firefox und Safari unterstützen sie derzeit nicht. Prüfe deshalb immer vorher, ob die Methode existiert, zum Beispiel mit 'ariaNotify' in document oder document.ariaNotify?.(), und sieh eine ARIA-Live-Region als Rückfall vor.
Keine Erfolgsmeldung: Die Methode gibt undefined zurück. Es gibt kein Ereignis und kein Promise, das bestätigt, dass die Ansage vorgelesen wurde.
Nicht übermäßig nutzen: Viele oder lange Ansagen überfordern Screenreader-Nutzer schnell. Verwende priority: "high" nur für wirklich dringende Meldungen wie Fehler.
Sprache: Die Aussprache hängt vom lang-Attribut ab. Fehlt es oder ist es falsch gesetzt, kann die Stimme den Text falsch aussprechen. Für Texte in einer anderen Sprache nutzt du element.ariaNotify() an einem Element mit passendem lang-Attribut.
Kein Ersatz für sichtbare Hinweise: Wichtige Informationen müssen auch sichtbar im Dokument stehen, damit sehende Nutzer sie ebenfalls wahrnehmen.
Die API ist noch in der Standardisierung. Namen und Optionen können sich ändern; frühere Entwürfe hatten zum Beispiel andere Optionen wie interrupt.

Siehe auch

Element.ariaNotify() Document Element Element.role Document.browsingTopics() Screen.unlockOrientation()