Temporal.Instant.prototype.toZonedDateTimeISO() — Methode · JavaScript-Referenz

Signatur

Temporal.Instant.prototype.toZonedDateTimeISO(timeZone)

Beschreibung

Ein Temporal.Instant ist ein exakter Zeitpunkt auf der globalen Zeitachse, also die Nanosekunden seit der Unix-Epoche. Er hat weder Zeitzone noch Kalender und kennt deshalb keine „Uhrzeit“ und kein „Datum“. Mit toZonedDateTimeISO() legst du fest, aus welcher Zeitzone du auf diesen Zeitpunkt schaust. Heraus kommt ein Temporal.ZonedDateTime, das Jahr, Monat, Tag, Stunde, Offset usw. kennt und immer den Kalender iso8601 verwendet.

Die Methode brauchst du immer dann, wenn du einen gespeicherten Zeitstempel (etwa aus einer Datenbank, einer API oder Temporal.Now.instant()) für einen Menschen in seiner Ortszeit anzeigen oder damit ortsbezogen rechnen willst, zum Beispiel „+1 Tag“ über eine Sommerzeitumstellung hinweg. Der exakte Zeitpunkt ändert sich dabei nicht: zdt.epochNanoseconds ist genau gleich instant.epochNanoseconds.

Als Zeitzone gehen ein IANA-Bezeichner wie "Europe/Berlin", "UTC", ein fester Offset wie "+05:30" oder ein vorhandenes Temporal.ZonedDateTime, dessen Zeitzone dann übernommen wird. Brauchst du einen anderen Kalender als ISO 8601, rufst du danach withCalendar() auf dem Ergebnis auf.

Parameter

Name	Typ	Default	Beschreibung
$timeZone Pflicht	string \| Temporal.ZonedDateTime		Die Zielzeitzone. Möglich sind ein IANA-Zeitzonenbezeichner (`"Europe/Berlin"`, `"America/New_York"`), `"UTC"`, ein Offset-String (`"+05:30"`) oder ein `Temporal.ZonedDateTime`, dessen Zeitzone übernommen wird. Ein ISO-String mit Zeitzonen-Annotation (z. B. `"2024-01-01T00:00+01:00[Europe/Berlin]"`) wird ebenfalls akzeptiert und steht dann für die Zone in der Annotation.

Rückgabewert

Typ

Temporal.ZonedDateTime

Beschreibung

Ein neues Temporal.ZonedDateTime für genau denselben Zeitpunkt, in der angegebenen Zeitzone und mit dem Kalender iso8601.

Beispiele

UTC-Zeitstempel in Berliner Ortszeit umwandeln

const instant = Temporal.Instant.from("2024-03-10T12:00:00Z");
const berlin = instant.toZonedDateTimeISO("Europe/Berlin");

console.log(berlin.toString());
console.log(berlin.hour, berlin.offset, berlin.calendarId);

2024-03-10T13:00:00+01:00[Europe/Berlin] 13 +01:00 iso8601

Derselbe Zeitpunkt in mehreren Zeitzonen (z. B. Meeting-Planer)

const meeting = Temporal.Instant.from("2024-03-10T12:00:00Z");
const zones = ["Europe/Berlin", "America/New_York", "Asia/Tokyo"];

for (const zone of zones) {
  const local = meeting.toZonedDateTimeISO(zone);
  console.log(`${zone.padEnd(18)} ${local.toPlainTime()} (${local.offset})`);
}

Europe/Berlin 13:00:00 (+01:00) America/New_York 08:00:00 (-04:00) Asia/Tokyo 21:00:00 (+09:00)

Aktuelle Zeit in der Zeitzone des Systems

const now = Temporal.Now.instant();
const local = now.toZonedDateTimeISO(Temporal.Now.timeZoneId());

console.log(local.toLocaleString("de-DE", {
  dateStyle: "full",
  timeStyle: "short"
}));

z. B. Sonntag, 10. März 2024 um 13:00

Legacy-Date umwandeln, Zeitzone übernehmen, Offset-Zonen nutzen

// Date → Instant → ZonedDateTime
const legacy = new Date("2024-06-01T08:30:00Z");
const instant = legacy.toTemporalInstant();

// Zeitzone aus einem vorhandenen ZonedDateTime übernehmen
const ref = Temporal.ZonedDateTime.from("2024-01-01T00:00[Europe/Paris]");
console.log(instant.toZonedDateTimeISO(ref).toString());

// Fester Offset ohne Sommerzeitregeln
console.log(instant.toZonedDateTimeISO("+05:30").toString());

2024-06-01T10:30:00+02:00[Europe/Paris] 2024-06-01T14:00:00+05:30[+05:30]

// Wichtig · Fallstricke

Pflichtargument: Ohne timeZone gibt es einen TypeError, ebenso bei Typen, die weder String noch ZonedDateTime sind. Ein unbekannter Zeitzonenname wie "Europe/Gotham" wirft einen RangeError.
Nur ISO-Kalender: Die Methode liefert immer iso8601. Eine frühere Variante toZonedDateTime({ timeZone, calendar }) wurde aus dem Proposal entfernt. Andere Kalender bekommst du mit .withCalendar("japanese") o. Ä.
Offset oder IANA-Zone: Mit einem festen Offset wie "+01:00" gibt es keine Sommerzeitregeln. Arithmetik wie add({ days: 1 }) verhält sich dann anders als mit "Europe/Berlin". Für echte Orte solltest du deshalb IANA-Namen verwenden.
Anzeige: Für Benutzeroberflächen nimmst du toLocaleString() bzw. Intl.DateTimeFormat, nicht toString(). Letzteres liefert das maschinenlesbare RFC-9557-Format.
Kompatibilität: Temporal ist neu: Firefox ab 139, Chromium ab 144, in Safari noch nicht verfügbar. Für den Produktiveinsatz brauchst du ggf. ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill. In Node.js ist Temporal erst in neueren Versionen verfügbar.

Siehe auch

Temporal.PlainDate.prototype.toZonedDateTime() Temporal.Instant.prototype.toLocaleString() Temporal.PlainDateTime.prototype.toZonedDateTime() Temporal.Instant.prototype.toString() Temporal.Instant.prototype.equals()