Temporal.PlainDateTime.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 Methode toZonedDateTime() von Temporal.PlainDateTime-Instanzen gibt eine neue Temporal.ZonedDateTime-Instanz zurück, die dasselbe Datum-Uhrzeit wie diese einfache Datum-Uhrzeit, jedoch in der angegebenen Zeitzone darstellt.

Syntax

js
toZonedDateTime(timeZone)
toZonedDateTime(timeZone, options)

Parameter

timeZone

Entweder ein String oder eine Temporal.ZonedDateTime-Instanz, die die zu verwendende Zeitzone darstellt. Wenn es sich um eine Temporal.ZonedDateTime-Instanz handelt, wird deren Zeitzone verwendet. Wenn es ein String ist, kann es sich um einen benannten Zeitzonen-Identifikator, einen Versatz-Zeitzonen-Identifikator oder einen Datum-Zeit-String handeln, der einen Zeitzonen-Identifikator oder Versatz enthält (siehe Zeitzonen und Versätze für weitere Informationen).

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

disambiguation Optional

Ein String, der angibt, was zu tun ist, wenn diese einfache Zeit mit null oder mehr als einem Zeitpunkt in der Zeitzone übereinstimmt, normalerweise aufgrund von Zeitumstellungen bei der Sommerzeit. Mögliche Werte sind "compatible", "earlier", "later" und "reject". Standardmäßig "compatible". Für mehr Informationen über diese Werte siehe Mehrdeutigkeit und Lücken von lokaler Zeit zu UTC-Zeit.

Rückgabewert

Eine neue Temporal.ZonedDateTime-Instanz, die dasselbe Datum-Uhrzeit wie diese einfache Datum-Uhrzeit darstellt, jedoch in der angegebenen Zeitzone.

Ausnahmen

RangeError

Wird ausgelöst, wenn eine der Optionen ungültig ist oder wenn timeZone kein gültiger Zeitzonen-Identifikator ist.

TypeError

Wird ausgelöst, wenn eines der Argumente nicht vom erwarteten Typ ist.

Beispiele

Verwendung von toZonedDateTime()

js
const dt = Temporal.PlainDateTime.from("2021-08-01T12:34:56");
const zdt = dt.toZonedDateTime("America/New_York");
console.log(zdt.toString()); // '2021-08-01T12:34:56-04:00[America/New_York]'

const dt2 = Temporal.PlainDateTime.from("2021-01-01T12:34:56");
const zdt2 = dt2.toZonedDateTime("America/New_York");
console.log(zdt2.toString()); // '2021-01-01T12:34:56-05:00[America/New_York]'

Umgang mit mehrdeutigen Zeiten

Unten haben wir zwei Wanduhrenzeiten, die wir in der Zeitzone America/New_York interpretieren möchten. Die erste, dtNotExist, hat aufgrund einer Vorwärtsumstellung der Sommerzeit nie existiert, daher müssen wir aus den Zeiten 01:05:00-05:00 oder 03:05:00-04:00 wählen. Die zweite, dtAmbiguous, kam zweimal vor, weil die Sommerzeit rückwärts umgestellt wurde, daher müssen wir aus den Zeiten 01:05:00-04:00 oder 01:05:00-05:00 wählen. Für eine ausführlichere Erklärung dieser Situation siehe Mehrdeutigkeit und Lücken von lokaler Zeit zu UTC-Zeit.

js
const dtNotExist = Temporal.PlainDateTime.from("2024-03-10T02:05:00");
const dtAmbiguous = Temporal.PlainDateTime.from("2024-11-03T01:05:00");

// Default: compatible
console.log(dtNotExist.toZonedDateTime("America/New_York").toString());
// '2024-03-10T03:05:00-04:00[America/New_York]'
console.log(dtAmbiguous.toZonedDateTime("America/New_York").toString());
// '2024-11-03T01:05:00-04:00[America/New_York]'

// Use the earlier time for ambiguous times
console.log(
  dtNotExist
    .toZonedDateTime("America/New_York", { disambiguation: "earlier" })
    .toString(),
);
// '2024-03-10T01:05:00-05:00[America/New_York]'
console.log(
  dtAmbiguous
    .toZonedDateTime("America/New_York", { disambiguation: "earlier" })
    .toString(),
);
// '2024-11-03T01:05:00-04:00[America/New_York]'

// Use the later time for ambiguous times
console.log(
  dtNotExist
    .toZonedDateTime("America/New_York", { disambiguation: "later" })
    .toString(),
);
// '2024-03-10T03:05:00-04:00[America/New_York]'
console.log(
  dtAmbiguous
    .toZonedDateTime("America/New_York", { disambiguation: "later" })
    .toString(),
);
// '2024-11-03T01:05:00-05:00[America/New_York]'

// Throw an error for ambiguous times
dtNotExist.toZonedDateTime("America/New_York", { disambiguation: "reject" });
// RangeError: instant is ambiguous

Spezifikationen

Specification
Temporal proposal
# sec-temporal.plaindatetime.prototype.tozoneddatetime

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch