Temporal.ZonedDateTime.prototype.withTimeZone() — Methode · JavaScript-Referenz

Signatur

Temporal.ZonedDateTime.prototype.withTimeZone(timeZone)

Beschreibung

withTimeZone() rechnet ein Temporal.ZonedDateTime in eine andere Zeitzone um. Der Zeitpunkt bleibt dabei gleich, epochNanoseconds ändert sich also nicht. Neu berechnet werden die lokale Uhrzeit und der UTC-Versatz. Die Methode beantwortet also Fragen wie „Wie spät ist es in New York, wenn es in Berlin 15 Uhr ist?“.

Das ursprüngliche Objekt bleibt unverändert, denn alle Temporal-Objekte sind unveränderlich. Auch der Kalender (z. B. iso8601) wird übernommen. Wenn du den Kalender wechseln willst, nimm withCalendar().

Das Gegenstück ist toPlainDateTime().toZonedDateTime(zone): Hier bleibt die Uhrzeit auf der Uhr gleich, und es entsteht ein anderer Zeitpunkt. Praktisch heißt das: Mit withTimeZone() rechnest du Termine für Teilnehmende in anderen Zeitzonen um. Mit dem zweiten Weg verschiebst du einen Termin, der „um 9 Uhr Ortszeit“ stattfindet, in eine andere Zone.

Parameter

Name	Typ	Default	Beschreibung
$timeZone Pflicht	string \| Temporal.ZonedDateTime		Die Zielzeitzone. Als Zeichenkette sind drei Formen erlaubt: ein IANA-Bezeichner (z. B. `"America/New_York"`), ein fester Versatz (z. B. `"+05:30"`) oder ein Datum-Zeit-String mit Zeitzonen-Angabe. Übergibst du ein `Temporal.ZonedDateTime`, wird dessen Zeitzone verwendet.

Rückgabewert

Typ

Temporal.ZonedDateTime

Beschreibung

Ein neues Temporal.ZonedDateTime mit demselben Zeitpunkt und Kalender in der angegebenen Zeitzone.

Beispiele

Meeting-Zeit für andere Zeitzonen umrechnen

const meeting = Temporal.ZonedDateTime.from("2024-03-15T15:00[Europe/Berlin]");

const newYork = meeting.withTimeZone("America/New_York");
const tokio = meeting.withTimeZone("Asia/Tokyo");

console.log(newYork.toString());
console.log(tokio.toString());

2024-03-15T10:00:00-04:00[America/New_York] 2024-03-15T23:00:00+09:00[Asia/Tokyo]

Gleicher Zeitpunkt, aber nicht equals()

const berlin = Temporal.ZonedDateTime.from("2024-03-15T15:00[Europe/Berlin]");
const ny = berlin.withTimeZone("America/New_York");

// Der Zeitpunkt ist identisch …
console.log(berlin.epochNanoseconds === ny.epochNanoseconds);
console.log(Temporal.ZonedDateTime.compare(berlin, ny));
// … equals() prüft aber auch die Zeitzone
console.log(berlin.equals(ny));

true 0 false

withTimeZone() im Vergleich zum Beibehalten der Uhrzeit

const start = Temporal.ZonedDateTime.from("2024-03-15T15:00[Europe/Berlin]");

// Gleicher Zeitpunkt, andere Uhrzeit
const umgerechnet = start.withTimeZone("America/New_York");

// Gleiche Uhrzeit, anderer Zeitpunkt
const gleicheUhrzeit = start.toPlainDateTime().toZonedDateTime("America/New_York");

console.log(umgerechnet.toString());
console.log(gleicheUhrzeit.toString());

2024-03-15T10:00:00-04:00[America/New_York] 2024-03-15T15:00:00-04:00[America/New_York]

Fester Versatz und Zeitzone eines anderen Objekts

const utc = Temporal.ZonedDateTime.from("2024-03-15T14:00[UTC]");

console.log(utc.withTimeZone("+05:30").toString());

// Zeitzone eines anderen ZonedDateTime übernehmen
const referenz = Temporal.ZonedDateTime.from("2024-01-01T00:00[Australia/Sydney]");
console.log(utc.withTimeZone(referenz).toString());

2024-03-15T19:30:00+05:30[+05:30] 2024-03-16T01:00:00+11:00[Australia/Sydney]

// Wichtig · Fallstricke

Browser-Kompatibilität: Temporal ist noch recht neu (Firefox 139+, Chrome/Edge 144+). Safari und ältere Node.js-Versionen unterstützen es noch nicht. Für produktiven Einsatz ist dort ein Polyfill wie @js-temporal/polyfill nötig.
Ein unbekannter Zeitzonen-Bezeichner (z. B. \"Europe/Atlantis\") löst einen RangeError aus. Andere Typen als String oder Temporal.ZonedDateTime lösen einen TypeError aus.
Die Methode ändert nie den Zeitpunkt. Wenn du die Ortszeit beibehalten willst, nimm toPlainDateTime().toZonedDateTime(zone).
Ein fester Versatz wie \"+02:00\" kennt keine Sommerzeit. Für echte Orte solltest du deshalb IANA-Bezeichner verwenden, damit spätere Berechnungen mit add() oder with() Zeitumstellungen korrekt berücksichtigen.
equals() gibt nach einem Zeitzonenwechsel false zurück, obwohl der Zeitpunkt gleich ist. Für einen reinen Zeitpunktvergleich nimm Temporal.ZonedDateTime.compare() oder vergleiche epochNanoseconds.
Wenn du ein Datum nur in einer anderen Zone anzeigen willst, reicht oft toLocaleString(locale, { timeZone }).

Siehe auch

Temporal.ZonedDateTime Temporal.ZonedDateTime.prototype.withCalendar() Temporal.ZonedDateTime.prototype.with() Temporal.ZonedDateTime.prototype.timeZoneId Temporal.PlainDateTime.prototype.toZonedDateTime() Temporal.Instant.prototype.toZonedDateTimeISO()