Temporal.PlainDate.prototype.toZonedDateTime()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die toZonedDateTime()-Methode von Temporal.PlainDate-Instanzen gibt ein neues Temporal.ZonedDateTime-Objekt zurück, das dieses Datum, eine angegebene Zeit und eine angegebene Zeitzone im selben Kalendersystem darstellt.

Syntax

js
toZonedDateTime(timeZone)
toZonedDateTime(info)

Parameter

timeZone

Entweder ein String oder eine Temporal.ZonedDateTime-Instanz, die die timeZone-Option repräsentiert. Dies ist eine praktische Überladung, sodass toZonedDateTime(timeZone) gleichbedeutend ist mit toZonedDateTime({ timeZone }), wobei timeZone ein String oder Temporal.ZonedDateTime ist. Diese Überladung wird gewählt, wenn das erste Argument kein Objekt ist oder die timeZone-Eigenschaft des Objekts undefined ist (weil ZonedDateTime-Instanzen stattdessen eine timeZoneId-Eigenschaft haben).

info

Ein Objekt, das einige oder alle der folgenden Eigenschaften enthält (in der Reihenfolge, in der sie abgerufen und validiert werden):

plainTime Optional

Ein String, ein Objekt oder eine Temporal.PlainTime-Instanz, die die Zeitkomponente des resultierenden ZonedDateTime darstellt. Es wird unter Verwendung des gleichen Algorithmus wie Temporal.PlainTime.from() in ein Temporal.PlainTime-Objekt konvertiert. Standardmäßig ist dies die erste gültige Zeit in dieser Zeitzone an diesem Kalenderdatum, die normalerweise "00:00:00" ist, aber anders sein kann, wenn beispielsweise die Sommerzeit Mitternacht überspringt.

timeZone

Entweder ein String oder eine Temporal.ZonedDateTime-Instanz, die die zu verwendende Zeitzone repräsentiert. Wenn es sich um eine Temporal.ZonedDateTime-Instanz handelt, wird deren Zeitzone verwendet. Wenn es ein String ist, kann es sich um eine benannte Zeitzonenkennung, eine Offset-Zeitzonenkennung oder eine Datum-Uhrzeit-Zeichenkette handeln, die eine Zeitzonenkennung oder einen Offset enthält (siehe Zeitzonen und Offsets für weitere Informationen).

Rückgabewert

Ein neues Temporal.ZonedDateTime-Objekt, das das Datum und die Zeit darstellt, die durch dieses Datum, plainTime und timeZone angegeben sind, interpretiert im Kalendersystem dieses Datums.

Im Falle von Mehrdeutigkeiten wird immer das kompatible Verhalten verwendet: Wenn die Zeit in eine Lücke fällt, bewegen wir uns vorwärts um die Längen der Lücke; wenn die Zeit in eine Mehrdeutigkeit fällt, wählen wir die frühere der beiden Möglichkeiten. Das bedeutet, dass das resultierende ZonedDateTime möglicherweise ein potenziell anderes Datum oder Zeit als die Eingabe hat.

Ausnahmen

TypeError

Wird ausgelöst, wenn timeZone weder ein String noch eine Temporal.ZonedDateTime-Instanz ist.

RangeError

Wird ausgelöst, wenn timeZone ein String ist, der keine gültige Zeitzonenkennung ist.

Beispiele

Verwendung von toZonedDateTime()

js
const summer = Temporal.PlainDate.from("2021-07-01");
// Just time zone
const summerTime = summer.toZonedDateTime("America/New_York");
console.log(summerTime.toString()); // 2021-07-01T00:00:00-04:00[America/New_York]

const winter = Temporal.PlainDate.from("2021-01-01");
// Time zone and time
const winterTime = winter.toZonedDateTime({
  plainTime: "12:34:56",
  timeZone: "America/New_York",
});
console.log(winterTime.toString()); // 2021-01-01T12:34:56-05:00[America/New_York]

const spring = Temporal.PlainDate.from("2021-03-01");
// Time zone as object and time as object
const springTime = spring.toZonedDateTime({
  plainTime: summerTime.toPlainTime(),
  timeZone: winterTime,
});
console.log(springTime.toString()); // 2021-03-01T00:00:00-05:00[America/New_York]

Spezifikationen

Specification
Temporal
# sec-temporal.plaindate.prototype.tozoneddatetime

Browser-Kompatibilität

Siehe auch