Signatur
Beschreibung
Temporal.ZonedDateTime kombiniert einen absoluten Zeitpunkt (wie Temporal.Instant) mit einer IANA-Zeitzone (z. B. "Europe/Berlin") und einem Kalender. Dadurch werden Datum und Uhrzeit immer korrekt in der lokalen Zeit der Zeitzone dargestellt – inklusive Sommerzeit-Übergängen, Schaltsekunden und anderen Eigenheiten.
Im Gegensatz zu Temporal.PlainDateTime kennt ZonedDateTime seinen genauen UTC-Offset und kann daher für alle Berechnungen genutzt werden, bei denen der tatsächliche globale Zeitpunkt relevant ist – etwa für Kalendereinträge, Scheduler oder Zeitstempel in verteilten Systemen.
Ein Temporal.ZonedDateTime-Objekt ist unveränderlich (immutable). Alle Methoden, die Werte modifizieren, geben neue Instanzen zurück. Die Zeitzone wird als IANA-Bezeichner oder UTC-Offset übergeben. Berechnungen wie add(), subtract() und until() berücksichtigen automatisch die Zeitzonenregeln.
- Verwende
ZonedDateTime, wenn du Zeitzone + Datum + Uhrzeit zusammen brauchst. - Verwende
Temporal.PlainDateTime, wenn die Zeitzone keine Rolle spielt. - Verwende
Temporal.Instant, wenn nur der absolute Zeitpunkt zählt.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $epochNanoseconds Pflicht | BigInt | Der absolute Zeitpunkt als Anzahl Nanosekunden seit dem Unix-Epoch (1970-01-01T00:00:00Z). | |
| $timeZone Pflicht | string | Temporal.TimeZone | IANA-Zeitzonenbezeichner (z. B. "Europe/Berlin") oder UTC-Offset-String (z. B. "+02:00"). |
|
| $calendar | string | Temporal.Calendar | "iso8601" | Kalender-ID (z. B. "iso8601", "gregory", "islamic"). Standard ist der ISO-8601-Gregorianische Kalender. |
Rückgabewert
Temporal.ZonedDateTime-Instanz, die den angegebenen Zeitpunkt in der angegebenen Zeitzone repräsentiert.Beispiele
ZonedDateTime erstellen und Felder auslesen
// Aktuellen Zeitpunkt als ZonedDateTime in der Berliner Zeitzone
const now = Temporal.Now.zonedDateTimeISO('Europe/Berlin');
console.log(now.year); // z. B. 2024
console.log(now.month); // z. B. 6
console.log(now.day); // z. B. 15
console.log(now.hour); // z. B. 14
console.log(now.timeZoneId); // "Europe/Berlin"
console.log(now.offset); // z. B. "+02:00"
console.log(now.toString()); // "2024-06-15T14:30:00+02:00[Europe/Berlin]"Aus ISO-String parsen, Datum addieren und in UTC konvertieren
// ZonedDateTime aus ISO-String parsen
const meeting = Temporal.ZonedDateTime.from(
'2024-03-31T01:00:00+01:00[Europe/Berlin]'
);
console.log(meeting.toString());
// Sommerzeit-Umstellung: 2 Wochen addieren
const twoWeeksLater = meeting.add({ weeks: 2 });
console.log(twoWeeksLater.toString());
// Als Instant (UTC) ausgeben
console.log(twoWeeksLater.toInstant().toString());
// Differenz berechnen
const diff = twoWeeksLater.since(meeting);
console.log(diff.toString()); // PT336H (14 Tage in Stunden)Zeitzone wechseln und Vergleich
const berlin = Temporal.ZonedDateTime.from(
'2024-07-01T12:00:00+02:00[Europe/Berlin]'
);
// In New Yorker Zeit umwandeln
const newYork = berlin.withTimeZone('America/New_York');
console.log(newYork.toString());
// Sind beide der gleiche Moment?
console.log(Temporal.ZonedDateTime.compare(berlin, newYork) === 0); // true
// Lokale Stunde in New York
console.log(newYork.hour); // 6// Wichtig · Fallstricke
Browser-Kompatibilität: Temporal befindet sich derzeit im TC39 Stage-3-Proposal. Zum produktiven Einsatz ist ein Polyfill (z. B. @js-temporal/polyfill) erforderlich. Native Unterstützung ist in modernen Browsern in Vorbereitung.
Sommerzeit-Fallstricke: Beim Übergang zur Sommerzeit (Uhren vor) kann eine lokale Uhrzeit ungültig oder mehrdeutig sein. ZonedDateTime.from() erlaubt es, das Verhalten mit der Option disambiguation zu steuern ("compatible", "earlier", "later", "reject").
Epoch-Nanosekunden: Der Konstruktor erwartet einen BigInt für Nanosekunden-Genauigkeit. Für die meisten Anwendungsfälle ist Temporal.ZonedDateTime.from() oder Temporal.Now.zonedDateTimeISO() praktischer.
Unveränderlichkeit: Jede Mutation erzeugt eine neue Instanz. Das Objekt ist vollständig immutable und damit thread-safe und gut für funktionale Muster geeignet.