Signatur
Beschreibung
Die Eigenschaft span der Schnittstelle HTMLTableColElement spiegelt das HTML-Attribut span der Elemente <col> und <colgroup>. Sie gibt als positive Ganzzahl an, für wie viele aufeinanderfolgende Tabellenspalten das Element gilt. Ein einzelnes <col span="3"> steht also für drei Spalten, die du gemeinsam gestalten kannst, etwa mit einer Hintergrundfarbe oder einer Breite.
Hat das Element kein span-Attribut oder einen ungültigen Wert, liefert die Eigenschaft den Standardwert 1. Laut HTML-Standard wird der gelesene Wert auf den Bereich 1 bis 1000 begrenzt. Wenn du der Eigenschaft einen Wert zuweist, wird das Inhaltsattribut sofort aktualisiert, und der Browser berechnet das Spaltenlayout der Tabelle neu.
Nützlich ist span vor allem, wenn du Spaltengruppen dynamisch umbauen willst, zum Beispiel wenn der Nutzer Spalten ein- oder ausblendet und die zugehörige Spaltengruppe mitwachsen oder schrumpfen soll. Außerdem kannst du damit per Skript herausfinden, welche <col>-Definition zu einer bestimmten Spaltennummer gehört.
Beachte: Bei einem <colgroup> gilt span nur, wenn die Gruppe keine <col>-Kindelemente hat. Enthält sie welche, bestimmen deren Spannen die Größe der Gruppe, und das span-Attribut der Gruppe wird für das Layout ignoriert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | number | 1 | Nur beim Setzen: positive Ganzzahl (unsigned long) mit der Anzahl der Spalten. Der gelesene Wert wird auf 1–1000 begrenzt. |
Rückgabewert
1 und 1000. Ohne Attribut oder bei ungültigem Wert 1.Beispiele
Spannweite auslesen und ändern
// HTML:
// <table id="preise">
// <colgroup>
// <col id="produkt">
// <col id="quartale" span="4">
// </colgroup>
// ...
// </table>
const quartale = document.getElementById('quartale');
console.log(quartale.span); // 4
// Eine fünfte Spalte (Jahressumme) hinzunehmen
quartale.span = 5;
console.log(quartale.getAttribute('span')); // "5"Standardwert und Begrenzung
const col = document.createElement('col');
console.log(col.span); // 1 – kein Attribut gesetzt
col.setAttribute('span', 'abc');
console.log(col.span); // 1 – ungültiger Wert
col.span = 5000;
console.log(col.span); // 1000 – auf das Maximum begrenzt
col.setAttribute('span', '0');
console.log(col.span); // 1 – auf das Minimum begrenztDas col-Element zu einer Spaltennummer finden
// Liefert das <col>, das für die Spalte mit Index spaltenIndex (ab 0) zuständig ist
const findeCol = (table, spaltenIndex) => {
let position = 0;
for (const col of table.querySelectorAll(':scope > colgroup > col')) {
if (spaltenIndex < position + col.span) return col;
position += col.span;
}
return null;
};
const table = document.querySelector('#preise');
const col = findeCol(table, 3);
col?.classList.add('hervorgehoben');
console.log(col?.id);Spaltengruppe beim Ausblenden anpassen
// <colgroup> ohne <col>-Kinder: hier bestimmt span die Größe der Gruppe
const gruppe = document.querySelector('#details-gruppe');
const setzeSichtbareSpalten = (anzahl) => {
gruppe.span = Math.max(1, anzahl);
};
setzeSichtbareSpalten(2);
console.log(gruppe.span); // 2// Wichtig · Fallstricke
- Begrenzung: Laut HTML-Standard liefert
spanimmer einen Wert zwischen 1 und 1000. Ältere Browser haben Werte über 1000 teils nicht begrenzt. Verlasse dich also nicht darauf, dass der gesetzte Wert genauso wieder ausgelesen wird. - Negative Zahlen: Weil der Typ
unsigned longist, wird z. B.-1nach den WebIDL-Regeln umgerechnet und dann auf den Standardwert zurückgesetzt, statt einen Fehler auszulösen. Prüfe Eingaben deshalb vorher selbst. - colgroup mit Kindern: Enthält ein
<colgroup>eigene<col>-Elemente, hat seinspankeine Wirkung aufs Layout. Die Eigenschaft gibt aber trotzdem den Attributwert zurück. - Kein colspan:
spanist nicht dasselbe wiecolspanbei Zellen (HTMLTableCellElement.colSpan). Es verbindet keine Zellen, sondern ordnet nur Spalten einem<col>zu. - Styling: Über
<col>wirken nur wenige CSS-Eigenschaften:background,border,widthundvisibility: collapse. Farbe oder Textausrichtung der Zellen lassen sich darüber nicht ändern. - Kompatibilität: Wird von allen gängigen Browsern seit Langem unterstützt.