Signatur
Beschreibung
Die Eigenschaft ariaRelevant des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-relevant. Sie legt fest, welche Art von Änderung innerhalb einer Live-Region (aria-live bzw. Rollen wie log, status, alert) Hilfstechnologien wie Screenreader melden sollen.
Der Wert ist eine durch Leerzeichen getrennte Liste folgender Token:
additions: Neu eingefügte Knoten werden gemeldet.removals: Entfernte Knoten werden gemeldet.text: Geänderter Textinhalt oder Text-Alternativen werden gemeldet.all: Kurzform füradditions removals text.
Ohne Angabe gilt implizit additions text.
Anders als Element.ariaRelevant setzt die Variante auf ElementInternals kein sichtbares Attribut im DOM. Sie legt nur die Standard-Semantik eines autonomen Custom Elements fest. Setzt jemand, der die Komponente verwendet, selbst ein aria-relevant-Attribut am Host-Element, hat dieses Vorrang. So kann eine Komponente sinnvolle Vorgaben für die Barrierefreiheit mitbringen, ohne das Markup der Nutzer zu verändern.
Man erhält das ElementInternals-Objekt über this.attachInternals() im Konstruktor des Custom Elements. Einsetzen sollte man die Eigenschaft vor allem bei Komponenten, die dynamische Inhalte anzeigen, etwa Chat-Verläufe, Protokolle, Benachrichtigungslisten oder Ticker.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $wert | string | null | null (implizit "additions text") | Beim Setzen: eine durch Leerzeichen getrennte Kombination aus additions, removals, text oder all. Mit null wird die Standard-Semantik entfernt. |
Rückgabewert
"additions text", oder null, wenn nichts gesetzt wurde. Der Browser gibt den String unverändert zurück und prüft ihn nicht.Beispiele
Protokoll-Komponente mit Standard-Semantik
class LogFeed extends HTMLElement {
#internals;
constructor() {
super();
this.#internals = this.attachInternals();
// Standard-Semantik festlegen, ohne Attribute zu setzen
this.#internals.role = 'log';
this.#internals.ariaLive = 'polite';
this.#internals.ariaRelevant = 'additions';
}
add(message) {
const entry = document.createElement('p');
entry.textContent = message;
this.append(entry); // Screenreader meldet nur neue Einträge
}
}
customElements.define('log-feed', LogFeed);
const feed = document.createElement('log-feed');
document.body.append(feed);
feed.add('Build gestartet');
console.log(feed.hasAttribute('aria-relevant'));Auch entfernte Einträge melden (z. B. Warteschlange)
class QueueList extends HTMLElement {
constructor() {
super();
this.internals = this.attachInternals();
this.internals.ariaLive = 'polite';
// Hinzufügen UND Entfernen ist hier relevant
this.internals.ariaRelevant = 'additions removals';
}
}
customElements.define('queue-list', QueueList);
const queue = new QueueList();
console.log(queue.internals.ariaRelevant);Wert zurücksetzen und Vorrang des Attributs
class StatusTicker extends HTMLElement {
constructor() {
super();
this.internals = this.attachInternals();
this.internals.ariaLive = 'polite';
this.internals.ariaRelevant = 'all';
}
}
customElements.define('status-ticker', StatusTicker);
const ticker = new StatusTicker();
// Das Attribut des Nutzers überschreibt die Standard-Semantik
ticker.setAttribute('aria-relevant', 'text');
// Standard-Semantik entfernen: danach gilt implizit "additions text"
ticker.internals.ariaRelevant = null;
console.log(ticker.internals.ariaRelevant);// Wichtig · Fallstricke
- Nur mit einer Live-Region wirksam:
ariaRelevantbewirkt allein nichts. Das Element braucht zusätzlichariaLiveoder eine Live-Rolle wielogoderstatus. - Keine Prüfung des Werts: Ungültige Token wie
\"added\"übernimmt der Browser ohne Fehler, Hilfstechnologien ignorieren sie aber. - Sparsam einsetzen:
removalsundallführen oft zu vielen, verwirrenden Ansagen. Die ARIA-Spezifikation rät davon ab, sie ohne guten Grund zu verwenden. - Wie Screenreader
aria-relevantumsetzen, ist sehr unterschiedlich. Besondersremovalswird oft nicht angesagt. Mit echten Screenreadern testen. - Browser-Unterstützung:
attachInternals()funktioniert nur bei autonomen Custom Elements. Die Unterstützung der ARIA-Eigenschaften aufElementInternalsist in Chromium und Safari vorhanden, in Firefox teils eingeschränkt. Bei Bedarf als Rückfallebene das Attribut direkt setzen, z. B. mitif (!('ariaRelevant' in ElementInternals.prototype)) this.setAttribute('aria-relevant', 'additions').