Temporal — das neue JavaScript Feature

Herausforderungen mit Zeitangaben in JavaScript

Im Frontend waren Zeitangaben häufig mit Frustration verbunden — denn es ist nicht einfach Zeitangaben und Zeitspannen fehlerfrei zu implementieren. Das lag bisher zum Beispiel daran, dass das native Date-Objekt in JavaScript veraltet ist, aber auch an praktischen Hürden, wie zum Beispiel aufgrund von unterschiedlichen Zeitzonen (JavaScript verwendet standardmäßig die lokale Zeitzone des Browsers) des Servers, des Clients und der Nutzer*innen. In diesem Artikel zeigen wir praxisnah, wie die Implementierung von Zeitangaben mittels des neuen JavaScript-Features Temporal funktioniert. 

Nehmen wir zuerst ein Datum, z. B. den 10. Juni 2025. Wir speichern es in JavaScript, um es im nächsten Schritt auf einer Website darzustellen. Dafür greifen wir normalerweise auf die Date-API zurück und erstellen ein neues Datumsobjekt wie dieses:

Wir stoßen jedoch schnell auf Probleme, wenn wir versuchen, mit diesem Objekt zu arbeiten. Wenn wir es anzeigen, erhalten wir etwas unerwartete Ergebnisse. Wenn wir in Hamburg, Deutschland, sind, lautet das angezeigte Datum:

In einem anderen Teil der Welt, zum Beispiel in Los Angeles, bekommen wir stattdessen:

Auch wenn nur ein Datum angegeben wird, fügt die Datums-API immer eine Zeitkomponente hinzu. Beim Ausgeben des Datums konvertiert die API in die Systemzeitzone der Benutzer*in.

Wir können versuchen, dieses Problem zu umgehen, indem wir z. B. das Originaldatum explizit im ISO-Format ausgeben:

Dies ist möglicherweise nicht das gewünschte Ausgabeformat, da die Benutzer*innen eher mit dem Format ihres Gebietsschemas vertraut sind. Stattdessen können wir die Methode  toLocaleDateString, um das Datum in einem bestimmten Gebietsschema zu formatieren:

Diese wird wiederum in der Systemzeitzone des Benutzers ausgegeben. In Hamburg ist dies:

Und in Los Angeles:

Lasst uns eine bestimmte Zeitzone erzwingen, in diesem Fall UTC, da wir nicht an der Zeit interessiert sind:

Und endlich bekommen wir das gewünschte Ergebnis:

Man muss sich all dieser Eigenheiten der Date-API bewusst sein, nur um ein Datum zu erzeugen und dabei die Zeitkomponente zu ignorieren.

Hit-Liste des schlechten Designs der Date-API

1. Begrenzte Unterstützung von Zeitzonen:
   UTC und die Systemzeitzone des Benutzers. Das sollte doch reichen, oder?
2. Veränderlichkeit:
   Vergiss nicht, das Datumsobjekt zu klonen, sonst musst du die Konsequenzen tragen.
3. Wenige API-Methoden auf hoher Ebene:
   Du möchtest Berechnungen mit Datumsangaben durchführen? Viel Glück!
4. Design-Ungereimtheiten:
   Null-basierte Monate und das berüchtigte getYear, kommt das bekannt vor?

Es ist Zeit für Temporal

Lasst uns all diese Probleme lösen, indem wir zur Temporal API wechseln:

Dies speichert ein Datum ohne die Zeitkomponente, daher der Name „einfaches“ Datum.

Der Aufruf der Methode toLocaleString liefert sofort das gewünschte Ergebnis, ohne dass wir uns um Zeitzonenprobleme kümmern müssen:

Kalendertag

PlainDate ist nützlich, um ein Ereignis zu speichern, das an einem bestimmten Kalendertag stattfindet, z. B. die Osterfeiertage:

Reale Uhrzeit

Das Äquivalent für die reale Uhrzeit ist PlainTime,  z. B. für die Speicherung eines Weckers, der sich nicht mit den Zeitzonen ändern soll:

Kalendertag und reale Uhrzeit

Kombiniere beides und erhalte PlainDateTime, eine von der Zeitzone unabhängige Darstellung von Datum und Uhrzeit:

Kalendertag und Monat 

Um ein wiederkehrendes Ereignis zu speichern, das jedes Jahr am gleichen Tag stattfindet, ist PlainMonthDay sehr nützlich

Kalenderjahr und Monat

Und die letzte einfache API lautet PlainYearMonth zur Speicherung eines ganzen Monats für ein bestimmtes Jahr:

Zeitzonen: Die nächste Hürde

Aber manchmal kommt man nicht umhin, Zeitzonen zu berücksichtigen. Fügen wir unserem Datum eine Zeitkomponente hinzu — 10. Juni 2025, 19:00, Europa/Berlin — und verwenden Temporal, um es zu speichern:

Der Aufruf der Methode toLocaleString gibt das Datum immer in der ursprünglich angegebenen Zeitzone aus:

Natürlich ist es möglich, eine andere Zeitzone einzustellen, z. B. um das Datum und die Uhrzeit einer Online-Veranstaltung in einer für die Benutzer*innen besser geeigneten Zeitzone anzuzeigen:

Ein wichtiger Punkt ist die Unveränderlichkeit von Temporal-Objekten. Jedes Mal, wenn man eine Methode aufruft, die das Datum oder die Uhrzeit ändert, wird ein neues Temporal-Objekt zurückgegeben, während das Original unverändert bleibt.

Definitive Zeitspannen

Bis jetzt bietet Temporal einen sauberen und intuitiven API-Ersatz für Date. Etwas völlig Neues in JavaScript sind dagegen Objekte, die sich auf eine Dauer beziehen:

Wir können diese auch mit der Methode toLocaleString in einem etwas praxisnäheren Format ausgeben:

Zeiträume (Dauern) können in Zahlen umgewandelt werden, um sie in bestehenden JavaScript-Methoden zu verwenden, die keine Temporal-Objekte akzeptieren:

Computer, bitte füge 2 Tage hinzu

In Verbindung mit anderen Temporal-APIs können Zeiträume für Datums- und Zeitberechnungen verwendet werden:

Wie viele Tage bis Halloween?

Umgekehrt bieten Temporal Plain und Zoned APIs Methoden zur Berechnung einer Dauer:

String Theorie

Zeitliche APIs arbeiten mit einem definierten ISO-Format für Daten, Zeiten und Zeiträume. Keine seltsamen Parsing-Probleme mehr wie bei der Date-API.

Je nachdem, welche API verwendet wird, sind nicht alle Komponenten erforderlich, z. B. verwendet PlainDate nur die Datumskomponente.

Diese serialisierten Darstellungen von Datum, Uhrzeit und Dauer sind nützlich bei der Kommunikation mit Backend-APIs, für die ein standardisiertes Format erforderlich ist. Für die interne Verwendung in JavaScript können Objekte anstelle von ISO-Strings verwendet werden:

Temporal: Es gibt so viel mehr

Dieser Artikel kratzt nur an der Oberfläche der neuen Temporal APIs. Die umfassendste Dokumentation mit vielen Beispielen ist auf MDN verfügbar. Die technischen Spezifikationen sind auf der TC39-Website zu finden.