Signatur
Beschreibung
Der Konstruktor Temporal.ZonedDateTime() erstellt ein unveränderliches Objekt, das einen exakten Zeitpunkt mit einer Zeitzone und einem Kalender verbindet. Damit ist es der vollständigste Datums- und Zeittyp der Temporal-API: Er kennt Wandzeit, UTC-Offset und die Regeln zur Sommerzeit der jeweiligen Zeitzone.
Der Konstruktor ist bewusst sehr einfach gehalten. Er erwartet den Zeitpunkt als BigInt in Nanosekunden seit dem 1. Januar 1970, 00:00 UTC. Er eignet sich daher vor allem, wenn du bereits einen exakten Zeitstempel hast, etwa aus einer Datenbank, einem Protokoll oder aus Temporal.Instant.
Im Alltag nimmt man meist die komfortableren Wege: Temporal.ZonedDateTime.from() für Strings wie "2024-03-31T02:30[Europe/Berlin]" oder für Objekte mit Feldern, Temporal.Now.zonedDateTimeISO() für die aktuelle Zeit oder instant.toZonedDateTimeISO(tz). Der Konstruktor muss mit new aufgerufen werden. Ohne new wirft er einen TypeError.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $epochNanoseconds Pflicht | bigint | Exakter Zeitpunkt in Nanosekunden seit der Unix-Epoche. Muss ein BigInt sein (z. B. 0n). Erlaubt ist der Bereich ±108 Tage, also ±8,64·1021 ns. |
|
| $timeZone Pflicht | string | Kennung der Zeitzone: ein IANA-Name wie "Europe/Berlin", "UTC" oder ein fester Offset wie "+05:30". Offsets mit Sekundenanteil sind nicht erlaubt. |
|
| $calendar | string | "iso8601" | Kalender-Kennung, z. B. "gregory", "japanese", "hebrew". Fehlt die Angabe, wird der ISO-8601-Kalender benutzt. |
Rückgabewert
Temporal.ZonedDateTime-Objekt für den angegebenen Zeitpunkt in der angegebenen Zeitzone und dem angegebenen Kalender.Beispiele
Unix-Epoche in UTC
const epoch = new Temporal.ZonedDateTime(0n, "UTC");
console.log(epoch.toString());
console.log(epoch.year, epoch.offset);Zeitstempel aus der Datenbank (Millisekunden) in Berliner Zeit umrechnen
// Die Datenbank speichert Millisekunden seit der Epoche
const msFromDb = 1_700_000_000_000;
const ns = BigInt(msFromDb) * 1_000_000n;
const berlin = new Temporal.ZonedDateTime(ns, "Europe/Berlin");
console.log(berlin.toString());
console.log(berlin.toLocaleString("de-DE", { dateStyle: "full", timeStyle: "short" }));Gleicher Zeitpunkt – andere Zeitzone und anderer Kalender
const tokyo = new Temporal.ZonedDateTime(0n, "Asia/Tokyo", "japanese");
console.log(tokyo.toString());
const india = new Temporal.ZonedDateTime(0n, "+05:30");
console.log(india.toString());
// Beide beschreiben denselben exakten Zeitpunkt
console.log(tokyo.epochNanoseconds === india.epochNanoseconds);Typische Fehler abfangen
const tryCreate = (ns, tz) => {
try {
return new Temporal.ZonedDateTime(ns, tz).toString();
} catch (err) {
return `${err.name}: ${err.message}`;
}
};
console.log(tryCreate(0, "UTC")); // Number statt BigInt
console.log(tryCreate(0n, "Mars/Olympus")); // unbekannte Zeitzone// Wichtig · Fallstricke
- Nur
BigInt:epochNanosecondsmuss einBigIntsein. EinNumber-Wert wieDate.now()führt zu einemTypeError. Wandle Millisekunden deshalb so um:BigInt(ms) * 1_000_000n. - Einheit prüfen: Temporal rechnet in Nanosekunden,
Datein Millisekunden. Wer den Faktor 106 vergisst, landet stillschweigend im Januar 1970. - Ungültige Werte: Unbekannte Zeitzonen, Offsets mit Sekundenanteil, unbekannte Kalender und Zeitpunkte außerhalb des erlaubten Bereichs führen zu einem
RangeError. - Keine Wandzeit-Eingabe: Der Konstruktor nimmt keine Werte wie „31.03.2024, 02:30 Uhr“ entgegen. Für solche Wandzeiten und die Auflösung von Sommerzeit-Lücken oder -Überschneidungen (Option
disambiguation) nimmTemporal.ZonedDateTime.from(). - Zeitzonendaten: Die Offsets kommen aus der IANA-Datenbank des Browsers bzw. der Laufzeitumgebung. Deshalb können sie sich zwischen Versionen leicht unterscheiden.
- Kompatibilität: Temporal ist noch nicht in allen Umgebungen verfügbar, zum Beispiel noch nicht in Safari und älteren Node.js-Versionen. Prüfe das mit
typeof Temporal !== \"undefined\"und binde bei Bedarf ein Polyfill ein, etwa@js-temporal/polyfillodertemporal-polyfill.