ElementInternals.ariaColIndex — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaColIndex

Beschreibung

Die Eigenschaft ariaColIndex von ElementInternals legt für ein autonomes Custom Element den Standardwert der ARIA-Eigenschaft aria-colindex fest. Sie gibt an, an welcher Spaltenposition sich eine Zelle oder Kopfzelle innerhalb der gesamten Spaltenzahl einer table, eines grid oder eines treegrid befindet. Die Zählung beginnt bei 1.

Der Vorteil gegenüber dem Attribut: Die Semantik steckt in der Komponente selbst. Der Wert wird über attachInternals() gesetzt, sodass im Light DOM kein aria-colindex-Attribut sichtbar ist. Setzt ein Nutzer der Komponente das Attribut aria-colindex doch selbst am Host-Element, hat dieser Wert Vorrang vor dem Wert aus ElementInternals.

Gebraucht wird die Angabe vor allem bei virtualisierten oder nur teilweise gerenderten Tabellen, wenn also nicht alle Spalten im DOM stehen, etwa bei horizontal gescrollten Datengrids. Stehen alle Spalten im DOM, berechnen Screenreader die Position selbst. Die Angabe ist dann überflüssig.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: ein String mit einer ganzen Zahl ab `1`, der die Spaltenposition angibt, z. B. `"3"`. Mit `null` wird der Standardwert wieder entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der gesetzte Spaltenindex als String oder null, wenn kein Wert gesetzt ist.

Beispiele

Grid-Zelle als Custom Element mit festem Spaltenindex

class GridCell extends HTMLElement {
  static observedAttributes = ['col'];

  constructor() {
    super();
    this._internals = this.attachInternals();
    this._internals.role = 'gridcell';
  }

  attributeChangedCallback(name, _alt, neu) {
    if (name === 'col') {
      // Eigenes Attribut 'col' auf ARIA-Semantik abbilden
      this._internals.ariaColIndex = neu;
    }
  }

  get internals() {
    return this._internals;
  }
}

customElements.define('grid-cell', GridCell);

const zelle = document.createElement('grid-cell');
zelle.setAttribute('col', '5');
console.log(zelle.internals.ariaColIndex);
console.log(zelle.hasAttribute('aria-colindex'));

"5" false

Virtualisiertes Datengrid: Index beim Scrollen aktualisieren

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

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

  // Wird vom Grid aufgerufen, wenn die Zelle neu belegt wird
  setzeSpalte(index) {
    this.#internals.ariaColIndex = String(index + 1); // 1-basiert!
  }

  get spalte() {
    return this.#internals.ariaColIndex;
  }
}

customElements.define('virtual-cell', VirtualCell);

const row = document.createElement('div');
row.setAttribute('role', 'row');

// Nur die sichtbaren Spalten 40–42 (0-basiert) werden gerendert
const sichtbar = [40, 41, 42];
for (const spaltenIndex of sichtbar) {
  const cell = document.createElement('virtual-cell');
  cell.setzeSpalte(spaltenIndex);
  cell.textContent = `Wert ${spaltenIndex}`;
  row.append(cell);
}

console.log([...row.children].map((c) => c.spalte));

["41", "42", "43"]

Wert zurücksetzen und Vorrang des Attributs

class HeaderCell extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'columnheader';
    this.internals.ariaColIndex = '2';
  }
}

customElements.define('header-cell', HeaderCell);

const kopf = new HeaderCell();
// Ein Attribut am Host überschreibt den Standardwert für Hilfstechnologien
kopf.setAttribute('aria-colindex', '7');
console.log(kopf.internals.ariaColIndex); // Internals-Wert bleibt unverändert

kopf.internals.ariaColIndex = null;
console.log(kopf.internals.ariaColIndex);

"2" null

// Wichtig · Fallstricke

Nur für Custom Elements: attachInternals() gibt es nur bei autonomen Custom Elements. Bei eingebauten Elementen oder bei Custom Elements mit is-Attribut wird ein NotSupportedError ausgelöst. Wer attachInternals() zweimal aufruft, bekommt ebenfalls einen Fehler.
1-basiert: Die Zählung beginnt bei 1, nicht bei 0. Wer Array-Indizes direkt übernimmt, kündigt im Screenreader falsche Positionen an.
String-Typ: Zahlen werden beim Setzen in Strings umgewandelt. Der Getter gibt immer einen String oder null zurück. Der Browser prüft den Wert nicht, auch ungültige Werte wie "abc" werden übernommen.
Vorrang: Ein vom Nutzer gesetztes aria-colindex-Attribut am Host überschreibt den Standardwert aus ElementInternals. Der Getter liest dieses Attribut nicht aus.
Nur mit passender Rolle sinnvoll: Der Wert wirkt nur bei Elementen mit der Rolle cell, gridcell, columnheader, rowheader oder row innerhalb einer Tabelle bzw. eines Grids. Bei virtualisierten Grids sollte der Container zusätzlich aria-colcount (bzw. ariaColCount) angeben.
Kompatibilität: Die ARIA-Spiegelung in ElementInternals gibt es in Firefox erst ab Version 119. Für ältere Browser vorher per Feature-Test prüfen, z. B. 'ariaColIndex' in ElementInternals.prototype, und als Ersatz das Attribut setzen.

Siehe auch

ElementInternals.ariaRowIndex ElementInternals.ariaColIndexText ElementInternals.ariaPosInSet ElementInternals.ariaColCount ElementInternals.ariaColSpan