HTMLTableRowElement.insertCell() — Methode · JavaScript-Referenz

Signatur

HTMLTableRowElement.prototype.insertCell(index)

Beschreibung

insertCell() ist eine Hilfsmethode des Interfaces HTMLTableRowElement. Sie legt in einem Schritt eine neue Datenzelle (<td>) an und hängt sie in die Zeile ein. Dafür bräuchte man sonst document.createElement('td') und danach insertBefore() bzw. append().

Der Parameter index legt die Position innerhalb der Sammlung row.cells fest. Mit -1 oder ohne Argument landet die Zelle am Ende der Zeile. Mit 0 wird sie zur ersten Zelle. Jeder andere gültige Index setzt die neue Zelle vor die Zelle, die bisher an dieser Stelle stand.

Die Methode lohnt sich vor allem, wenn Sie Tabellen dynamisch aufbauen, etwa aus JSON-Daten, bei Rechnungspositionen oder bei Tabellen, die der Benutzer bearbeiten kann. Zusammen mit HTMLTableElement.insertRow() bzw. HTMLTableSectionElement.insertRow() lassen sich ganze Tabellen erzeugen, ohne HTML-Strings zusammenzusetzen. Das ist sicherer als innerHTML.

Wichtig: insertCell() erzeugt immer ein <td>, nie ein <th>. Kopfzellen müssen Sie mit document.createElement('th') anlegen und selbst einfügen.

Parameter

Name	Typ	Default	Beschreibung
$index	number	-1	Position der neuen Zelle in `row.cells`. `-1` (oder weggelassen) hängt die Zelle am Ende an, `0` fügt sie am Anfang ein. Gültig sind Werte von `-1` bis `row.cells.length`.

Rückgabewert

Typ

HTMLTableCellElement

Beschreibung

Das neu erstellte und bereits eingefügte <td>-Element. Es kann direkt mit Inhalt, Attributen oder Klassen versehen werden.

Beispiele

Zeile mit Zellen am Ende anhängen

const table = document.querySelector('#kunden');
const row = table.tBodies[0].insertRow(); // neue Zeile am Ende

const nameCell = row.insertCell();   // entspricht insertCell(-1)
nameCell.textContent = 'Anna Schmidt';

const cityCell = row.insertCell();
cityCell.textContent = 'Berlin';

console.log(row.cells.length);

2

Tabelle aus JSON-Daten aufbauen

const produkte = [
  { name: 'Tastatur', preis: 49.9 },
  { name: 'Maus', preis: 19.5 },
  { name: 'Monitor', preis: 229 }
];

const tbody = document.querySelector('#produkte tbody');
const format = new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' });

for (const { name, preis } of produkte) {
  const row = tbody.insertRow();
  row.insertCell().textContent = name;
  const preisCell = row.insertCell();
  preisCell.textContent = format.format(preis);
  preisCell.classList.add('rechts');
}

console.log(tbody.rows.length);

3

Zelle an bestimmter Position einfügen (z. B. Positionsnummer vorne)

const rows = document.querySelectorAll('#bestellung tbody tr');

rows.forEach((row, i) => {
  const nrCell = row.insertCell(0); // neue erste Zelle
  nrCell.textContent = String(i + 1);
});

// Zelle zwischen erster und zweiter Spalte einfügen
const ersteZeile = rows[0];
const mitte = ersteZeile.insertCell(1);
mitte.textContent = 'neu';
console.log(ersteZeile.cells[1].textContent);

neu

Ungültigen Index abfangen

const row = document.createElement('tr');
row.insertCell();

try {
  row.insertCell(5); // nur 0..1 bzw. -1 erlaubt
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Ungültiger Index: Ist index kleiner als -1 oder größer als row.cells.length, wirft die Methode eine DOMException vom Typ IndexSizeError.
Nur <td>: Kopfzellen (<th>) lassen sich mit insertCell() nicht erzeugen. Nutzen Sie dafür document.createElement('th') und row.append() oder row.insertBefore().
colspan wird nicht berücksichtigt: Der Index bezieht sich auf die Anzahl der Elemente in row.cells, nicht auf die sichtbaren Spalten. Zellen mit colspan oder rowspan können die tatsächliche Spaltenposition deshalb verschieben.
Sicherheit: Setzen Sie Inhalte mit textContent statt innerHTML, damit Benutzerdaten keine XSS-Lücke öffnen.
Performance: Bei sehr vielen Zeilen lohnt es sich, die Tabelle abseits der Seite aufzubauen (z. B. in einem losgelösten <tbody> oder einem DocumentFragment) und erst danach einzuhängen. So vermeiden Sie wiederholte Neuberechnungen des Layouts (Reflows).
Kompatibilität: Die Methode wird in allen Browsern unterstützt. In älteren Browsern (z. B. frühen Firefox-Versionen) war index ein Pflichtparameter. Wer ganz sicher gehen will, übergibt -1 ausdrücklich.

Siehe auch

HTMLTableRowElement.deleteCell() HTMLTableElement.insertRow() HTMLTableSectionElement.insertRow() HTMLTableElement.deleteRow() HTMLTableElement.deleteTHead()