Temporal.PlainDate.prototype.toZonedDateTime() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainDate.prototype.toZonedDateTime(timeZone | options)

Beschreibung

Die Methode toZonedDateTime() macht aus einem reinen Kalenderdatum (ohne Uhrzeit und ohne Zeitzone) einen exakten Zeitpunkt mit Zeitzone. Das Ergebnis ist ein Temporal.ZonedDateTime, das denselben Kalender wie das Ausgangsdatum verwendet.

Es gibt zwei Aufrufformen:

Nur Zeitzone: date.toZonedDateTime("Europe/Berlin") – als Uhrzeit wird der Beginn des Tages in dieser Zeitzone verwendet (normalerweise 00:00, bei einer Zeitumstellung um Mitternacht die erste gültige Uhrzeit).
Optionsobjekt: date.toZonedDateTime({ timeZone, plainTime }) – hier gibst du zusätzlich eine Uhrzeit an.

Die Methode ist praktisch, wenn du z. B. ein Datum aus einem Datumsauswahlfeld und eine Uhrzeit aus einem anderen Feld zu einem Termin in einer bestimmten Zeitzone zusammensetzen willst. Aus dem Ergebnis bekommst du dann über epochMilliseconds oder toInstant() einen eindeutigen Zeitpunkt, den du speichern oder übertragen kannst.

Gibt es die angegebene Uhrzeit in der Zeitzone nicht (Lücke bei der Sommerzeitumstellung) oder gibt es sie doppelt (Rückstellung), wird die Mehrdeutigkeit immer mit dem Modus "compatible" aufgelöst. Einen anderen disambiguation-Modus kannst du hier nicht angeben.

Parameter

Name	Typ	Default	Beschreibung
$timeZone Pflicht	string \| Temporal.ZonedDateTime		Kurzform: eine IANA-Zeitzonenkennung (z. B. `"Europe/Berlin"`), ein fester Versatz (z. B. `"+02:00"`) oder ein `Temporal.ZonedDateTime`, dessen Zeitzone übernommen wird. Die Uhrzeit ist dann der Tagesbeginn.
$options	Object		Alternativ zu `timeZone`: ein Objekt mit den folgenden Eigenschaften.
$options.timeZone Pflicht	string \| Temporal.ZonedDateTime		Die zu verwendende Zeitzone, wie oben beschrieben.
$options.plainTime	Temporal.PlainTime \| Object \| string	Tagesbeginn	Die Uhrzeit. Erlaubt ist alles, was auch `Temporal.PlainTime.from()` akzeptiert, z. B. `"14:30"` oder `{ hour: 14, minute: 30 }`. Fehlt sie, wird der Beginn des Tages in der Zeitzone verwendet.

Rückgabewert

Typ

Temporal.ZonedDateTime

Beschreibung

Ein neues Temporal.ZonedDateTime mit dem Datum dieser Instanz, der angegebenen (oder ermittelten) Uhrzeit und der Zeitzone im selben Kalendersystem.

Beispiele

Tagesbeginn in einer Zeitzone

const date = Temporal.PlainDate.from("2021-07-01");

const zdt = date.toZonedDateTime("America/New_York");
console.log(zdt.toString());

2021-07-01T00:00:00-04:00[America/New_York]

Termin aus Datum und Uhrzeit zusammensetzen

// Werte z. B. aus <input type="date"> und <input type="time">
const dateInput = "2024-10-15";
const timeInput = "14:30";

const meeting = Temporal.PlainDate.from(dateInput).toZonedDateTime({
  timeZone: "Europe/Berlin",
  plainTime: timeInput,
});

console.log(meeting.toString());
// Eindeutigen Zeitstempel zum Speichern verwenden
console.log(meeting.epochMilliseconds);
// Dasselbe Treffen in Tokio
console.log(meeting.withTimeZone("Asia/Tokyo").toPlainTime().toString());

2024-10-15T14:30:00+02:00[Europe/Berlin] 1728995400000 21:30:00

Sommerzeit-Lücke: Mitternacht existiert nicht

// In São Paulo begann die Sommerzeit am 4.11.2018 um 00:00 –
// Mitternacht gab es an diesem Tag nicht.
const date = Temporal.PlainDate.from("2018-11-04");
console.log(date.toZonedDateTime("America/Sao_Paulo").toString());

// Uhrzeit in der Lücke: "compatible" verschiebt nach vorne
const berlin = Temporal.PlainDate.from("2024-03-31").toZonedDateTime({
  timeZone: "Europe/Berlin",
  plainTime: "02:30",
});
console.log(berlin.toString());

2018-11-04T01:00:00-02:00[America/Sao_Paulo] 2024-03-31T03:30:00+02:00[Europe/Berlin]

Zeitzone eines vorhandenen ZonedDateTime übernehmen

const now = Temporal.Now.zonedDateTimeISO("Europe/Vienna");
const tomorrow = now.toPlainDate().add({ days: 1 });

// Morgen um 9 Uhr in derselben Zeitzone wie "now"
const reminder = tomorrow.toZonedDateTime({
  timeZone: now,
  plainTime: { hour: 9 },
});
console.log(reminder.timeZoneId, reminder.hour);

Europe/Vienna 9

// Wichtig · Fallstricke

Tagesbeginn ist nicht immer 00:00: Ohne plainTime wird der tatsächliche Beginn des Tages in der Zeitzone verwendet. Fällt eine Zeitumstellung auf Mitternacht, kann das z. B. 01:00 sein. Verlass dich also nicht darauf, dass hour immer 0 ist.
Keine Wahl beim Auflösen von Mehrdeutigkeiten: Mit plainTime wird immer disambiguation: "compatible" verwendet (bei einer Lücke nach vorne, bei doppelten Uhrzeiten die frühere). Brauchst du "reject", "earlier" oder "later", dann nimm date.toPlainDateTime(time).toZonedDateTime(tz, { disambiguation: "reject" }).
Fehler: Eine unbekannte Zeitzonenkennung oder eine ungültige Uhrzeit wirft einen RangeError. Ist das Argument weder String noch Objekt, oder fehlt im Optionsobjekt timeZone, gibt es einen TypeError.
Feste Versätze wie "+02:00" kennen keine Sommerzeit. Für echte Orte besser eine IANA-Kennung wie "Europe/Berlin" verwenden.
Kompatibilität: Temporal gibt es noch nicht in allen Browsern (zuerst in Firefox 139, danach in Chromium-basierten Browsern; Safari zieht noch nach). Für den Produktiveinsatz ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill verwenden und vorher mit typeof Temporal !== "undefined" prüfen.

Siehe auch

Temporal.PlainDateTime.prototype.toZonedDateTime() Temporal.PlainDate.prototype.toPlainDateTime() Temporal.Instant.prototype.toZonedDateTimeISO() Temporal.PlainDate.prototype.toLocaleString() Temporal.PlainDate.prototype.toString()