ElementInternals.ariaDescription — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaDescription

Beschreibung

Die Eigenschaft ariaDescription der Schnittstelle ElementInternals entspricht dem ARIA-Attribut aria-description. Sie enthält einen frei formulierten Text, der das Element für assistive Technologien wie Screenreader genauer beschreibt oder kommentiert. Der Text ergänzt den zugänglichen Namen (aria-label), ersetzt ihn aber nicht. Screenreader lesen ihn meist erst nach Name und Rolle vor.

Anders als Element.ariaDescription ändert die Eigenschaft auf ElementInternals kein Attribut am Host-Element. Sie legt stattdessen die Standard-Semantik eines autonomen Custom Elements fest. Nutzer der Komponente können diesen Standardwert jederzeit überschreiben, indem sie selbst ein aria-description-Attribut setzen. Das eigene Markup bleibt dadurch sauber, und die Barrierefreiheit ist trotzdem von Anfang an gegeben.

Das ElementInternals-Objekt bekommst du nur über this.attachInternals(), typischerweise im Konstruktor der Custom-Element-Klasse. Weist du null zu, wird der Standardwert entfernt.

Parameter

Name	Typ	Default	Beschreibung
$wert	string \| null	null	Beschreibungstext für assistive Technologien. `null` entfernt die Standard-Beschreibung.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell hinterlegte Standard-Beschreibung, oder null, wenn keine gesetzt ist. Ein vom Nutzer gesetztes aria-description-Attribut am Host-Element wird hier nicht zurückgegeben.

Beispiele

Standard-Beschreibung im Konstruktor festlegen

class LoeschButton extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'button';
    this.#internals.ariaLabel = 'Löschen';
    this.#internals.ariaDescription = 'Entfernt den Eintrag dauerhaft.';
  }

  connectedCallback() {
    this.tabIndex = 0;
    this.textContent = '🗑';
  }
}

customElements.define('loesch-button', LoeschButton);

const btn = document.createElement('loesch-button');
document.body.append(btn);
// Kein Attribut im DOM, aber Semantik für Screenreader vorhanden
console.log(btn.hasAttribute('aria-description'));

false

Beschreibung dynamisch an den Zustand anpassen

class SpeicherStatus extends HTMLElement {
  #internals = this.attachInternals();

  static get observedAttributes() { return ['status']; }

  attributeChangedCallback(name, alt, neu) {
    const texte = {
      gespeichert: 'Alle Änderungen wurden gespeichert.',
      ungespeichert: 'Es gibt ungespeicherte Änderungen.'
    };
    this.#internals.ariaDescription = texte[neu] ?? null;
  }

  get beschreibung() {
    return this.#internals.ariaDescription;
  }
}

customElements.define('speicher-status', SpeicherStatus);

const el = document.createElement('speicher-status');
el.setAttribute('status', 'ungespeichert');
console.log(el.beschreibung);
el.setAttribute('status', 'unbekannt');
console.log(el.beschreibung);

Es gibt ungespeicherte Änderungen. null

Nutzer überschreibt den Standardwert per Attribut

// Setzt voraus, dass <loesch-button> aus Beispiel 1 definiert ist
const btn = document.createElement('loesch-button');
btn.setAttribute('aria-description', 'Löscht nur diesen Kommentar.');
document.body.append(btn);

// Screenreader verwenden jetzt das Attribut; der interne Standard bleibt unverändert
console.log(btn.getAttribute('aria-description'));

Löscht nur diesen Kommentar.

// Wichtig · Fallstricke

Browser-Unterstützung: Die ARIA-Spiegelung auf ElementInternals funktioniert in Chromium-Browsern und Safari (ab 16.4). Firefox unterstützt ariaDescription erst in neueren Versionen und nicht überall. Prüfe die Unterstützung vorab, z. B. mit 'ariaDescription' in ElementInternals.prototype, und greife sonst auf setAttribute('aria-description', …) zurück.
aria-description gehört zum Entwurf von ARIA 1.3. Ältere Screenreader ignorieren es womöglich. Für wichtige Informationen ist aria-describedby mit einem sichtbaren Text robuster.
attachInternals() gibt es nur für autonome Custom Elements. Bei eingebauten Elementen (is="…") und bei einem zweiten Aufruf wird ein NotSupportedError geworfen.
Ein vom Nutzer gesetztes aria-description-Attribut hat immer Vorrang. Die Eigenschaft liest es aber nicht aus.
Die Beschreibung sollte kurz sein und nicht den zugänglichen Namen wiederholen, sonst wird die Ausgabe des Screenreaders unnötig lang.

Siehe auch

ElementInternals.ariaBrailleRoleDescription ElementInternals.ariaRoleDescription ElementInternals.ariaOrientation ElementInternals.ariaSort ElementInternals.ariaColCount