Temporal/ZonedDateTime

Browserunterstützung
caniuse.com

Ein Temporal.ZonedDateTime-Objekt repräsentiert einen eindeutigen Zeitpunkt, in Nanosekundengenauigkeit (im Rahmen der Möglichkeiten des verwendeten Computers), mit Bezug auf eine IANA Zeitzone und einen Kalender.

Durch die Verbindung von Instant mit Zeitzone und Kalender können ZonedDateTime-Objekte korrekte Datums- und Zeitberechnungen durchführen und passend für unterschiedliche Kulturen dargestellt werden.

Der einem ZonedDateTime-Objekt zu Grunde liegende Instant lässt sich mit der Methode toInstant() abrufen, die verwendete Zeitzone und der verwendete Kalender finden sich in dem schreibgeschützten Eigenschaften timezoneId und calendarId.

Erzeugen eines Temporal.ZonedDateTime

Um ein ZonedDateTime-Objekt zu erhalten, kann man

• Mittels Temporal.ZonedDateTime.from(zonedDateTime) ein anderes ZonedDateTime-Objekt klonen
• Mittels Temporal.ZonedDateTime.from(string) einen RFC 9557-String in ein ZonedDateTime-Objekt konvertieren
• Mittels Temporal.ZonedDateTime.from(info, options) aus einem flachen Objekt mit Konstruktionsdaten ein ZonedDateTime-Objekt erzeugen (siehe unten)

• Mittels new Temporal.ZonedDateTime(epochNanoseconds, timeZone, calendar) aus den Nanosekunden seit Beginn der Unix-Epoche (01.01.1970) ein neues ZonedDateTime erzeugen (derzeit nur in Firefox

• Aus einem Instant, einem PlainDate oder einem PlainDateTime mit der Methode instant.toZonedDateTimeISO(timezone) ein ZonedDateTime-Objekt erzeugen.

• von Temporal.Now.zonedDateTimeISO() den aktuellen Zeitpunkt erhalten, optional mit Angabe einer Zeitzone

Das flache Objekt, das man an ZonedDateTime.from übergeben kann, spezifiziert die einzelnen Komponenten eines ZonedDateTime-Objekts. Die einzelnen Datums- und Zeitkomponenten sind bei Temporal.PlainDate und Temporal.PlainTime beschrieben, hinzu kommt die verpflichtende Angabe der Eigenschaft timeZone (sic!) mit einer Zeitzone. Hier ist Aufmerksamkeit geboten, denn der Name der Eigenschaft weicht von der Eigenschaft ab, mit der man die Zeitzone im fertigen Objekt abrufen kann. Optional kann mit der Eigenschaft offset auch die Zeitverschiebung zu UTC angegeben werden, allerdings werden hier nur Offsets akzeptiert, die für das genannte Datum und die genannte Zeitzone gültig sind. Sinnlos? Nein: Beim Übergang von Sommer- zu Winterzeit gibt es die Stunde von 2-3 Uhr morgens zweimal und nur mit Offset-Angabe ist die Unterscheidung zwischen 2A und 2B Uhr möglich.

Erzeugen von ZonedDateTime-Objekten

const schabowski_moment = Temporal.ZonedDateTime.from("1989-11-09T18:57[Europe/Berlin]");
// ZonedDateTime mit Startzeit der Artemis II Mission, erstellt aus RFC 9557-String mit UTC
const artemis2_start = Temporal.ZonedDateTime.from("2026-04-01T22:35:12Z[America/New_York");
// Landezeit der Orion-Kapsel mit Ortszeit Deutschland
const orion_landung_de = Temporal.ZonedDateTime.from({ year: 2026, month: 4, day: 1, 
                                                 hour: 2, minute: 7, second: 27,
                                                 timeZone: "Europe/Berlin"});
// Umrechnen auf Zeitzone des Landeorts (San Diego, also Zonenname Los Angeles)
orion_landung_local = orion_landung_de.withTimeZone("America/Los_Angeles");
console.log(orion_landung_local.toString());
// Ausgabe: '2026-04-10T17:07:27-07:00[America/Los_Angeles]'

Was kann man damit machen

ZonedDateTime ist das leistunsfähigste Temporal-Objekt. Man kann damit Datums- und Zeitarithmetik betreiben, unter Berücksichtigung von Kalender- und Zeitzonenangaben. Aus diesem Grund besitzt ZonedDateTime eine Vielzahl von Eigenschaften und Methoden.

Eigenschaften und Vererbung

Der Prototyp für Temporal.Instant-Objekte erbt die Methoden von Object.prototype.

Darüber hinaus stellt er – in Form von get-Propertys – etliche Eigenschaften zum Abruf der Bestandteile eines ZonedDateTime bereit. Beachte, dass die Begriffe Jahr, Monat und Woche je nach verwendetem Kalender sehr unterschiedliche Werte aufweisen können.

Die nachfolgende Tabelle enthält nur Kurzinformationen zu den Datums- und Zeiteigenschaften. Die Artikel zu PlainDate und PlainTime gehen auf die Besonderheiten – vor allem bei Verwendung von nicht-iso8601 Kalendern – genauer ein.

Eigenschaft	Bedeutung
calendarId	Ein Kürzel für den verwendeten Kalender
day	Die Nummer des Tages im Monat, beginnend bei 1. Erwarte nicht, dass die Tage innerhalb eines Monats fortlaufend nummeriert sind! Je nach Kalender oder Zeitzone kann es Sprünge geben.
dayOfWeek	Die laufende Nummer des Tages in einer Kalenderwoche, von 1 bis daysInWeek.
dayOfYear	Die laufende Nummer des Tages in einem Kalenderjahr, von 1 bis daysInYear.
daysInMonth	Wieviele Tage hat der Monat, in dem sich dieses ZonedDateTime befindet
daysInWeek	Wieviele Tage hat die Woche, in der sich dieses ZonedDateTime befindet. Im ISO-Kalender und in den generell unterstützten Temporal-Kalendern ist das immer 7, dafür gibt es aber keine Garantie! Verwende den Wert dieser Eigenschaft und nicht die magische Zahl 7 in deinem Code.
daysInYear	Wieviele Tage hat das Jahr, in der sich dieses ZonedDateTime befindet. Im ISO-Kalender (solar) sind das 365 oder 366 Tage, es gibt aber auch reine Mondkalender (lunar) mit 354-355 Tagen und Mond-/Sonnenkalender (lunisolar) mit Schaltmonaten haben kurze Jahre mit 354-355 Tage und lange Jahre mit 383-385 Tagen.
epochMilliseconds	Millisekunden seit Beginn der Unix-Epoche (1.1.1970). Für Zeitpunkte vor dem Epochenbeginn ist dieser Wert negativ. Da der MAX_SAFE_INTEGER-Wert in JavaScript bei 253 liegt, besteht keine Gefahr einer Epochalypse im Jahr 2038 wie beim 32-bit time_t-Typ in Unix-Systemen. epochMilliseconds ist der durch 106 dividierte und abgerundete Wert von epochNanoseconds.
epochNanoseconds	Nanosekunden seit Beginn der Unix-Epoche (1.1.1970). Dies ist ein BigInt Wert
era	undefined für Kalender, die keine Ära verwenden, andernfalls ein kalenderspezifischer String, der die Ära in diesem Kalender bezeichnet, zu der dieses ZonedDateTime gehört. Je nach Kalendersystem sehr unterschiedlich.
eraYear	undefined für Kalender, die keine Ära verwenden. Identisch mit year für Kalender, die nur eine Ära haben (z. B. hebrew oder islamic-civil. In Kalendern mit mehreren Äras (z. B. japanese) die Jahreszahl in der jeweiligen Ära.
hour	Die Stunde am Tag, im Bereich 0-23. Beachte, dass beim Wechsel Sommer- in Winterzeit die gleiche Stunde mehrfach auftreten kann
hoursInDay	Wieviele Stunden hat dieser Tag. Normalerweise 24, beim Wechsel zwischen Winter- und Sommerzeit auch mehr oder weniger.
inLeapYear	Gibt an, ob das Jahr dieses ZonedDateTime ein Schaltjahr ist.

**in arbeit**