ElementInternals.ariaRoleDescription — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaRoleDescription

Beschreibung

Die Eigenschaft ariaRoleDescription des ElementInternals-Interfaces legt eine menschenlesbare, vom Autor lokalisierte Beschreibung der Rolle eines autonomen Custom Elements fest. Sie entspricht dem ARIA-Attribut aria-roledescription. Screenreader lesen dann etwa „Folie“ statt „Region“ oder „Kanban-Karte“ statt „Schaltfläche“ vor.

Anders als beim Setzen des Attributs mit setAttribute() bleibt der Wert intern: Er erscheint nicht im Markup und kann von Nutzern der Komponente nicht aus Versehen gelöscht werden. Setzt der Verwender der Komponente selbst ein aria-roledescription-Attribut am Host-Element, hat dieses Vorrang. Der interne Wert dient also als Standardwert, den Verwender überschreiben können.

Du erhältst das ElementInternals-Objekt über this.attachInternals() im Konstruktor eines Custom Elements. Die Eigenschaft ist nur sinnvoll, wenn das Element auch eine Rolle hat (z. B. über internals.role). Eine Rollenbeschreibung ohne Rolle oder bei generischen Rollen wie generic wird von assistiven Technologien ignoriert.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: eine lokalisierte, nicht leere Beschreibung der Rolle, z. B. `"Folie"`. Mit `null` entfernst du den internen Wert wieder.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell gesetzte interne Rollenbeschreibung oder null, wenn keine gesetzt ist. Ein aria-roledescription-Attribut am Host-Element wird hier nicht zurückgegeben.

Beispiele

Präsentationsfolie mit eigener Rollenbeschreibung

class SlideView extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'region';
    this.#internals.ariaRoleDescription = 'Folie';
  }
}
customElements.define('slide-view', SlideView);

const slide = document.createElement('slide-view');
slide.setAttribute('aria-label', 'Einführung');
document.body.append(slide);
// Screenreader: „Einführung, Folie“ statt „Einführung, Region“
console.log(slide.hasAttribute('aria-roledescription'));

false

Wert lesen und über eine öffentliche Eigenschaft ändern

class KanbanCard extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.role = 'button';
    this.#internals.ariaRoleDescription = 'Kanban-Karte';
    this.tabIndex = 0;
  }
  // Lokalisierung von außen ermöglichen
  set roleLabel(text) {
    this.#internals.ariaRoleDescription = text || null;
  }
  get roleLabel() {
    return this.#internals.ariaRoleDescription;
  }
}
customElements.define('kanban-card', KanbanCard);

const card = new KanbanCard();
console.log(card.roleLabel);
card.roleLabel = 'Kanban card';
console.log(card.roleLabel);
card.roleLabel = '';
console.log(card.roleLabel);

Kanban-Karte Kanban card null

Attribut des Verwenders hat Vorrang

class InfoTile extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'group';
    internals.ariaRoleDescription = 'Kachel';
  }
}
customElements.define('info-tile', InfoTile);

// Im HTML: <info-tile aria-roledescription="Widget"></info-tile>
// Assistive Technologien lesen hier „Widget“, nicht „Kachel“.
const tile = document.createElement('info-tile');
tile.setAttribute('aria-roledescription', 'Widget');
document.body.append(tile);
console.log(tile.getAttribute('aria-roledescription'));

Widget

// Wichtig · Fallstricke

Nur mit Rolle sinnvoll: Ohne gesetzte Rolle (internals.role) oder bei generic/presentation/none wird die Beschreibung ignoriert.
Sparsam einsetzen: Die Rollenbeschreibung ersetzt die vorgelesene Standardrolle. Nutzer verlieren dadurch den Hinweis, wie man mit dem Element umgeht (z. B. „Schaltfläche“). Sie sollte deshalb eine bekannte Rolle nur präzisieren und nie leer sein oder nur aus Leerzeichen bestehen.
Lokalisierung: Der Wert wird wörtlich vorgelesen. Passe ihn an die Seitensprache (lang) an.
attachInternals() gibt es nur bei autonomen Custom Elements (nicht bei is=\"…\"-Erweiterungen) und nur einmal pro Element. Ein zweiter Aufruf wirft einen NotSupportedError.
Kompatibilität: Die ARIA-Reflexion auf ElementInternals ist erst seit Firefox 119 und Safari 16.4 verfügbar. Für ältere Browser kannst du per Feature-Erkennung ('ariaRoleDescription' in ElementInternals.prototype) auf setAttribute('aria-roledescription', …) zurückfallen.

Siehe auch

ElementInternals.ariaBrailleRoleDescription ElementInternals.ariaDescription ElementInternals.ariaOrientation ElementInternals.ariaColSpan ElementInternals.ariaRowSpan