HTMLTableCaptionElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLTableCaptionElement extends HTMLElement

Beschreibung

Das Interface HTMLTableCaptionElement steht für ein <caption>-Element im DOM. Die Beschriftung einer Tabelle ist mehr als Deko: Screenreader lesen sie als zugänglichen Namen der Tabelle vor. Wer eine Datentabelle barrierefrei machen will, sollte ihr deshalb immer eine Beschriftung geben.

Das Interface bringt kaum eigene Mitglieder mit. Es erbt alles von HTMLElement, also etwa textContent, classList oder hidden. Die einzige eigene Eigenschaft ist das veraltete align, das die Position der Beschriftung festlegt ("top", "bottom", "left", "right").

In der Praxis bekommt man ein solches Objekt meist über die Tabelle selbst: HTMLTableElement.caption liest oder setzt die Beschriftung, createCaption() gibt die vorhandene zurück oder legt eine neue an, und deleteCaption() entfernt sie. Alternativ geht auch document.createElement("caption").

Laut Spezifikation muss <caption> das erste Kind des <table>-Elements sein. createCaption() und der Setter von table.caption fügen die Beschriftung automatisch an der richtigen Stelle ein.

Parameter

Name	Typ	Default	Beschreibung
$align	string	""	Veraltet. Eigenschaft, die das HTML-Attribut `align` widerspiegelt (`"top"`, `"bottom"`, `"left"`, `"right"`). Stattdessen die CSS-Eigenschaft `caption-side` verwenden.

Rückgabewert

Typ

HTMLTableCaptionElement

Beschreibung

Instanzen entstehen über document.createElement("caption"), table.createCaption() oder durch Lesen von table.caption (ist null, wenn keine Beschriftung da ist).

Beispiele

Beschriftung mit createCaption() anlegen

const table = document.querySelector("#umsatz");
// Gibt die vorhandene Beschriftung zurück oder legt eine neue an
const caption = table.createCaption();
caption.textContent = "Umsatz 2024 nach Quartal";

console.log(caption instanceof HTMLTableCaptionElement);
console.log(table.firstElementChild === caption);

true true

Beschriftung per createElement erzeugen und zuweisen

const table = document.createElement("table");
table.innerHTML = "<tr><th>Name</th><th>Punkte</th></tr>";

const caption = document.createElement("caption");
caption.textContent = "Rangliste";
caption.classList.add("table-title");

// Der Setter fügt die Beschriftung als erstes Kind ein
table.caption = caption;
document.body.append(table);

console.log(table.caption.textContent);

Rangliste

Beschriftung dynamisch aktualisieren und entfernen

const table = document.querySelector("table");

const updateCaption = (count) => {
  const caption = table.caption ?? table.createCaption();
  caption.textContent = `${count} Einträge gefunden`;
};

updateCaption(42);
console.log(table.caption.textContent);

// Beschriftung komplett löschen
table.deleteCaption();
console.log(table.caption);

42 Einträge gefunden null

Position per CSS statt veraltetem align setzen

const caption = document.querySelector("table").createCaption();
caption.textContent = "Quelle: Statistisches Bundesamt";

// Veraltet: caption.align = "bottom";
caption.style.captionSide = "bottom";
console.log(getComputedStyle(caption).captionSide);

bottom

// Wichtig · Fallstricke

Kompatibilität: Das Interface wird seit Jahren in allen Browsern unterstützt. align ist veraltet und sollte nicht mehr benutzt werden. Stattdessen caption-side in CSS nehmen. Die Werte left und right werden dort nicht zuverlässig unterstützt.
Reihenfolge: Wer ein <caption> mit appendChild() ans Ende der Tabelle hängt, bekommt ungültiges HTML. Besser createCaption() oder table.caption = … verwenden, denn beide fügen die Beschriftung als erstes Kind ein.
Pro Tabelle ist nur eine Beschriftung erlaubt. Der Setter von table.caption ersetzt eine vorhandene Beschriftung.
Barrierefreiheit: Die Beschriftung nicht mit display: none verstecken, sonst lesen Screenreader sie nicht mehr vor. Wenn sie nicht sichtbar sein soll, eine visuell versteckte Klasse (.sr-only) verwenden.
Sicherheit: Texte aus Benutzereingaben mit textContent einfügen, nicht mit innerHTML. So lassen sich XSS-Angriffe vermeiden.

Siehe auch

HTMLTableSectionElement HTMLGeolocationElement HTMLTableColElement HTMLTableCellElement HTMLTableRowElement