HTMLTableSectionElement.insertRow() — Methode · JavaScript-Referenz

Signatur

HTMLTableSectionElement.prototype.insertRow(index)

Beschreibung

Die Methode insertRow() des Interfaces HTMLTableSectionElement legt eine neue, leere Tabellenzeile (<tr>) an und fügt sie direkt in den jeweiligen Tabellenabschnitt ein, also in <thead>, <tbody> oder <tfoot>. Der Rückgabewert ist die neu erzeugte Zeile, die man anschließend mit insertCell() um Zellen ergänzt.

Der Index bezieht sich nur auf die Zeilen dieses Abschnitts (siehe section.rows), nicht auf die gesamte Tabelle. Das unterscheidet die Methode von HTMLTableElement.insertRow(), deren Index über alle Abschnitte hinweg zählt. Wird -1 übergeben oder der Parameter weggelassen, landet die Zeile am Ende des Abschnitts; bei einem Wert, der gleich der Zeilenanzahl ist, ebenfalls.

Typische Einsatzfälle sind dynamisch erzeugte Datentabellen, etwa aus einer API-Antwort, oder das Einfügen von Summenzeilen in <tfoot>. Gegenüber document.createElement('tr') plus appendChild() spart die Methode Code und stellt sicher, dass die Zeile im richtigen Abschnitt landet.

Parameter

Name	Typ	Default	Beschreibung
$index	number	-1	Position der neuen Zeile innerhalb von `section.rows`. `0` fügt am Anfang ein, `-1` oder `rows.length` am Ende. Die neue Zeile steht anschließend an genau diesem Index.

Rückgabewert

Typ

HTMLTableRowElement

Beschreibung

Die neu erzeugte und bereits eingefügte <tr>-Zeile.

Beispiele

Daten-Array als Zeilen in tbody einfügen

const tbody = document.querySelector('#users tbody');
const users = [
  { name: 'Anna', role: 'Admin' },
  { name: 'Ben', role: 'Redakteur' }
];

for (const user of users) {
  const row = tbody.insertRow(); // am Ende anhängen
  row.insertCell().textContent = user.name;
  row.insertCell().textContent = user.role;
}

console.log(tbody.rows.length);

2

Neueste Einträge oben einfügen

const tbody = document.querySelector('#log tbody');

const addLogEntry = (message) => {
  const row = tbody.insertRow(0); // immer an erster Stelle
  row.insertCell().textContent = new Date().toLocaleTimeString('de-DE');
  row.insertCell().textContent = message;
};

addLogEntry('Server gestartet');
addLogEntry('Benutzer angemeldet');
console.log(tbody.rows[0].cells[1].textContent);

Benutzer angemeldet

Summenzeile im tfoot erzeugen

const table = document.querySelector('#orders');
const tfoot = table.tFoot ?? table.createTFoot();

const total = [...table.tBodies[0].rows]
  .reduce((sum, row) => sum + Number(row.cells[1].textContent), 0);

const row = tfoot.insertRow(-1);
const label = row.insertCell();
label.textContent = 'Summe';
row.insertCell().textContent = total.toFixed(2);

console.log(tfoot.rows.length);

1

Fehlerbehandlung bei ungültigem Index

const tbody = document.createElement('table').createTBody();

try {
  tbody.insertRow(5); // Abschnitt hat 0 Zeilen
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

IndexSizeError: Ist index kleiner als -1 oder größer als rows.length, wird eine DOMException vom Typ IndexSizeError ausgelöst.
Abschnitt statt Tabelle: Der Index zählt nur Zeilen dieses Abschnitts. Wer über die ganze Tabelle hinweg zählen will, nutzt HTMLTableElement.insertRow().
Zellen im thead: insertCell() erzeugt immer <td>. Für Kopfzellen braucht man document.createElement('th') und row.appendChild().
Performance: Jedes Einfügen verändert direkt das DOM. Bei vielen Zeilen ist es günstiger, einen neuen <tbody> außerhalb des DOM zu füllen und ihn dann mit replaceWith() auf einmal auszutauschen.
Sicherheit: Zellinhalte besser über textContent setzen als über innerHTML, damit Nutzerdaten keine XSS-Lücke öffnen.
Die Methode wird von allen gängigen Browsern seit Langem unterstützt. Laut Spezifikation ist index optional (Standardwert -1); sehr alte Browser verlangten ihn noch zwingend.

Siehe auch

HTMLTableSectionElement.deleteRow() HTMLTableElement.insertRow() HTMLTableRowElement.insertCell() HTMLTableElement.deleteRow() HTMLSelectElement.item()