Signatur
Beschreibung
Die Eigenschaft ariaRelevant ist eine gespiegelte Eigenschaft (Reflection) des HTML-Attributs aria-relevant. Sie gibt an, welche Arten von Änderungen im Zugänglichkeitsbaum einer Live-Region (Elemente mit aria-live oder Rollen wie log, status, alert) von assistiven Technologien angesagt werden sollen.
Der Wert ist eine durch Leerzeichen getrennte Liste von Schlüsselwörtern:
additions– neu eingefügte Knoten werden gemeldet.removals– entfernte Knoten werden gemeldet.text– Textänderungen (auch Änderungen an Textalternativen) werden gemeldet.all– Kurzform füradditions removals text.
Ist das Attribut nicht gesetzt, gilt implizit additions text; die Eigenschaft liefert dann jedoch null. Das Setzen der Eigenschaft schreibt das Attribut direkt ins DOM – el.ariaRelevant = "all" ist gleichwertig zu el.setAttribute("aria-relevant", "all").
Nützlich ist die Eigenschaft vor allem bei dynamischen Oberflächen wie Chat-Verläufen, Benachrichtigungslisten oder Warenkörben, bei denen auch das Entfernen von Einträgen für Nutzer relevant ist. In den meisten Fällen reicht der Standardwert; removals und all sollten sparsam eingesetzt werden, weil sie schnell zu übermäßigen Ansagen führen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | null | null (implizit: "additions text") | Beim Setzen: durch Leerzeichen getrennte Liste aus additions, removals, text oder all. null entfernt das Attribut. |
Rückgabewert
aria-relevant-Attributs als String oder null, wenn das Attribut nicht gesetzt ist.Beispiele
Wert lesen und setzen
// <div id="log" role="log" aria-live="polite" aria-relevant="additions"></div>
const log = document.getElementById('log');
console.log(log.ariaRelevant);
// Auch Entfernungen melden lassen
log.ariaRelevant = 'additions removals';
console.log(log.getAttribute('aria-relevant'));Warenkorb als Live-Region, die auch Entfernungen ansagt
const cart = document.createElement('ul');
cart.setAttribute('aria-live', 'polite');
cart.ariaRelevant = 'additions removals';
document.body.append(cart);
const addItem = (name) => {
const li = document.createElement('li');
li.textContent = name;
cart.append(li);
return li;
};
const item = addItem('Kaffeebohnen 500 g');
// Screenreader sagt auch das Entfernen an
setTimeout(() => item.remove(), 2000);
console.log(cart.ariaRelevant);Feature-Erkennung mit Fallback auf setAttribute
const setRelevant = (el, value) => {
if ('ariaRelevant' in Element.prototype) {
el.ariaRelevant = value;
} else {
// z. B. Firefox
if (value === null) el.removeAttribute('aria-relevant');
else el.setAttribute('aria-relevant', value);
}
};
const status = document.querySelector('[role="status"]') ?? document.body;
setRelevant(status, 'text');
console.log(status.getAttribute('aria-relevant'));// Wichtig · Fallstricke
- Kompatibilität:
ariaRelevantwird in Chromium-Browsern und Safari unterstützt, in Firefox jedoch nicht und wurde aus der ARIA-Reflection-Spezifikation (ARIAMixin) entfernt. Für plattformübergreifenden Code bessersetAttribute('aria-relevant', …)verwenden oder auf das Vorhandensein der Eigenschaft prüfen. - Die Eigenschaft liefert
null, wenn das Attribut fehlt – nicht den impliziten Standardwert"additions text". - Die Werte werden nicht geprüft: Ungültige Schlüsselwörter werden ohne Fehlermeldung übernommen und von assistiven Technologien ignoriert.
aria-relevantwirkt nur innerhalb einer Live-Region (aria-liveoder entsprechende Rolle). Die Unterstützung durch Screenreader ist uneinheitlich, besonders beiremovals.allbzw.removalskönnen zu sehr vielen Ansagen führen – für wichtige Entfernungen ist oft eine eigene Statusmeldung verständlicher.