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 darstellt. Dies ist eine Komfortüberladung, sodass toZonedDateTime(timeZone) äquivalent zu toZonedDateTime({ timeZone }) ist, 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. Sie wird unter Verwendung desselben Algorithmus wie Temporal.PlainTime.from() in ein Temporal.PlainTime-Objekt umgewandelt. Standardmäßig wird die erste gültige Zeit in dieser Zeitzone an diesem Kalenderdatum verwendet, die normalerweise "00:00:00" ist, sich aber ändern kann, wenn zum Beispiel die Sommerzeit Mitternacht überspringt.

timeZone

Entweder ein String oder eine Temporal.ZonedDateTime-Instanz, die die zu verwendende Zeitzone darstellt. Wenn eine Temporal.ZonedDateTime-Instanz, wird deren Zeitzone verwendet. Wenn ein String, kann es sich um einen benannten Zeitzonenbezeichner, einen Offset-Zeitzonenbezeichner oder einen Datums-/Zeitstring mit einem Zeitzonenbezeichner oder einem Offset handeln (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 und im Kalendersystem dieses Datums interpretiert werden.

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ückenlänge; 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 anderes Datum oder eine andere 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 kein gültiger Zeitzonenbezeichner 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 proposal
# sec-temporal.plaindate.prototype.tozoneddatetime

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch