Signatur
Beschreibung
Die Methode createCaption() gehört zur Schnittstelle HTMLTableElement. Sie liefert die Tabellenüberschrift (<caption>) einer Tabelle. Hat die Tabelle schon ein <caption>-Element, bekommst du genau dieses zurück, und es wird kein zweites angelegt. Andernfalls wird ein neues, leeres <caption> erzeugt, als erstes Kind der Tabelle eingefügt und zurückgegeben.
Das ist praktisch, wenn du Tabellen per Skript erzeugst oder änderst und eine barrierefreie Beschriftung sicherstellen willst. Screenreader lesen die <caption> als Namen der Tabelle vor. Weil die Methode idempotent ist, kannst du sie beliebig oft aufrufen, ohne vorher prüfen zu müssen, ob schon eine Beschriftung da ist.
Laut HTML-Standard muss <caption> das erste Kind von <table> sein. Die Methode hält sich automatisch daran. Mit createElement('caption') und append() würdest du das Element dagegen leicht an die falsche Stelle setzen. Zum Entfernen gibt es das Gegenstück deleteCaption(), lesend und schreibend zugreifen kannst du auch über die Eigenschaft table.caption.
Rückgabewert
<caption>-Element der Tabelle.Beispiele
Beschriftung zu einer vorhandenen Tabelle hinzufügen
// HTML: <table id="umsatz"><tr><td>Q1</td><td>12.000 €</td></tr></table>
const table = document.querySelector('#umsatz');
const caption = table.createCaption();
caption.textContent = 'Umsatz 2024 nach Quartal';
console.log(table.firstElementChild === caption);
console.log(caption.tagName);Mehrfacher Aufruf liefert dasselbe Element
const table = document.createElement('table');
const a = table.createCaption();
const b = table.createCaption();
console.log(a === b);
console.log(table.querySelectorAll('caption').length);Tabelle komplett per Skript aufbauen
const renderTable = (titel, zeilen) => {
const table = document.createElement('table');
// Reihenfolge egal: caption landet immer an erster Stelle
const tbody = table.createTBody();
for (const [name, wert] of zeilen) {
const row = tbody.insertRow();
row.insertCell().textContent = name;
row.insertCell().textContent = wert;
}
table.createCaption().textContent = titel;
return table;
};
const t = renderTable('Lagerbestand', [['Schrauben', 540], ['Muttern', 320]]);
document.body.append(t);
console.log(t.firstElementChild.outerHTML);Beschriftung umschalten mit deleteCaption()
const table = document.querySelector('table');
const toggleCaption = (text) => {
if (table.caption) {
table.deleteCaption();
} else {
table.createCaption().textContent = text;
}
};
toggleCaption('Messwerte');
console.log(table.caption?.textContent);
toggleCaption();
console.log(table.caption);// Wichtig · Fallstricke
- Keine Duplikate: Ist bereits ein
<caption>vorhanden, gibt die Methode dieses zurück und legt kein neues an. Vorhandener Text bleibt erhalten. Wenn du den Text neu setzen willst, überschreibetextContentausdrücklich. - Sicherheit: Setze Beschriftungstexte aus Benutzereingaben über
textContentund nicht überinnerHTML, sonst riskierst du XSS. - Nur Tabellen: Die Methode gibt es nur auf
HTMLTableElement. Auf<tbody>oder anderen Elementen fehlt sie, dort erhältst du einenTypeError. - Gestaltung: Die Position der Beschriftung steuerst du per CSS mit
caption-side. Das veraltete Attributalignsolltest du nicht mehr verwenden. - Kompatibilität: Wird seit DOM Level 1 von allen Browsern unterstützt. In Node.js steht die Methode nur mit einer DOM-Implementierung wie jsdom zur Verfügung.