ElementInternals.ariaRowIndexText — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaRowIndexText

Beschreibung

Die Eigenschaft ariaRowIndexText der Schnittstelle ElementInternals entspricht dem ARIA-Attribut aria-rowindextext. Damit legt ein autonomes Custom Element intern eine Textalternative zum numerischen Zeilenindex (aria-rowindex) fest. Screenreader lesen dann zum Beispiel „Kalenderwoche 12“ oder „Zeile B“ statt der bloßen Zahl vor.

Anders als Element.ariaRowIndexText ändert diese Eigenschaft kein sichtbares Attribut im DOM. Sie legt nur die Standard-Semantik des Elements fest. Setzt jemand das Attribut aria-rowindextext direkt am Host-Element, hat dieser Wert Vorrang. So bestimmt das Custom Element sein Verhalten selbst und bleibt trotzdem von außen überschreibbar.

Die Eigenschaft ist sinnvoll für Web Components, die Zeilen in Tabellen, Grids oder Baum-Grids darstellen, etwa mit role="row", "cell", "gridcell", "rowheader" oder "columnheader". Das gilt besonders, wenn der numerische Index für Menschen wenig aussagt oder nur ein Teil der Zeilen im DOM liegt (Virtualisierung). Setzen Sie aria-rowindextext immer zusätzlich zu aria-rowindex und nie als Ersatz dafür.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der lesbare Text für den Zeilenindex, z. B. `"Woche 12"`. Mit `null` entfernen Sie den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell festgelegte Standardwert als Zeichenkette. Wurde nichts festgelegt, ist der Wert null.

Beispiele

Custom Element als Tabellenzeile mit lesbarem Index

class KalenderZeile extends HTMLElement {
  #internals;

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

  connectedCallback() {
    const woche = Number(this.dataset.woche ?? 1);
    this.#internals.ariaRowIndex = String(woche + 1); // +1 wegen Kopfzeile
    this.#internals.ariaRowIndexText = `Kalenderwoche ${woche}`;
  }

  get rowIndexText() {
    return this.#internals.ariaRowIndexText;
  }
}

customElements.define('kalender-zeile', KalenderZeile);

const zeile = document.createElement('kalender-zeile');
zeile.dataset.woche = '12';
document.body.append(zeile);
console.log(zeile.rowIndexText);
console.log(zeile.getAttribute('aria-rowindextext'));

Kalenderwoche 12 null

Virtualisiertes Grid: Text beim Recycling der Zeile aktualisieren

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

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

  // Wird vom Virtualisierer aufgerufen, wenn die Zeile neue Daten erhält
  update({ index, label }) {
    this.#internals.ariaRowIndex = String(index);
    this.#internals.ariaRowIndexText = label ?? null;
    this.textContent = label ?? `Zeile ${index}`;
  }
}

customElements.define('grid-row', GridRow);

const row = document.createElement('grid-row');
row.update({ index: 250, label: 'Sitzreihe Y' });
row.update({ index: 251 }); // Ohne label wird der Standardwert entfernt

Attribut am Host überschreibt den internen Wert

class TabellenZeile extends HTMLElement {
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.role = 'row';
    this.#internals.ariaRowIndex = '3';
    this.#internals.ariaRowIndexText = 'Zeile C';
  }
}
customElements.define('tabellen-zeile', TabellenZeile);

const el = document.createElement('tabellen-zeile');
// Wer das Element nutzt, überschreibt den Wert für Screenreader:
el.setAttribute('aria-rowindextext', 'Dritter Eintrag');
console.log(el.ariaRowIndexText); // Element.ariaRowIndexText liest das Attribut

Dritter Eintrag

// Wichtig · Fallstricke

Nicht als Attribut sichtbar: Werte, die über ElementInternals gesetzt werden, tauchen nicht in getAttribute() oder im DOM-Inspektor auf. Prüfen Sie sie im Accessibility-Baum der Entwicklerwerkzeuge.
Nur zusammen mit aria-rowindex: Laut ARIA-Spezifikation ergänzt aria-rowindextext den numerischen Index, ersetzt ihn aber nicht. Fehlt ariaRowIndex, kann der Text ignoriert werden.
Rolle erforderlich: Die Eigenschaft wirkt nur bei Rollen wie row, cell, gridcell, rowheader oder columnheader. Setzen Sie deshalb auch internals.role.
attachInternals() gibt es nur für autonome Custom Elements, und pro Element darf es nur einmal aufgerufen werden. Ein zweiter Aufruf löst eine NotSupportedError-DOMException aus.
Kompatibilität: Chromium-Browser seit Version 81, Safari seit 16.4, Firefox seit 119. Wie Screenreader aria-rowindextext unterstützen, ist unterschiedlich. Testen Sie mit NVDA, JAWS und VoiceOver.

Siehe auch

ElementInternals ElementInternals.ariaRowIndex ElementInternals.ariaColIndexText ElementInternals.role Element.ariaRowIndexText HTMLElement.attachInternals() ElementInternals.ariaErrorMessageElements