ElementInternals.ariaBrailleLabel — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaBrailleLabel

Beschreibung

Die Eigenschaft ariaBrailleLabel der Schnittstelle ElementInternals entspricht dem ARIA-Attribut aria-braillelabel. Damit gibt ein autonomes Custom Element eine eigene Beschriftung für Braillezeilen vor. Die normale Sprachausgabe (der zugängliche Name) bleibt davon unberührt.

Anders als ein gesetztes Attribut erscheint der Wert nicht im DOM. Er gilt als Standard-Semantik der Komponente: Setzt jemand am Element selbst das Attribut aria-braillelabel, hat dieses Vorrang. So kann die Komponente eine sinnvolle Vorgabe mitbringen, ohne das Light DOM ihrer Nutzer zu verändern.

Gebraucht wird das nur selten, etwa wenn ein ausführlicher zugänglicher Name auf einer Braillezeile zu viel Platz belegt. Beispiele sind Bewertungssterne (***), Statusanzeigen oder Kurzformen wie „Tel.“ statt „Telefonnummer“. Ein ariaBrailleLabel sollte nur ergänzen: Das Element braucht trotzdem einen zugänglichen Namen, etwa über ariaLabel.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: die Braillebeschriftung als freier Text. Mit `null` wird der Standardwert entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell gesetzte Braillebeschriftung oder null, wenn keine gesetzt ist.

Beispiele

Standard-Braillebeschriftung in einer Bewertungskomponente

class StarRating extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'img';
  }

  connectedCallback() {
    const stars = Number(this.getAttribute('value') ?? 0);
    // Sprachausgabe: ausführlich
    this.#internals.ariaLabel = `${stars} von 5 Sternen`;
    // Braillezeile: kompakt
    this.#internals.ariaBrailleLabel = '*'.repeat(stars);
    this.textContent = '★'.repeat(stars) + '☆'.repeat(5 - stars);
    console.log(this.#internals.ariaBrailleLabel);
  }
}

customElements.define('star-rating', StarRating);

const el = document.createElement('star-rating');
el.setAttribute('value', '4');
document.body.append(el);

****

Wert bei Zustandsänderung aktualisieren und entfernen

class StatusBadge extends HTMLElement {
  static observedAttributes = ['state'];
  #internals = this.attachInternals();

  attributeChangedCallback(name, oldValue, newValue) {
    const labels = { online: 'onl', offline: 'offl' };
    this.#internals.role = 'status';
    this.#internals.ariaLabel = `Status: ${newValue}`;
    // Kurzform nur für bekannte Zustände, sonst Vorgabe entfernen
    this.#internals.ariaBrailleLabel = labels[newValue] ?? null;
    console.log(newValue, '→', this.#internals.ariaBrailleLabel);
  }
}

customElements.define('status-badge', StatusBadge);

const badge = document.createElement('status-badge');
badge.setAttribute('state', 'online');
badge.setAttribute('state', 'wartung');

online → onl wartung → null

Attribut am Element überschreibt die Vorgabe

class InfoTag extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.ariaLabel = 'Telefonnummer';
    this.#internals.ariaBrailleLabel = 'Tel.';
  }
}
customElements.define('info-tag', InfoTag);

const tag = document.createElement('info-tag');
// Der Nutzer der Komponente legt eine eigene Beschriftung fest – sie hat Vorrang
tag.setAttribute('aria-braillelabel', 'Fon');
document.body.append(tag);
console.log(tag.getAttribute('aria-braillelabel'));

Fon

// Wichtig · Fallstricke

Verfügbarkeit prüfen: ARIA-Reflexion über ElementInternals und besonders ariaBrailleLabel ist neu. Deshalb vorher prüfen, z. B. mit 'ariaBrailleLabel' in ElementInternals.prototype. Wird die Eigenschaft nicht unterstützt, wirkt die Zuweisung nicht; es kommt aber zu keinem Fehler.
Nur für autonome Custom Elements: attachInternals() funktioniert nicht bei eingebauten Elementen (is="…"). Mehrfaches Aufrufen löst eine NotSupportedError-DOMException aus.
Kein Ersatz für einen zugänglichen Namen: Laut ARIA-Spezifikation sollen Hilfsmittel aria-braillelabel nur beachten, wenn das Element einen zugänglichen Namen hat. Deshalb immer zusätzlich ariaLabel oder sichtbaren Text vorsehen.
Sparsam einsetzen: Viele Braillenutzer haben eigene Kürzungsregeln (Kurzschrift). Ein eigenes Braille-Label kann diese Regeln aushebeln. Deshalb nur verwenden, wenn der normale Name auf der Braillezeile wirklich unpraktisch ist.
Der Wert ist im DOM nicht sichtbar. element.getAttribute('aria-braillelabel') liefert also nicht den Wert aus den Internals.
Die Unterstützung durch Screenreader und Braillezeilen ist unterschiedlich. Mit echten Hilfsmitteln testen, z. B. NVDA, JAWS oder VoiceOver.

Siehe auch

ElementInternals.ariaErrorMessageElements ElementInternals.ariaLabel ElementInternals.ariaLevel ElementInternals.ariaRelevant ElementInternals.ariaValueMax