Element.ariaRoleDescription — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaRoleDescription

Beschreibung

Die Eigenschaft ariaRoleDescription gehört zur ARIA-Reflexion der Element-Schnittstelle. Sie liest und schreibt direkt das HTML-Attribut aria-roledescription. el.ariaRoleDescription = "Folie" bewirkt also dasselbe wie el.setAttribute("aria-roledescription", "Folie").

Mit aria-roledescription ersetzen Sie den Rollennamen, den ein Screenreader ansagt, durch einen eigenen, lokalisierten Text. Aus „Gruppe“ wird zum Beispiel „Folie“, aus „Schaltfläche“ „Kachel“. Die semantische Rolle des Elements bleibt dabei unverändert. Hilfstechnologien behandeln es weiter als group, button usw., nur die Ansage ändert sich.

Sinnvoll ist das bei eigenen Widgets, deren Standardrolle Nutzer nicht gut verstehen, etwa bei Folien in einem Karussell, Präsentationsfolien oder Kacheln in einem Dashboard. Das Element sollte dabei eine gültige, nicht generische Rolle haben (explizit über role oder implizit wie bei <button>). Der Wert muss ein nicht leerer Text sein, der sich deutlich vom eigentlichen Rollennamen unterscheidet.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-roledescription als Text oder null, wenn das Attribut nicht gesetzt ist. Wird null zugewiesen, entfernt das Setzen das Attribut.

Beispiele

Wert lesen und setzen

// HTML: <section id="slide1" role="group" aria-roledescription="Folie" aria-label="1 von 5">…</section>
const slide = document.getElementById('slide1');

console.log(slide.ariaRoleDescription);

// Wert ändern – das Attribut wird automatisch aktualisiert
slide.ariaRoleDescription = 'Präsentationsfolie';
console.log(slide.getAttribute('aria-roledescription'));

Folie Präsentationsfolie

Karussell-Folien lokalisiert beschriften

const texte = { de: 'Folie', en: 'slide', fr: 'diapositive' };
const lang = document.documentElement.lang || 'de';

const slides = document.querySelectorAll('.carousel__slide');
slides.forEach((slide, i) => {
  slide.role = 'group';
  slide.ariaRoleDescription = texte[lang] ?? texte.de;
  slide.ariaLabel = `${i + 1} von ${slides.length}`;
});
// Screenreader sagt z. B.: „1 von 5, Folie“

Attribut entfernen und Fallback für alte Browser

const tile = document.querySelector('.dashboard-tile');

const setRoleDescription = (el, value) => {
  if ('ariaRoleDescription' in Element.prototype) {
    el.ariaRoleDescription = value; // null entfernt das Attribut
  } else if (value === null) {
    el.removeAttribute('aria-roledescription');
  } else {
    el.setAttribute('aria-roledescription', value);
  }
};

setRoleDescription(tile, 'Kachel');
setRoleDescription(tile, null);
console.log(tile.hasAttribute('aria-roledescription'));

false

// Wichtig · Fallstricke

Sparsam einsetzen: Ein eigener Rollenname kann Nutzer verwirren, weil Screenreader-Nutzer auf bekannte Rollen wie „Schaltfläche“ oder „Link“ angewiesen sind, um zu wissen, wie sie mit einem Element umgehen. Ersetzen Sie Standardrollen nur, wenn es einen klaren Mehrwert bringt.
Das Attribut wirkt nur auf Elementen mit einer gültigen, nicht generischen Rolle. Auf einem <div> oder <span> ohne role ignorieren Hilfstechnologien es meist.
Ein leerer Text ("") ist ungültig und wird von Hilfstechnologien ignoriert. Wenn Sie das Attribut loswerden wollen, weisen Sie null zu oder verwenden Sie removeAttribute().
Die Eigenschaft ist kein Ersatz für einen zugänglichen Namen: aria-label bzw. aria-labelledby brauchen Sie weiterhin.
Der Text sollte lokalisiert sein, denn Screenreader übersetzen ihn nicht.
Browser-Kompatibilität: Firefox unterstützt die ARIA-Reflexions-Eigenschaften erst ab Version 119. Für ältere Browser verwenden Sie setAttribute(). Das HTML-Attribut selbst funktioniert überall.

Siehe auch

Element.ariaLabel Element.role Element.ariaBrailleRoleDescription Element.setAttribute() Element.getAttribute() AudioWorkletProcessor.parameterDescriptors ElementInternals.ariaOrientation