Element.ariaColSpan — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaColSpan

Beschreibung

Die Eigenschaft ariaColSpan ist die JavaScript-Spiegelung (Reflection) des Attributs aria-colspan. Mit ihr teilst du Hilfstechnologien wie Screenreadern mit, über wie viele Spalten sich eine Zelle (role="cell", role="gridcell", role="columnheader" oder role="rowheader") erstreckt. Das Lesen und Schreiben der Eigenschaft wirkt direkt auf das Attribut im DOM – el.ariaColSpan = "2" entspricht also el.setAttribute("aria-colspan", "2").

Gebraucht wird das vor allem bei selbstgebauten Tabellen und Datengrids aus <div>-Elementen, etwa in virtualisierten Grids oder Tabellenkomponenten von UI-Bibliotheken. Bei nativen HTML-Tabellen nutzt du stattdessen das colspan-Attribut von <td> bzw. <th>; dieses wird automatisch an den Accessibility-Baum weitergegeben, aria-colspan ist dort überflüssig.

Der Wert ist immer ein String (oder null, wenn das Attribut fehlt), obwohl er semantisch eine positive Ganzzahl ≥ 1 darstellt. Zum Rechnen musst du ihn also selbst mit Number() oder parseInt() umwandeln.

Parameter

Name	Typ	Default	Beschreibung
$wert	string \| null		Beim Setzen: String mit einer positiven Ganzzahl (z. B. `"2"`). Das Zuweisen von `null` entfernt das Attribut `aria-colspan`.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-colspan als String, oder null, wenn das Attribut nicht gesetzt ist.

Beispiele

Wert auslesen und ändern

// HTML: <div role="grid"><div role="row"><div id="summe" role="gridcell" aria-colspan="2">Summe</div></div></div>
const zelle = document.getElementById("summe");

console.log(zelle.ariaColSpan); // String!
zelle.ariaColSpan = "3";
console.log(zelle.getAttribute("aria-colspan"));

2 3

Zellenbreite in einem CSS-Grid und für Screenreader synchron setzen

// Setzt die visuelle Spaltenbreite und die ARIA-Information gemeinsam
const setzeSpannweite = (zelle, spalten) => {
  zelle.style.gridColumn = `span ${spalten}`;
  zelle.ariaColSpan = String(spalten);
};

const kopf = document.createElement("div");
kopf.role = "columnheader";
kopf.textContent = "Quartal 1";
setzeSpannweite(kopf, 3);

console.log(kopf.outerHTML);

<div role="columnheader" style="grid-column: span 3;" aria-colspan="3">Quartal 1</div>

Spannweite numerisch auswerten und Attribut entfernen

const zellen = document.querySelectorAll('[role="gridcell"]');

// Gesamtzahl belegter Spalten einer Zeile berechnen
const belegteSpalten = [...zellen].reduce(
  (summe, z) => summe + (Number(z.ariaColSpan) || 1),
  0
);
console.log(`Belegte Spalten: ${belegteSpalten}`);

// Attribut wieder entfernen (Standard: 1 Spalte)
zellen[0].ariaColSpan = null;
console.log(zellen[0].hasAttribute("aria-colspan"));

Belegte Spalten: 4 false

// Wichtig · Fallstricke

Nicht bei nativen Tabellen verwenden: Für <td>/<th> gilt colspan (bzw. die Eigenschaft HTMLTableCellElement.colSpan, die eine Zahl liefert). aria-colspan ist nur für ARIA-Rollen wie cell, gridcell, columnheader und rowheader gedacht.
Typ: ariaColSpan liefert einen String, keine Zahl. zelle.ariaColSpan + 1 ergibt z. B. "21" statt 3.
Nur Semantik: Das Attribut ändert die Darstellung nicht. Die visuelle Spannweite (z. B. grid-column: span n) musst du selbst per CSS setzen und synchron halten.
Gültig sind nur Ganzzahlen ≥ 1. Ungültige Werte werden unverändert gespeichert, von Hilfstechnologien aber ignoriert oder uneinheitlich behandelt.
Kompatibilität: Firefox unterstützt ARIA-Reflection erst ab Version 119. Für ältere Browser weichst du auf setAttribute("aria-colspan", …) aus, was überall funktioniert.

Siehe auch

Element.ariaRowSpan Element.ariaColCount Element.ariaColIndex Element.role HTMLTableCellElement.colSpan Element.setAttribute() Element.ariaPlaceholder