Temporal

Browserunterstützung
caniuse.com

Das Temporal API ist dazu gedacht, das Date-Objekt durch eine Familie anderer Objekte zu ersetzen, die besser mit Zeitzonen, nicht-gregorianischen Kalendern und Zeitdifferenzen umgehen können. Eine Erweiterung von Date um entsprechende Funktionen wurde nicht als sinnvoll erachtet. Statt dessen ging man den gleichen Weg wie Java, wo in Version 8 die Date- und Time-Klassen aus java.util durch ein neues java.time Package abgelöst wurden.

Die Objekte des Temporal API sind ähnlich benannt, im Detail aber anders aufgebaut. Die Implementierung in den Browsern ist noch nicht abgeschlossen, bitte prüfe vor der Verwendung zunächst die Kompatibilitätsangaben.

Einen browsergeeigneten Polyfill gibt es von FullCalendar unter der Adresse https://cdn.jsdelivr.net/npm/temporal-polyfill@0.3.0/global.min.js. Aus Datenschutzgründen bitte nie von dort in deine Seite einbinden, sondern herunterladen und selbst hosten!

Einführung

Die Grundlage des Temporal API ist die Klasse Temporal.Instant, die einen bestimmten Zeitpunkt beschreibt. Offiziell ist dieser Zeitpunkt frei von Kalender- oder Zeitzoneninformationen, praktisch ist ein Instant aber genau wie Date auf die Unix-Epoche (01.01.1970, Mitternacht) bezogen und wird durch die Nanosekunden beschrieben, die seitdem vergangen sind (oder bis dahin vergehen müssen).

Um zu bestimmen, welchem Datum oder welcher Zeit ein Instant entspricht, muss er mit einer Zeitzone und einem Kalender kombiniert werden. Dazu besitzt das Instant-Objekt die Methode toZonedDateTimeISO(), die eine Zeitzonenangabe (entweder ein Kürzel wie CET oder eine Ortsangabe wie Europe/Berlin) erwartet und den Instant in dieser Zeitzone auf Basis des ISO-8601 Kalenders (gregorianisch) darstellt. Das Ergebnis ist ein Temporal.ZonedDateTime-Objekt. Die Umrechnung in andere Kalendersysteme ist möglich, erfordert aber den Aufruf einer der with...-Methoden des ZonedDateTime-Objekts.

Um Zeitdifferenzen zu beschreiben, wurde die Klasse Temporal.Duration eingeführt. Sie beschreibt eine Zeitdauer in Kalenderbegriffen (z.B. Jahre, Tage, Stunden oder Sekunden), ist aber nicht auf einen bestimmtem Kalender ausgerichtet. Dieser Bezug wird hergestellt, wenn eine Duration verwendet wird, um eine kalenderbezogene Datums- oder Zeitangabe zu verändern.

Darüber hinaus gibt es eine Gruppe von Klassen, die zwar kalenderbasierend sind, aber weder Zeitzonen noch Zeitumstellungen beachten. Dies sind: PlainDate (nur Datum), PlainTime (Zeit ohne Datum), PlainDateTime (die Kombination von beiden) sowie PlainMonthDay (nur Monat und Tag) und PlainYearMonth (nur Jahr und Monat). Letztere eignen sich vor allem zur Darstellung von Aussagen wie „Am 24.12. ist Weihnachten“ oder „Im Juli 2026 verreisen wir“.

Außerdem gibt es die Helferklasse Temporal.Now, die fünf Methoden zum Abruf des aktuellen Moments in unterschiedlichen Repräsentationen (Instant, PlainDate, PlainDateTime, PlainTime und ZonedDateTime) sowie die Abfrage der Zeitzone des Computers ermöglicht.

Vorteile der Temporal-Klassen

• Ein Date-Objekt kann über set-Methoden verändert werden, was böse Überraschungen auslösen kann. Die Temporal-Objekte sind hingegen unveränderlich. Wenn ich zu einem ZonedDateTime-Objekt eine Stunde addiere, bekomme ich ein neues Objekt, ähnlich wie bei DateTimeImmutable in PHP.
• Der Januar ist Monat 0? Nicht bei Temporal, hier werden die Monate so, wie man es erwartet, ab 1 nummeriert.
• Zeitzonen können mit Hilfe der aus PHP bekannten Zeitzonenbezeichnungen angegeben werden. Entweder als Kürzel (CET=Central European Time) oder als Ortsbezeichnung der IANA Zeitzonendatenbank (Europe/Berlin).

Instant, Plain oder Zoned?

Die Vielzahl der verfügbaren Klassen erfordert die Entscheidung, welche Klasse für einen bestimmten Zweck die richtige ist.

• Die Instant-Klasse beschreibt einen Zeitpunkt, ohne Bezug zu einem Kalender. Man kann Instants nicht sinnvoll ausgeben (außer als Nanosekunden seit dem 01.01.1970), aber vergleichen, Differenzen bilden (in Nanosekunden), und sie durch Angabe einer Zeitzone auch in ein ZonedDateTime-Objekte umrechnen.
• Die PlainDate-Klasse enthält weder eine Zeit noch eine Zeitzone. Sie repräsentiert ein Datum in dem zugeordneten Kalender und kann damit für alle Anlässe verwendet werden, wo die Zeit irrelevant ist. Wenn ich berechnen will, welches Datum in 5 Tagen ist, muss ich mich nicht darum kümmern, ob dazwischen vielleicht die Sommerzeit begonnen hat und ich deshalb 60 Minuten extra addieren muss.
• Mit PlainTime erhält man ein Objekt, das nur die Uhrzeit speichert, unabhängig vom Datum und unabhängig von Zeitumstellungen.
• Die Klasse PlainDateTime kombiniert PlainDate und PlainTime zu einem Zeitpunkt, der aber immer noch unabhängig von Zeitzonen ist. Für Zeitpunkte der lokalen Zeit geeignet.
• Für Zeitangaben der realen Welt, für die ein Kalender und eine Zeitzone von bedeutung ist, verwendet man ZonedDateTime.

Gemeinsame Konzepte

Kalender

Temporal unterstützt die Kalender, deren IDs von Intl.supportedValuesOf('calendar') zurückgegeben werden. Teils kann die Kalender-ID bei der Objektkonstruktion angegeben werden, teils muss zunächst der ISO 8601-Kalender (was im Wesentlichen dem gregorianischen Kalender entspricht) verwendet und dann auf den gewünschten Kalender umgestellt werden.

Stringformat für die Erzeugung von Temporal-Objekten

Temporal-Objekte können unter anderem aus geeignet aufgebauten Strings erstellt werden. Das Format dieser Strings basiert auf der ISO 8601-Norm und ist grundsätzlich aus dem Date-Konstruktor bekannt.

Ein Datum wird in der Reihenfolge Jahr, Monat und Tag aufgeschrieben. Dabei ist

• das Jahr vierstellig oder sechsstellig.
  • Sechsstellige Jahresangaben sind eine Erweiterung zu ISO 8601. Zur Unterscheidung muss das Vorzeichen geschrieben werden und das Datum muss im Bereich -271821-04-01 bis +275760-09-30 liegen.
• der Monat zweistellig im Bereich 01 bis 12
• der Tag zweistellig im Bereich 01 bis 28, 29, 30 oder 31, je nach Monat
• Optional' kann zwischen den Werten für Jahr, Monat und Tag ein Minuszeichen gesetzt werden
• Je nach Kalender ist für PlainYearMonth die Angabe eines Tages und für PlainMonthDay die Angabe eines Jahres optional.

Beispiele:

   2025-10-15
   +002364-09-28
   19950604

Eine Uhrzeit wird in der Reihenfolge Stunden, Minuten, Sekunden und Sekundenbruchteile aufgeschrieben. Dabei sind

• die Stunden zweistellig im Bereich 00 bis 23
• die Minuten zweistellig im Bereich 00 bis 59
• die Sekunden zweistellig im Bereich 00 bis 59
• die Sekundenbruchteile ein- bis neunstellig. Zwischen Sekunden und Sekundenbruchteilen muss ein Punkt oder Komma notiert werden
• Optional kann zwischen den Stunden, Minuten und Sekunden ein Doppelpunkt gesetzt werden. Für die Angabe von Sekundenbruchteilen ist der Doppelpunkt aber Pflicht.

Beispiele:

   12:00:00
   173015
   04:10:22.876554

Die Angabe von Datum und Uhrzeit in einem String ist möglich. Hierfür wird zuerst das Datum notiert, dann ein T, t oder Leerzeichen als Trennzeichen, und dann die Uhrzeit.

Beachte: Die Erzeugung eines PlainTime-Objekts aus "123010" scheitert in Chrome, weil dies auch eine Angabe für Monat+Tag sein könne. Was zwar Blödsinn ist, aber der Hintergrund scheint zu sein, dass ein ISO-String mit Datum und Uhrzeit eine legale Quelle für PlainTime sein kann und das Suchmuster für "Monat+Tag" auf die ersten 4 Stellen von "123010" zutrifft. Aus "1232" lässt sich hingegen problemlos ein PlainTime erzeugen, weil der 32.12. nicht existiert.

Beschwerden dagegen bitte an die Temporal-Autoren richten, nicht an Selfhtml.

Empfehlung: Uhrzeit-Strings für PlainTime immer mit einem vorangestellten T übergeben.

Außer Datum und Zeit kann ein Temporal-String noch weitere Angaben enthalten: Zeitverschiebung, Zeitzone und Kalender.

Die Zeitverschiebung (Offset) ist die Abweichung der angegebenen Zeit von der UTC. Sie wird direkt an die Uhrzeit angehängt und besteht entweder aus einem Z (oder z) oder aus einer Abweichung im Format +HH:MM oder +HH:MM. HH sind die Stunden, MM die Minuten. Ein Z bedeutet, dass die Zeitangabe ohne Zeitzone als UTC erfolgt, was nicht das gleiche ist wie +00:00.

Beispiel:

   2026-02-26T12:13:00+02:00

Ein solcher String kann als Eingabe für einen Instant verwendet werden. Für die Erzeugung von ZonedDateTime-Objekten sollte eher auf die Angabe einer Zeitzone zurückgegriffen werden.

Die Zeitzone ist entweder ein Zeitzonenkürzel wie CET (Central European Time) oder eine Ortsangabe wie Europe/Berlin. Sie wird in eckige Klammern gesetzt und folgt auf Uhrzeit und ggf. Zeitverschiebung. Gibt man eine Zeitverschiebung (außer Z) und eine Zeitzone an, prüft Temporal, ob die Verschiebung zur Zone passt. Lässt man die Verschiebung weg, wird sie bedarfsweise aus der Zonenangabe ermittelt.

Der Kalender wird ähnlich einer Locale-Kalenderergänzung (u-ca) notiert und ebenfalls in eckige Klammern gesetzt. Hinter u-ca folgt ein Gleichheitszeichen und die Kalender-ID.

Beispiel:

   2027-05-25T17:00:00[CET][u-ca=hebrew]

Die eigentliche Datums- und Zeitangabe erfolgt im ISO-Format, d.h. basierend auf dem gregorianischen Kalender. Wird aus diesem String ein ZonedDateTime-Objekt erstellt, würde man darin das Jahr 5787 vorfinden, den Monat 9 und den Tag 18.

Erzeugung

Die Spezifikation beschreibt Konstruktoraufrufe für alle Temporal-Klassen, die Implementierung ist aber unvollständig. Deshalb ist new noch nicht einsetzbar.

Statt dessen verfügen alle Temporal-Klassen über eine statische from-Methode, die je nach Klasse mit unterschiedlichen Parametern aufrufbar ist.

Temporal.PlainDate

Ein PlainDate-Objekt kann auf unterschiedliche Arten erzeugt werden:

- Mittels new Temporal.PlainDate(jahr,monat,tag,kalender) – bislang nur im Firefox. Die Angabe der Kalender-ID ist optional, Default ist der ISO 8601-Kalender.

Erzeugen eines Temporal.PlainDate-Objekts

// Aus einem ISO-String
const ostern1 = Temporal.PlainDate.from("2026-04-05");

// Aus einem Objekt mit den Einzelwerten
const ostern2 = Temporal.PlainDate.from({ year: 2026, month: 4, day: 5 });

// Mit Hilfe des Konstruktors, ähnlich wie Date, aber mit "richtigem" Monat
const ostern3 = new Temporal.PlainDate(2026, 4, 5);

// Das heutige Datum
const heute = Temporal.Now.plainDateISO();

// Ausgeben 
console.log(heute.toString());              // Als ISO-String YYYY-MM-DD (2026-02-24)
console.log(heute.toLocaleString());        // Passend zum Default-Locale (24.2.2026)
console.log(heute.toLocaleString("en-US")); // Mit bestimmtem Locale (2/24/2026)

Die einzelnen Komponenten eines PlainDate (year, month, day, etc) sind über Eigenschaften verfügbar, dazu auch abgeleitete Werte wie Wochentag (dayOfWeek), Tagesnummer im Jahr (dayOfYear), Kalenderwoche (weekOfYear) und Kontextinformationen wie Tage im Monat (daysInMonth), Tage im Jahr (daysInYear) und ob ein Schaltjahr vorliegt (inLeapYear).

Diese Eigenschaften können nur gelesen werden, weil Temporal-Objekte unveränderlich sind. Man kann aber eine modifizierte Kopie erstellen, dazu dient die with-Methode. Man übergibt ihr ein Objekt mit den Komponenten, die geändert werden sollen. Bei einem PlainDate sind das vor allem year, month und day:

Ändern eines PlainDate auf den letzten Tag im Monat

const datum = Temporal.PlainDate.from("2026-05-01");
const eom   = datum.with( { day: datum.daysInMonth } );

Siehe auch

• MDN: Temporal Standardobjekt (automatisch übersetzt)

TC39: Entwurf der Temporal-Spezifikation, abgerufen 25.02.2026