HTMLTimeElement.dateTime — Eigenschaft · JavaScript-Referenz

Signatur

HTMLTimeElement.dateTime

Beschreibung

Die Eigenschaft dateTime der Schnittstelle HTMLTimeElement spiegelt das Attribut datetime eines <time>-Elements wider. Sie enthält eine maschinenlesbare Zeichenkette für Datum, Uhrzeit oder Dauer. Den für Menschen lesbaren Text zeigt das Element selbst an, zum Beispiel „gestern Abend“ oder „3. März 2024“.

Gültige Formate sind unter anderem:

Jahr/Monat/Tag: 2024, 2024-03, 2024-03-15
Jahrestag ohne Jahr: 03-15
Uhrzeit: 14:30, 14:30:15.250
Lokales Datum mit Uhrzeit: 2024-03-15T14:30 (T oder Leerzeichen als Trenner)
Mit Zeitzone: 2024-03-15T14:30Z, 2024-03-15T14:30+01:00
Kalenderwoche: 2024-W11
Dauer: PT2H30M oder 2h 30m

Die Eigenschaft eignet sich gut, um aus einem Skript Zeitangaben zu lesen, etwa für relative Anzeigen wie „vor 5 Minuten“, zum Sortieren oder Filtern. Man kann sie auch setzen, um ein Element nachträglich zu aktualisieren. Suchmaschinen, Feed-Reader und Hilfstechnologien werten den Attributwert ebenfalls aus.

Fehlt das Attribut, gibt dateTime eine leere Zeichenkette zurück. Der Maschinenwert steckt in diesem Fall im Textinhalt des Elements, und den musst du selbst auslesen.

Rückgabewert

Typ

string

Beschreibung

Der aktuelle Wert des Attributs datetime. Fehlt das Attribut, ist es eine leere Zeichenkette "". Beim Setzen wird der Wert unverändert als Attribut geschrieben.

Beispiele

Datum auslesen und in ein Date-Objekt umwandeln

// HTML: <time id="release" datetime="2024-03-15T14:30:00Z">15. März</time>
const timeEl = document.querySelector('#release');
console.log(timeEl.dateTime);

const date = new Date(timeEl.dateTime);
console.log(date.toISOString());

2024-03-15T14:30:00Z 2024-03-15T14:30:00.000Z

Relative Zeitangaben („vor 3 Stunden“) erzeugen

// HTML: <time class="rel" datetime="2024-03-15T10:00:00Z">15.03.2024</time>
const rtf = new Intl.RelativeTimeFormat('de', { numeric: 'auto' });

const updateRelativeTimes = () => {
  document.querySelectorAll('time.rel').forEach((el) => {
    if (!el.dateTime) return; // kein datetime-Attribut vorhanden
    const diffMs = new Date(el.dateTime) - Date.now();
    const hours = Math.round(diffMs / 3_600_000);
    el.textContent = Math.abs(hours) < 24
      ? rtf.format(hours, 'hour')
      : rtf.format(Math.round(hours / 24), 'day');
    el.title = new Date(el.dateTime).toLocaleString('de-DE');
  });
};

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

dateTime setzen und Textinhalt passend formatieren

const setTimestamp = (el, date) => {
  el.dateTime = date.toISOString(); // maschinenlesbar
  el.textContent = date.toLocaleDateString('de-DE', {
    day: 'numeric', month: 'long', year: 'numeric'
  }); // menschenlesbar
};

const el = document.createElement('time');
setTimestamp(el, new Date(Date.UTC(2024, 11, 24, 18, 0)));
document.body.append(el);
console.log(el.outerHTML);

<time datetime="2024-12-24T18:00:00.000Z">24. Dezember 2024</time>

Artikel nach Veröffentlichungsdatum sortieren

// HTML: mehrere <article> mit je <time datetime="...">
const list = document.querySelector('#articles');
const sorted = [...list.querySelectorAll('article')].sort((a, b) =>
  new Date(b.querySelector('time').dateTime) -
  new Date(a.querySelector('time').dateTime)
);
list.append(...sorted); // neueste zuerst

// Wichtig · Fallstricke

Keine Prüfung: Der Browser nimmt beim Setzen jede Zeichenkette an, auch ungültige wie el.dateTime = 'morgen'. Um die Gültigkeit des Formats musst du dich selbst kümmern.
Nicht jedes gültige Format versteht Date: Werte wie 03-15, 2024-W11, 14:30 oder Dauern wie PT2H ergeben mit new Date() ein Invalid Date. Prüfe das Ergebnis mit Number.isNaN(date.getTime()).
Zeitzonen: Ohne Zeitzonenangabe liest new Date('2024-03-15T14:30') den Wert als lokale Zeit, ein reines Datum wie 2024-03-15 dagegen als UTC. Für eindeutige Zeitpunkte am besten toISOString() verwenden.
Leere Zeichenkette statt null: Fehlt das Attribut, liefert dateTime "". getAttribute('datetime') gibt dagegen null zurück.
Schreibweise: Die Eigenschaft heißt dateTime (großes T), das Attribut datetime. Wer el.datetime schreibt, legt nur eine gewöhnliche Eigenschaft an und ändert nichts am Attribut.
Kompatibilität: Wird von allen aktuellen Browsern unterstützt (Chrome 62+, Firefox 22+, Safari 10+, Edge 79+). In sehr alten Browsern hilft als Ausweichlösung getAttribute('datetime').

Siehe auch

AnimationPlaybackEvent.currentTime HTMLIFrameElement.privateToken HTMLModElement.dateTime HTMLAreaElement.pathname HTMLImageElement.name