Element.ariaColIndexText — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaColIndexText

Beschreibung

Die Eigenschaft ariaColIndexText gehört zu den Eigenschaften, die ARIA-Reflection umsetzen. Sie ist direkt mit dem HTML-Attribut aria-colindextext verknüpft: Wer die Eigenschaft liest, bekommt den aktuellen Attributwert. Wer sie setzt, schreibt das Attribut. Einen Umweg über getAttribute() oder setAttribute() braucht man nicht.

aria-colindex gibt die Position einer Zelle innerhalb einer Tabelle oder eines Grids als Zahl an. Manchmal hilft eine Zahl nicht weiter, etwa wenn die Spalten für Nutzer Buchstaben tragen („Spalte B“ in einer Tabellenkalkulation) oder Namen wie Wochentage und Quartale. Dann liefert aria-colindextext einen Text, den Screenreader statt der Zahl vorlesen.

Man setzt die Eigenschaft auf Elementen mit den Rollen cell, gridcell, columnheader, rowheader oder row bzw. auf den passenden nativen Elementen (<td>, <th>). aria-colindextext sollte immer zusätzlich zu aria-colindex stehen und die Zahl nicht ersetzen. Manche Hilfstechnologien lesen nur den Zahlenwert oder brauchen ihn für die Navigation.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: der lesbare Spaltentext, z. B. `"Spalte B"`. Mit `null` wird das Attribut `aria-colindextext` entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-colindextext als String. Fehlt das Attribut, ist der Wert null.

Beispiele

Wert lesen und ändern

// HTML: <td id="zelle" aria-colindex="2" aria-colindextext="B">42</td>
const zelle = document.getElementById('zelle');

console.log(zelle.ariaColIndexText);

zelle.ariaColIndexText = 'Spalte B';
console.log(zelle.getAttribute('aria-colindextext'));

B Spalte B

Tabellenkalkulation: Spaltenbuchstaben für Screenreader

// Wandelt einen 1-basierten Index in Spaltenbuchstaben um (1 → A, 27 → AA)
const spaltenBuchstabe = (index) => {
  let s = '';
  while (index > 0) {
    const rest = (index - 1) % 26;
    s = String.fromCharCode(65 + rest) + s;
    index = Math.floor((index - 1) / 26);
  }
  return s;
};

document.querySelectorAll('[role="gridcell"]').forEach((zelle) => {
  const index = Number(zelle.ariaColIndex); // z. B. "28"
  zelle.ariaColIndexText = `Spalte ${spaltenBuchstabe(index)}`;
});

console.log(spaltenBuchstabe(28));

AB

Wochentage als Spaltennamen in einem Kalender-Grid

const tage = ['Montag', 'Dienstag', 'Mittwoch', 'Donnerstag', 'Freitag', 'Samstag', 'Sonntag'];

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

tage.forEach((tag, i) => {
  const zelle = document.createElement('div');
  zelle.setAttribute('role', 'gridcell');
  zelle.ariaColIndex = String(i + 1);
  zelle.ariaColIndexText = tag;
  zelle.textContent = String(i + 1);
  zeile.append(zelle);
});

console.log(zeile.children[2].ariaColIndexText);

// Attribut wieder entfernen
zeile.children[2].ariaColIndexText = null;
console.log(zeile.children[2].hasAttribute('aria-colindextext'));

Mittwoch false

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser und Safari unterstützen die Eigenschaft seit Längerem, Firefox erst ab Version 119. In älteren Umgebungen und in jsdom kann die Eigenschaft fehlen. Dann ist der Wert undefined und eine Zuweisung legt nur eine gewöhnliche JS-Eigenschaft an, ohne das Attribut zu setzen. Im Zweifel mit 'ariaColIndexText' in Element.prototype prüfen und sonst auf setAttribute('aria-colindextext', …) ausweichen.
Der Wert ist immer ein String. Zahlen werden bei der Zuweisung in Strings umgewandelt. undefined wird zum String "undefined" und entfernt das Attribut nicht. Zum Entfernen null zuweisen.
aria-colindextext nur zusätzlich zu aria-colindex verwenden. Ohne Zahlenindex fehlt Hilfstechnologien die Grundlage für die Navigation.
Nicht jeder Screenreader wertet aria-colindextext schon aus (es gehört zu ARIA 1.3). Deshalb mit echten Hilfstechnologien testen.
Die Eigenschaft ändert nur Attribute für die Barrierefreiheit. Auf die Darstellung oder das Verhalten hat sie keinen Einfluss.

Siehe auch

Element.ariaKeyShortcuts ElementInternals.ariaMultiSelectable Element.ariaRowIndexText Element.ariaColIndex Element.ariaRowIndex