HTMLTimeElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLTimeElement extends HTMLElement

Beschreibung

HTMLTimeElement ist die DOM-Schnittstelle für das HTML-Element <time>. Sie erbt alle Eigenschaften und Methoden von HTMLElement und ergänzt sie um genau eine eigene Eigenschaft: dateTime. Diese spiegelt das HTML-Attribut datetime wider und enthält eine maschinenlesbare Darstellung von Datum, Uhrzeit oder Dauer.

Das Element trennt die menschenlesbare Anzeige (Textinhalt, z. B. „gestern, 14 Uhr“) vom maschinenlesbaren Wert (z. B. 2024-05-12T14:00). Das ist nützlich für Suchmaschinen, Kalender-Integrationen, Screenreader und für eigene Skripte, die relative Zeitangaben („vor 5 Minuten“) dynamisch berechnen und aktualisieren.

Typische Einsatzfälle sind Veröffentlichungsdaten in Blogartikeln, Kommentar-Zeitstempel, Veranstaltungstermine oder Dauerangaben (z. B. PT2H30M). Fehlt das Attribut datetime, wird laut Spezifikation der Textinhalt als Zeitwert interpretiert – die Eigenschaft dateTime liefert dann jedoch einen leeren String.

Eine Instanz erhält man über document.createElement("time") oder durch Abfrage vorhandener Elemente, z. B. mit document.querySelector("time"). Ein direkter Aufruf von new HTMLTimeElement() ist nicht erlaubt.

Parameter

Name	Typ	Default	Beschreibung
$dateTime	string	""	Eigenschaft (lesen/schreiben). Spiegelt das Attribut `datetime` wider. Gültige Formate u. a. `2024-05-12`, `14:30`, `2024-05-12T14:30:00+02:00`, `2024-W20` oder Dauern wie `PT1H15M`.

Rückgabewert

Typ

HTMLTimeElement

Beschreibung

Das DOM-Objekt eines <time>-Elements, erhältlich über document.createElement("time") oder DOM-Abfragen.

Beispiele

Element erzeugen und Zeitwert setzen

const published = new Date("2024-05-12T14:30:00Z");

const time = document.createElement("time");
time.dateTime = published.toISOString();
time.textContent = published.toLocaleDateString("de-DE", {
  day: "numeric",
  month: "long",
  year: "numeric"
});

document.querySelector(".post-meta").append(time);
console.log(time.outerHTML);

Relative Zeitangaben dynamisch anzeigen

// HTML: <time datetime="2024-05-12T14:30:00Z">12.05.2024</time>
const rtf = new Intl.RelativeTimeFormat("de", { numeric: "auto" });

const updateRelativeTimes = () => {
  document.querySelectorAll("time[datetime]").forEach((el) => {
    const diffMs = new Date(el.dateTime) - Date.now();
    const diffMin = Math.round(diffMs / 60000);
    if (Math.abs(diffMin) < 60) {
      el.textContent = rtf.format(diffMin, "minute");
    } else if (Math.abs(diffMin) < 1440) {
      el.textContent = rtf.format(Math.round(diffMin / 60), "hour");
    } else {
      el.textContent = rtf.format(Math.round(diffMin / 1440), "day");
    }
    el.title = new Date(el.dateTime).toLocaleString("de-DE");
  });
};

updateRelativeTimes();
setInterval(updateRelativeTimes, 60_000);

z. B. „vor 3 Tagen“ als Textinhalt

Typprüfung und Auslesen eines vorhandenen Elements

// HTML: <time id="start" datetime="2024-09-01T19:00">1. September, 19 Uhr</time>
const el = document.getElementById("start");

if (el instanceof HTMLTimeElement) {
  console.log(el.dateTime);                  // maschinenlesbar
  console.log(el.textContent);               // menschenlesbar
  console.log(el.getAttribute("datetime")); // identisch zu dateTime
}

2024-09-01T19:00 1. September, 19 Uhr 2024-09-01T19:00

// Wichtig · Fallstricke

Keine Validierung: dateTime akzeptiert beliebige Strings. Ungültige Werte führen zu keinem Fehler, new Date(el.dateTime) liefert dann aber Invalid Date – vor der Verarbeitung immer mit Number.isNaN(date.getTime()) prüfen.
Leerer Wert ohne Attribut: Fehlt datetime, gibt dateTime einen leeren String zurück, nicht den Textinhalt.
Zeitzonen: Werte ohne Offset (z. B. 2024-09-01T19:00) werden von Date als lokale Zeit interpretiert. Für eindeutige Zeitstempel Z oder einen Offset angeben.
Schreibweise: Die Eigenschaft heißt dateTime (Binnenmajuskel), das Attribut datetime. el.datetime ist undefined.
Kompatibilität: In allen aktuellen Browsern verfügbar (Chrome 62+, Firefox 22+, Safari 10+, Edge 79+). Sehr alte Browser behandelten <time> als HTMLUnknownElement.
Das Element hat keine visuelle Standarddarstellung; es beeinflusst nur Semantik und Barrierefreiheit.

Siehe auch

Date HTMLPreElement HTMLTitleElement HTMLBaseElement HTMLDivElement