HTMLTableElement.insertRow() — Methode · JavaScript-Referenz

Signatur

HTMLTableElement.prototype.insertRow(index)

Beschreibung

Mit insertRow() fügen Sie einer Tabelle direkt über das DOM eine neue Zeile hinzu, ohne document.createElement('tr') und appendChild() selbst aufzurufen. Die Methode liefert das neue HTMLTableRowElement zurück. Dieses befüllen Sie danach meist mit insertCell().

Der index bezieht sich auf die Sammlung table.rows. Diese enthält alle Zeilen der Tabelle in dieser Reihenfolge: zuerst <thead>, dann alle <tbody>-Zeilen bzw. direkte Kind-<tr>, zuletzt <tfoot>. Die neue Zeile landet dabei immer im selben Elternelement wie die Zeile, vor der sie eingefügt wird:

Hat die Tabelle weder Zeilen noch ein <tbody>, erzeugt der Browser automatisch ein <tbody> und fügt die Zeile dort ein.
Hat die Tabelle keine Zeilen, aber ein <tbody>, kommt die Zeile ins letzte <tbody>.
Bei -1 oder index === rows.length wird die Zeile an das Elternelement der letzten Zeile angehängt. Das kann auch ein <tfoot> sein.
Sonst wird die Zeile direkt vor der Zeile mit der Position index eingefügt.

Wollen Sie gezielt in den Tabellenrumpf schreiben, rufen Sie besser table.tBodies[0].insertRow() auf, also die gleichnamige Methode von HTMLTableSectionElement. Dort gilt der Index nur innerhalb dieses Abschnitts.

Parameter

Name	Typ	Default	Beschreibung
$index	number	-1	Position der neuen Zeile in `table.rows`. Erlaubt sind `-1` bis `rows.length`. `-1` oder `rows.length` hängt die Zeile hinten an, `0` fügt sie als erste Zeile ein.

Rückgabewert

Typ

HTMLTableRowElement

Beschreibung

Das neu erzeugte, bereits eingefügte <tr>-Element. Es ist noch leer, die Zellen fügen Sie mit insertCell() hinzu.

Beispiele

Zeile am Ende anhängen und befüllen

// HTML: <table id="users"><tbody></tbody></table>
const table = document.querySelector('#users');

const row = table.insertRow(); // entspricht insertRow(-1)
row.insertCell().textContent = 'Anna';
row.insertCell().textContent = 'anna@example.com';

console.log(table.rows.length);
console.log(row.parentElement.tagName);

1 TBODY

Tabelle aus einem Daten-Array aufbauen

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

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

for (const { name, price } of products) {
  const row = tbody.insertRow();
  row.insertCell().textContent = name; // textContent statt innerHTML: kein XSS
  row.insertCell().textContent = price.toLocaleString('de-DE', {
    style: 'currency',
    currency: 'EUR'
  });
}

document.body.append(table);
console.log(table.rows[2].cells[1].textContent);

229,00 €

Neue Zeile oben im tbody unter dem thead einfügen

// HTML: <table id="log"><thead><tr><th>Zeit</th><th>Ereignis</th></tr></thead><tbody></tbody></table>
const table = document.querySelector('#log');

const addLogEntry = (text) => {
  // insertRow(1) auf der Tabelle: Position direkt nach der thead-Zeile.
  // Sicherer ist der Aufruf auf dem tbody:
  const row = table.tBodies[0].insertRow(0);
  row.insertCell().textContent = new Date().toLocaleTimeString('de-DE');
  row.insertCell().textContent = text;
  return row;
};

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

Benutzer angemeldet

Ungültigen Index abfangen

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

try {
  table.insertRow(5); // die Tabelle hat 0 Zeilen
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Fehler bei ungültigem Index: Ist index kleiner als -1 oder größer als rows.length, wirft die Methode eine DOMException vom Typ IndexSizeError.
Falle mit tfoot: table.insertRow() hängt die Zeile an das Elternelement der letzten Zeile an. Hat die Tabelle ein <tfoot> mit Zeilen, landet die neue Zeile deshalb im Tabellenfuß und nicht im Rumpf. Nehmen Sie dafür table.tBodies[0].insertRow().
Index über die ganze Tabelle: Der Index zählt auch die Zeilen in <thead> mit. insertRow(0) fügt die Zeile daher vor der Kopfzeile ein, also im <thead>.
Automatisches tbody: In einer leeren Tabelle ohne <tbody> legt die Methode selbst eines an. Wenn Sie tr dagegen mit appendChild() einfügen, passiert das nicht.
Sicherheit: Befüllen Sie die Zellen mit textContent. innerHTML mit Benutzereingaben öffnet XSS-Lücken.
Leistung: Bei sehr vielen Zeilen bauen Sie die Tabelle am besten erst außerhalb des Dokuments auf, etwa ein noch nicht eingehängtes <tbody>, und fügen sie dann auf einmal ein. So lösen Sie weniger Reflows aus.
Kompatibilität: Die Methode funktioniert in allen Browsern. Den Parameter index dürfen Sie aber erst seit der HTML5-Spezifikation weglassen. Sehr alte Browser (z. B. Firefox vor Version 20) verlangen ihn zwingend, deshalb übergeben Sie bei Bedarf ausdrücklich -1.

Siehe auch

HTMLTableRowElement.deleteCell() HTMLTableElement.deleteRow() HTMLTableElement.deleteTFoot() HTMLTableElement.createTBody() HTMLTableElement.createTFoot()