Signatur
Beschreibung
Die Eigenschaft caption eines HTMLTableElement gibt das erste direkte <caption>-Kindelement der Tabelle als HTMLTableCaptionElement zurück. Gibt es keines, ist der Wert null. Damit kommen Sie schnell an die Tabellenbeschriftung, ohne selbst mit querySelector zu suchen.
Die Eigenschaft lässt sich auch setzen: Wenn Sie ein HTMLTableCaptionElement zuweisen, entfernt der Browser das bisherige erste <caption>-Element (falls vorhanden) und fügt das neue als erstes Kind der Tabelle ein. Wenn Sie null zuweisen, wird die vorhandene Beschriftung nur entfernt.
Oft sind die Hilfsmethoden bequemer: createCaption() gibt die vorhandene Beschriftung zurück oder legt eine neue an, und deleteCaption() entfernt sie. Eine Tabellenbeschriftung verbessert die Barrierefreiheit, weil Screenreader sie als zugänglichen Namen der Tabelle vorlesen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value (beim Setzen) | HTMLTableCaptionElement | null | Neues <caption>-Element, das die bisherige Beschriftung ersetzt. Mit null wird die bestehende Beschriftung entfernt. |
Rückgabewert
<caption>-Kindelement der Tabelle oder null, wenn es keines gibt.Beispiele
Beschriftung auslesen
// HTML: <table id="umsatz"><caption>Umsatz 2024</caption>...</table>
const table = document.querySelector('#umsatz');
const caption = table.caption;
console.log(caption?.textContent ?? 'Keine Beschriftung vorhanden');Neue Beschriftung zuweisen (ersetzt die alte)
const table = document.querySelector('#umsatz');
const neu = document.createElement('caption');
neu.textContent = 'Umsatz 2024 (vorläufig)';
table.caption = neu; // alte caption wird entfernt, neue als erstes Kind eingefügt
console.log(table.firstElementChild === neu);
console.log(table.querySelectorAll('caption').length);Beschriftung entfernen oder bei Bedarf anlegen
const table = document.querySelector('#umsatz');
// Entfernen – gleichwertig zu table.deleteCaption()
table.caption = null;
console.log(table.caption);
// Nur anlegen, wenn noch keine existiert
const cap = table.caption ?? table.createCaption();
cap.textContent = 'Quartalsübersicht';
console.log(table.caption.textContent);// Wichtig · Fallstricke
- Wenn Sie ein Element zuweisen, das kein
HTMLTableCaptionElementist (z. B. ein<div>oder einen String), wird einTypeErrorausgelöst. - Berücksichtigt wird nur ein direktes Kindelement. Ein
<caption>, das tiefer verschachtelt ist, wird ignoriert. - Ein zugewiesenes Element, das schon an anderer Stelle im DOM hängt, wird dorthin verschoben und nicht kopiert. Wenn Sie eine Kopie brauchen, verwenden Sie
cloneNode(true). - Das HTML-Attribut
alignvon<caption>ist veraltet. Positionieren Sie die Beschriftung mit der CSS-Eigenschaftcaption-side. - Die Eigenschaft wird von allen Browsern unterstützt, auch von sehr alten.