ElementInternals.ariaBrailleRoleDescription — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaBrailleRoleDescription

Beschreibung

Die Eigenschaft ariaBrailleRoleDescription der ElementInternals-Schnittstelle entspricht dem ARIA-Attribut aria-brailleroledescription. Sie legt fest, welche (meist abgekürzte) Rollenbeschreibung eine Braillezeile für das Element ausgibt, zum Beispiel "sld" statt der vollen Beschreibung "Folie".

Anders als Element.ariaBrailleRoleDescription wirkt der Wert über ElementInternals als Standard-Semantik eines autonomen Custom Elements. Im DOM erscheint dafür kein Attribut. Setzt der Autor der Seite am Element selbst ein aria-brailleroledescription-Attribut, hat dieses Vorrang vor dem Wert aus den Internals. So kann eine Komponente sinnvolle Standardwerte mitbringen, die Nutzer der Komponente trotzdem überschreiben können.

Laut Spezifikation sollte die Braillerollenbeschreibung nur zusammen mit einer nicht leeren ariaRoleDescription eingesetzt werden. Sie ist gedacht für die Fälle, in denen die normale Rollenbeschreibung für Braille zu lang ist. Sie darf nicht einfach eine identische Kopie davon sein.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: die Braille-Rollenbeschreibung als Zeichenkette. `null` entfernt den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Die aktuell über die Internals gesetzte Braillerollenbeschreibung oder null, wenn keine gesetzt wurde. Ein vom Autor gesetztes aria-brailleroledescription-Attribut am Element wird dabei nicht gespiegelt.

Beispiele

Standard-Semantik für eine Folien-Komponente

class SlideElement extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'article';
    this.#internals.ariaRoleDescription = 'Folie';
    // Kurzform für Braillezeilen
    this.#internals.ariaBrailleRoleDescription = 'fol';
  }
  get brailleDescription() {
    return this.#internals.ariaBrailleRoleDescription;
  }
}
customElements.define('x-slide', SlideElement);

const slide = document.createElement('x-slide');
document.body.append(slide);
console.log(slide.brailleDescription);
console.log(slide.hasAttribute('aria-brailleroledescription'));

fol false

Autor-Attribut überschreibt den Internals-Standardwert

class ToggleChip extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'button';
    internals.ariaRoleDescription = 'Umschalt-Chip';
    internals.ariaBrailleRoleDescription = 'chip';
    this.internals = internals; // nur zu Demo-Zwecken öffentlich
  }
}
customElements.define('toggle-chip', ToggleChip);

const chip = document.createElement('toggle-chip');
// Seitenautor setzt eigene Beschreibung – diese gewinnt im Accessibility-Tree
chip.setAttribute('aria-roledescription', 'Filter');
chip.setAttribute('aria-brailleroledescription', 'flt');
document.body.append(chip);

console.log(chip.internals.ariaBrailleRoleDescription); // Internals-Wert bleibt erhalten
console.log(chip.getAttribute('aria-brailleroledescription'));

chip flt

Feature-Erkennung und Zurücksetzen

class InfoCard extends HTMLElement {
  #internals = this.attachInternals();
  connectedCallback() {
    if ('ariaBrailleRoleDescription' in this.#internals) {
      this.#internals.ariaRoleDescription = 'Infokarte';
      this.#internals.ariaBrailleRoleDescription = 'ikrt';
    }
  }
  resetBraille() {
    this.#internals.ariaBrailleRoleDescription = null;
    return this.#internals.ariaBrailleRoleDescription;
  }
}
customElements.define('info-card', InfoCard);

const card = document.body.appendChild(document.createElement('info-card'));
console.log(card.resetBraille());

null

// Wichtig · Fallstricke

Browser-Unterstützung: Die ARIA-Reflexion auf ElementInternals gibt es in Chromium-Browsern und Safari. ariaBrailleRoleDescription gehört zu ARIA 1.3 und ist neuer als die übrigen ARIA-Eigenschaften. Firefox unterstützt es derzeit nicht. Prüfen Sie die Unterstützung vorher mit 'ariaBrailleRoleDescription' in internals.
Nur verfügbar, wenn attachInternals() aufgerufen wurde. Das geht nur bei autonomen Custom Elements und nur einmal pro Element (sonst NotSupportedError).
Ohne gültige ariaRoleDescription ignorieren Hilfstechnologien die Braillebeschreibung in der Regel.
Nur verwenden, wenn die Braille-Kurzform wirklich von der normalen Beschreibung abweicht. Ein leerer oder nur aus Leerzeichen bestehender Wert sollte vermieden werden.
Ob und wie der Wert tatsächlich ausgegeben wird, hängt vom Screenreader und der Braillezeile ab. Testen Sie mit echten Hilfstechnologien.

Siehe auch

ElementInternals.ariaLabel ElementInternals.ariaRoleDescription ElementInternals.ariaDescription ElementInternals.ariaBrailleLabel ElementInternals.ariaDetailsElements