Element.ariaColCount — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaColCount

Beschreibung

Die Eigenschaft ariaColCount gehört zum ARIA-Reflection-Mixin (ARIAMixin) des Element-Interfaces. Sie spiegelt das HTML-Attribut aria-colcount wider. Wenn du die Eigenschaft liest, erhältst du den Attributwert als String. Wenn du sie setzt, wird das Attribut sofort im DOM aktualisiert. Setzt du sie auf null, wird das Attribut entfernt.

Gebraucht wird aria-colcount, wenn nur ein Teil der Spalten im DOM liegt, etwa bei virtualisierten Tabellen, horizontal scrollenden Datengrids oder Tabellen mit ausgeblendeten Spalten. Screenreader können dann ansagen „Spalte 5 von 120“, obwohl nur zehn Spalten gerendert sind. Die einzelnen Zellen bekommen dazu aria-colindex (bzw. ariaColIndex).

Gültig ist das Attribut auf Elementen mit den Rollen table, grid und treegrid, auch auf nativen <table>-Elementen. Der Wert ist eine ganze Zahl für die Gesamtzahl der Spalten. -1 bedeutet, dass die Gesamtzahl unbekannt ist. Liegen ohnehin alle Spalten im DOM, lass das Attribut weg: Der Browser berechnet die Anzahl dann selbst.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: die Gesamtzahl der Spalten als String, z. B. `"120"`, oder `"-1"`, wenn die Anzahl unbekannt ist. `null` entfernt das Attribut.

Rückgabewert

Typ

string | null

Beschreibung

Den aktuellen Wert des aria-colcount-Attributs als String oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Wert lesen und setzen

// HTML: <div id="grid" role="grid" aria-colcount="8">…</div>
const grid = document.getElementById('grid');

console.log(grid.ariaColCount); // "8"

grid.ariaColCount = '12';
console.log(grid.getAttribute('aria-colcount')); // "12"

// Attribut entfernen
grid.ariaColCount = null;
console.log(grid.hasAttribute('aria-colcount')); // false

8 12 false

Virtualisiertes Datengrid: Gesamtzahl und Spaltenindex setzen

const columns = Array.from({ length: 50 }, (_, i) => `Spalte ${i + 1}`);
const table = document.createElement('table');
const row = table.insertRow();

// Es werden nur die Spalten 11–15 gerendert
const start = 10;
const visible = columns.slice(start, start + 5);

table.ariaColCount = String(columns.length);

visible.forEach((label, i) => {
  const th = document.createElement('th');
  th.textContent = label;
  th.ariaColIndex = String(start + i + 1); // Zählung beginnt bei 1
  row.append(th);
});

document.body.append(table);
console.log(table.ariaColCount, row.cells[0].ariaColIndex);

50 11

Gesamtzahl unbekannt, z. B. bei nachgeladenen Spalten

const grid = document.querySelector('[role="grid"]');

const loadColumns = async () => {
  grid.ariaColCount = '-1'; // Gesamtzahl noch unbekannt
  const res = await fetch('/api/columns');
  const cols = await res.json();
  grid.ariaColCount = String(cols.length);
};

loadColumns();

Fallback für ältere Browser

const setColCount = (el, count) => {
  if ('ariaColCount' in Element.prototype) {
    el.ariaColCount = String(count);
  } else {
    el.setAttribute('aria-colcount', String(count));
  }
};

setColCount(document.querySelector('table'), 24);

// Wichtig · Fallstricke

Der Wert ist immer ein String: Obwohl eine Zahl gemeint ist, liefert die Eigenschaft \"8\" und nicht 8. Zum Rechnen wandle ihn mit Number() oder parseInt() um. Gesetzte Zahlen werden automatisch in Strings umgewandelt.
Nur bei unvollständigem DOM verwenden: Liegen alle Spalten im DOM, ist das Attribut überflüssig. Ein falscher Wert führt dazu, dass Screenreader falsche Angaben machen.
Nicht mit aria-colindex verwechseln: aria-colcount gehört auf den Tabellen- bzw. Grid-Container. aria-colindex gehört auf Zeilen oder Zellen und beginnt bei 1.
Der Wert sollte die tatsächliche Gesamtzahl aller Spalten angeben oder -1 sein, wenn diese unbekannt ist. Browser prüfen den Wert nicht.
Browser-Kompatibilität: Firefox unterstützt ARIA-Reflection erst ab Version 119. Für ältere Browser verwende setAttribute('aria-colcount', …), das überall funktioniert.
Die Eigenschaft ändert nur den Barrierefreiheitsbaum, nicht die Darstellung oder das Verhalten der Tabelle.

Siehe auch

Element.ariaColIndex Element.ariaColSpan Element.ariaRowCount Element.ariaRowIndex Element.role Element.setAttribute() Element.ariaCurrent