HTMLTableCellElement.colSpan — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTableCellElement.colSpan

Beschreibung

Die Eigenschaft colSpan spiegelt das HTML-Attribut colspan einer Tabellenzelle wider. Sie gibt als positive Ganzzahl an, wie viele Spalten die Zelle horizontal belegt. Fehlt das Attribut, ist der Wert 1.

Typische Einsatzfälle sind Überschriftenzellen über mehrere Spalten (z. B. „Quartal 1“ über drei Monatsspalten), Summenzeilen oder Meldungen wie „Keine Daten vorhanden“, die sich über die ganze Tabellenbreite ziehen sollen. Wenn du Tabellen dynamisch mit insertRow() und insertCell() aufbaust, ist colSpan der direkte Weg, Zellen zu verbinden.

Beim Setzen schreibt der Browser den Wert in das Attribut colspan zurück. Beim Lesen wird der Attributwert begrenzt: Ungültige Werte, 0 und negative Zahlen führen zu 1, Werte über 1000 werden auf 1000 gekappt.

Beachte: Wenn eine Zelle mehr Spalten belegt, musst du in derselben Zeile entsprechend weniger Zellen anlegen. Sonst entsteht eine ungleichmäßige Tabelle, bei der Zellen über den rechten Rand hinausragen.

Parameter

Name	Typ	Default	Beschreibung
$value	number	1	Beim Setzen: Anzahl der zu belegenden Spalten (1–1000). Der Wert wird in eine vorzeichenlose Ganzzahl umgewandelt und als Attribut `colspan` gespeichert.

Rückgabewert

Typ

number

Beschreibung

Positive Ganzzahl zwischen 1 und 1000, die die Anzahl der belegten Spalten angibt. Standardwert ist 1.

Beispiele

colSpan lesen und ändern

// HTML: <table><tr><th id="kopf" colspan="2">Name</th></tr></table>
const kopf = document.getElementById('kopf');
console.log(kopf.colSpan);

kopf.colSpan = 3;
console.log(kopf.getAttribute('colspan'));

2 "3"

Meldung „Keine Daten“ über die ganze Tabellenbreite

const zeigeLeereTabelle = (table) => {
  const tbody = table.tBodies[0] ?? table.createTBody();
  tbody.replaceChildren();

  // Spaltenanzahl aus der Kopfzeile ermitteln (inkl. vorhandener colSpans)
  const spalten = [...table.tHead.rows[0].cells]
    .reduce((summe, zelle) => summe + zelle.colSpan, 0);

  const zelle = tbody.insertRow().insertCell();
  zelle.colSpan = spalten;
  zelle.textContent = 'Keine Daten vorhanden';
  zelle.classList.add('leer');
};

zeigeLeereTabelle(document.querySelector('#bestellungen'));

Gruppierte Kopfzeile dynamisch erzeugen

const table = document.createElement('table');
const thead = table.createTHead();
const gruppen = thead.insertRow();
const monate = thead.insertRow();

const quartale = { Q1: ['Jan', 'Feb', 'Mär'], Q2: ['Apr', 'Mai', 'Jun'] };

for (const [quartal, liste] of Object.entries(quartale)) {
  const th = document.createElement('th');
  th.textContent = quartal;
  th.colSpan = liste.length; // umspannt alle Monate des Quartals
  gruppen.append(th);

  for (const monat of liste) {
    const m = document.createElement('th');
    m.textContent = monat;
    monate.append(m);
  }
}

document.body.append(table);
console.log([...gruppen.cells].map((c) => c.colSpan));

[3, 3]

Begrenzung ungültiger Werte

const td = document.createElement('td');

td.setAttribute('colspan', '0');
console.log(td.colSpan);

td.setAttribute('colspan', 'abc');
console.log(td.colSpan);

td.setAttribute('colspan', '5000');
console.log(td.colSpan);

1 1 1000

// Wichtig · Fallstricke

Schreibweise: Die Eigenschaft heißt colSpan mit großem S. cell.colspan = 2 legt nur eine eigene JavaScript-Eigenschaft an und ändert nichts an der Darstellung.
Kein 0: Anders als bei rowSpan, wo 0 „bis zum Ende der Tabellengruppe“ bedeutet, wird colspan="0" als 1 behandelt.
Grenzen: Werte über 1000 werden auf 1000 gekappt. Das Setzen eines negativen Werts kann je nach Browser eine Umwandlung in eine große vorzeichenlose Zahl auslösen oder einen Fehler werfen. Prüfe den Wert deshalb vorher.
Layout-Konsistenz: Die Summe der colSpan-Werte sollte in jeder Zeile gleich sein. Bei der Berechnung musst du auch Zellen aus darüberliegenden Zeilen mit rowSpan berücksichtigen. cellIndex berücksichtigt keine verbundenen Zellen und entspricht daher nicht der visuellen Spaltenposition.
Barrierefreiheit: Bei komplexen Kopfzeilen mit verbundenen Zellen solltest du die Zuordnung mit scope="colgroup" oder dem Attribut headers herstellen.
Kompatibilität: Wird von allen Browsern seit Langem unterstützt, auch vom Internet Explorer.

Siehe auch

HTMLTableCellElement.align HTMLTableCellElement.rowSpan HTMLTableCellElement.noWrap HTMLTableCellElement.scope HTMLTableCellElement.vAlign