ElementInternals.ariaRowIndex — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaRowIndex

Beschreibung

Die Eigenschaft ariaRowIndex des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-rowindex. Sie gibt an, an welcher Stelle eine Zeile (bzw. eine Zelle) innerhalb der Gesamtzahl der Zeilen einer table, eines grid oder eines treegrid steht. Die Zählung beginnt bei 1.

Anders als Element.ariaRowIndex setzt die Variante auf ElementInternals kein sichtbares HTML-Attribut. Der Wert fließt stattdessen als Standard-Semantik direkt in den Barrierefreiheitsbaum. So kann ein autonomes Custom Element (z. B. <data-row>) seine ARIA-Semantik intern festlegen, ohne das DOM seines Nutzers zu verändern. Setzt der Nutzer selbst ein aria-rowindex-Attribut am Element, hat dieses Vorrang.

Gebraucht wird die Eigenschaft vor allem bei virtualisierten oder paginierten Tabellen, bei denen nur ein Teil der Zeilen im DOM liegt. Ohne einen Index könnten Screenreader nur die gerade gerenderten Zeilen zählen. Meistens kombiniert man sie mit ariaRowCount am Grid-Container.

Die Eigenschaft ist nur verfügbar, wenn man sich im Konstruktor eines Custom Elements über this.attachInternals() ein ElementInternals-Objekt geholt hat.

Parameter

Name	Typ	Default	Beschreibung
$wert	string \| null	null	Beim Setzen: eine positive ganze Zahl als String (z. B. `"5"`), größer oder gleich `1` und höchstens so groß wie `aria-rowcount`. Mit `null` entfernt man die Standard-Semantik wieder.

Rückgabewert

Typ

string | null

Beschreibung

Den gesetzten Zeilenindex als String oder null, wenn keiner festgelegt wurde. Der Wert wird nicht in eine Zahl umgewandelt.

Beispiele

Custom Element mit Zeilenindex im Konstruktor

class DataRow extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'row';
    this.#internals.ariaRowIndex = '1';
  }
  get internals() { return this.#internals; }
}
customElements.define('data-row', DataRow);

const row = document.createElement('data-row');
console.log(row.internals.ariaRowIndex);
console.log(row.getAttribute('aria-rowindex'));

1 null

Virtualisierte Tabelle: Index aus Datenposition setzen

class GridRow extends HTMLElement {
  static observedAttributes = ['data-index'];
  #internals = this.attachInternals();
  constructor() {
    super();
    this.#internals.role = 'row';
  }
  attributeChangedCallback(name, _alt, neu) {
    // Datenindex ist 0-basiert, aria-rowindex 1-basiert (+1 für Kopfzeile)
    this.#internals.ariaRowIndex = neu === null ? null : String(Number(neu) + 2);
  }
}
customElements.define('grid-row', GridRow);

const grid = document.createElement('div');
grid.setAttribute('role', 'grid');
grid.ariaRowCount = '1001'; // 1000 Datensätze + Kopfzeile

// Es werden nur die Zeilen 500–509 gerendert
for (let i = 500; i < 510; i++) {
  const row = document.createElement('grid-row');
  row.dataset.index = i;
  grid.append(row);
}
document.body.append(grid);

Attribut des Nutzers hat Vorrang

class TreeItemRow extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'row';
    internals.ariaRowIndex = '3';
  }
}
customElements.define('tree-item-row', TreeItemRow);

const el = document.createElement('tree-item-row');
el.setAttribute('aria-rowindex', '7');
// Im Barrierefreiheitsbaum gilt jetzt 7, nicht 3
console.log(el.ariaRowIndex);

7

// Wichtig · Fallstricke

Der Wert ist ein String: Zahlen werden beim Setzen zwar umgewandelt, beim Lesen erhält man aber immer "5" statt 5. Zum Rechnen deshalb Number() verwenden.
Die Zählung beginnt bei 1, nicht bei 0. Kopfzeilen zählen mit. Ein häufiger Fehler ist, den 0-basierten Array-Index direkt zu übernehmen.
Der Wert wird nicht geprüft: Ungültige Angaben wie "0" oder "abc" werden gespeichert, von assistiven Technologien aber ignoriert.
Sinnvoll nur zusammen mit einer passenden Rolle (row, cell, gridcell, rowheader, columnheader) innerhalb eines table-, grid- oder treegrid-Containers.
Ein aria-rowindex-Attribut, das der Nutzer am Element setzt, überschreibt die Standard-Semantik aus ElementInternals.
attachInternals() lässt sich pro Element nur einmal aufrufen und funktioniert nur bei autonomen Custom Elements, nicht bei erweiterten eingebauten Elementen (is="…").
Kompatibilität: Die ARIA-Reflexion auf ElementInternals gibt es in Firefox erst ab Version 119. Bei älteren Browsern vorher mit 'ariaRowIndex' in ElementInternals.prototype prüfen, ob die Eigenschaft unterstützt wird.

Siehe auch

ElementInternals.ariaExpanded ElementInternals.ariaColIndex ElementInternals.ariaPosInSet ElementInternals.ariaRowIndexText ElementInternals.ariaHidden