Temporal.ZonedDateTime.from()

Syntax

Temporal.ZonedDateTime.from(info)
Temporal.ZonedDateTime.from(info, options)

Parameter

info

Eins der folgenden:

• Eine Temporal.ZonedDateTime Instanz, die eine Kopie der Instanz erstellt.
• Ein RFC 9557 Format String, der ein Datum, optional eine Uhrzeit, optional einen Offset, eine Zeitzonenanmerkung und optional einen Kalender enthält.
• Ein Objekt, das Eigenschaften enthält, die entweder von Temporal.PlainDate.from() (calendar, era, eraYear, year, month, monthCode, day) oder von Temporal.PlainTime.from() (hour, minute, second, millisecond, microsecond, nanosecond) akzeptiert werden. Info sollte explizit ein Jahr (als year oder als era und eraYear), einen Monat (als month oder monthCode) und einen Tag angeben; andere sind optional und werden auf ihre Standardwerte gesetzt. Die folgenden Eigenschaften sollten ebenfalls bereitgestellt werden:

  timeZone

  Entweder ein String oder eine Temporal.ZonedDateTime Instanz, die die zu verwendende Zeitzone darstellt. Wenn eine Temporal.ZonedDateTime Instanz angegeben wird, wird deren Zeitzone verwendet. Wenn ein String angegeben wird, kann er ein benannter Zeitzonen-Identifier, ein Offset-Zeitzonen-Identifier oder ein Datum-Zeitstring sein, der einen Zeitzonen-Identifier oder einen Offset enthält (siehe Zeitzonen und Offsets für weitere Informationen). Die Zeiteigenschaften werden in dieser Zeitzone interpretiert.

  offset Optional

  Ein Offset-String, im gleichen Format wie der RFC 9557 Offset, jedoch mit optionalen Sekunden- und Subsekundenkomponenten (±HH:mm:ss.sssssssss), der den Offset von UTC darstellt. Wenn weggelassen, wird er aus der Zeitzone und dem Datum-Zeitpunkt berechnet. "Z" ist nicht erlaubt.

options Optional

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

disambiguation Optional

Was zu tun ist, wenn das lokale Datum und die Uhrzeit in der angegebenen Zeitzone mehrdeutig sind (es gibt mehr als einen Moment mit solcher lokaler Zeit, oder die lokale Zeit existiert nicht). Mögliche Werte sind "compatible", "earlier", "later" und "reject". Standardmäßig ist "compatible". Für weitere Informationen über diese Werte siehe Mehrdeutigkeit und Lücken von lokaler Zeit zu UTC-Zeit.

offset Optional

Was zu tun ist, wenn der Offset explizit in info angegeben ist, aber für die gegebene Zeitzone zur angegebenen lokalen Zeit ungültig ist. Mögliche Werte sind "use", "ignore", "reject" und "prefer". Standardmäßig ist "reject". Für weitere Informationen über diese Werte siehe Offset-Mehrdeutigkeit.

overflow Optional

Ein String, der das Verhalten spezifiziert, wenn eine Datumskomponente außerhalb des Bereichs liegt (bei Verwendung des Objekts info). Mögliche Werte sind:

"constrain" (Standard)

Die Datumskomponente wird eingeschränkt auf den gültigen Bereich.

"reject"

Ein RangeError wird ausgelöst, wenn die Datumskomponente außerhalb des Bereichs liegt.

Rückgabewert

Ein neues Temporal.ZonedDateTime Objekt, das das Datum und die Uhrzeit darstellt, die durch info im angegebenen calendar und timeZone spezifiziert sind.

Ausnahmen

TypeError

Wird in einem der folgenden Fälle ausgelöst:

• info ist kein Objekt oder String.
• options ist kein Objekt oder undefined.
• Die bereitgestellten Eigenschaften sind unzureichend, um ein Datum eindeutig zu bestimmen. In der Regel müssen Sie ein year (oder era und eraYear), ein month (oder monthCode) und einen day angeben.

RangeError

Wird in einem der folgenden Fälle ausgelöst:

• Die bereitgestellten Eigenschaften, die dieselbe Komponente spezifizieren, sind inkonsistent.
• Die bereitgestellten nicht-numerischen Eigenschaften sind nicht gültig; zum Beispiel, wenn monthCode niemals ein gültiger Monatscode in diesem Kalender ist.
• Die bereitgestellten numerischen Eigenschaften liegen außerhalb des Bereichs, und options.overflow ist auf "reject" gesetzt.
• Die Uhrzeit ist in der Zeitzone mehrdeutig und options.disambiguation ist auf "reject" gesetzt.
• Die Info liegt nicht im darstellbaren Bereich, der ±10⁸ Tage oder etwa ±273,972.6 Jahre vom Unix-Epoch umfasst.

Beispiele

Erstellen eines ZonedDateTime aus einem Objekt

// Year + month + day + hour + minute + second
const zdt = Temporal.ZonedDateTime.from({
  timeZone: "America/New_York",
  year: 2021,
  month: 7,
  day: 1,
  hour: 12,
  minute: 34,
  second: 56,
});
console.log(zdt.toString()); // "2021-07-01T12:34:56-04:00[America/New_York]"

Erstellen eines ZonedDateTime aus einem String

const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56-04:00[America/New_York]",
);
console.log(zdt.toLocaleString()); // "7/1/2021, 12:34:56 PM EDT" (assuming en-US locale)

// Time given as UTC, and converted to local
const zdt2 = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56Z[America/New_York]",
);
console.log(zdt2.toString()); // "2021-07-01T08:34:56-04:00[America/New_York]"

Erstellen eines ZonedDateTime aus einem ISO 8601 / RFC 3339 String

Beachten Sie, dass Temporal.ZonedDateTime.from() ISO 8601 Strings ablehnt, die keinen Zeitzonen-Identifier enthalten. Dies stellt sicher, dass die Zeitzone immer bekannt ist und verwendet werden kann, um verschiedene Offsets abzuleiten, während sich die lokale Zeit ändert.

Wenn Sie einen ISO 8601 String analysieren möchten, konstruieren Sie zuerst ein Temporal.Instant Objekt und konvertieren Sie es dann in ein Temporal.ZonedDateTime Objekt. Sie können jede Zeitzone angeben, auch wenn sie nicht mit dem ursprünglich im String angegebenen Offset übereinstimmt, und die lokale Zeit wird entsprechend angepasst.

const isoString = "2021-07-01T12:34:56+02:00";
const instant = Temporal.Instant.from(isoString);
const zdt = instant.toZonedDateTimeISO("America/New_York");
console.log(zdt.toString()); // "2021-07-01T06:34:56-04:00[America/New_York]"

Lokale Zeit-Mehrdeutigkeit

Siehe Mehrdeutigkeit und Lücken von lokaler Zeit zu UTC-Zeit für eine Einführung in diese Situation.

const localTimeNotExist = "2024-03-10T02:05:00[America/New_York]";
// For non-existent times, "compatible" is equivalent to "later"
const zdt = Temporal.ZonedDateTime.from(localTimeNotExist);
console.log(zdt.toString()); // "2024-03-10T03:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(localTimeNotExist, {
  disambiguation: "earlier",
});
console.log(zdt2.toString()); // "2024-03-10T01:05:00-05:00[America/New_York]"

const localTimeAmbiguous = "2024-11-03T01:05:00[America/New_York]";
// For ambiguous times, "compatible" is equivalent to "earlier"
const zdt3 = Temporal.ZonedDateTime.from(localTimeAmbiguous);
console.log(zdt3.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt4 = Temporal.ZonedDateTime.from(localTimeAmbiguous, {
  disambiguation: "later",
});
console.log(zdt4.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

Behebung von Offset-Mehrdeutigkeit

Siehe Offset-Mehrdeutigkeit für eine Einführung in diese Situation.

const offsetAmbiguous = "2019-12-23T12:00:00-02:00[America/Sao_Paulo]";

Temporal.ZonedDateTime.from(offsetAmbiguous);
// RangeError: date-time can't be represented in the given time zone
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "use" }).toString();
// "2019-12-23T11:00:00-03:00[America/Sao_Paulo]"
Temporal.ZonedDateTime.from(offsetAmbiguous, { offset: "ignore" }).toString();
// "2019-12-23T12:00:00-03:00[America/Sao_Paulo]"

Für weitere Beispiele, insbesondere hinsichtlich verschiedener Kalender und Überlaufeinstellungen, siehe Temporal.PlainDate.from() und Temporal.PlainTime.from().

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Temporal.ZonedDateTime
• Temporal.ZonedDateTime()
• Temporal.ZonedDateTime.prototype.with()