Temporal.ZonedDateTime.prototype.with()

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 with()-Methode von Temporal.ZonedDateTime-Instanzen gibt ein neues Temporal.ZonedDateTime-Objekt zurück, welches diese Datums-Uhrzeit mit einigen Feldern darstellt, die durch neue Werte ersetzt wurden. Da alle Temporal-Objekte so gestaltet sind, dass sie unveränderlich sind, fungiert diese Methode im Wesentlichen als Setter für die Felder der Datums-Uhrzeit.

Um die Eigenschaft calendarId zu ersetzen, verwenden Sie die Methode withCalendar(). Um die Eigenschaft timeZoneId zu ersetzen, verwenden Sie die Methode withTimeZone().

Syntax

js
with(info)
with(info, options)

Parameter

info

Ein Objekt, das mindestens eine der Eigenschaften enthält, die von Temporal.ZonedDateTime.from() erkannt werden (außer calendar und timeZone): day, era und eraYear, hour, microsecond, millisecond, minute, month, monthCode, nanosecond, offset, second, year. Nicht angegebene Eigenschaften verwenden die Werte der ursprünglichen Datums-Uhrzeit. Sie müssen nur eines von month oder monthCode sowie eines von era und eraYear oder year angeben, und die andere Eigenschaft wird entsprechend aktualisiert.

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 die lokale Datums-Uhrzeit in der angegebenen Zeitzone mehrdeutig ist (es gibt mehr als einen Zeitpunkt mit dieser lokalen Zeit, oder die lokale Zeit existiert nicht). Mögliche Werte sind "compatible", "earlier", "later" und "reject". Standardwert ist "compatible". Weitere Informationen zu diesen Werten finden Sie unter Ambiguität und Lücken von lokaler Zeit zu UTC-Zeit.

offset Optional

Was zu tun ist, wenn der Offset explizit in info angegeben wird, aber für die angegebene Zeitzone in der angegebenen lokalen Zeit ungültig ist. Mögliche Werte sind "use", "ignore", "reject" und "prefer". Standardwert ist "prefer". Weitere Informationen zu diesen Werten finden Sie unter Offset-Mehrdeutigkeit.

overflow Optional

Eine Zeichenkette, die das Verhalten angibt, wenn eine Datumskomponente außerhalb des gültigen Bereichs liegt (bei der Verwendung des Objekts info). Mögliche Werte sind:

"constrain" (Standard)

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

"reject"

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

Rückgabewert

Ein neues Temporal.ZonedDateTime-Objekt, bei dem die in info angegebenen Felder, die nicht undefined sind, durch die entsprechenden Werte ersetzt werden und der Rest der Felder von der ursprünglichen Datums-Uhrzeit übernommen wird.

Ausnahmen

TypeError

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

  • info ist kein Objekt.
  • options ist kein Objekt oder undefined.
RangeError

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

  • Die angegebenen Eigenschaften, die dieselbe Komponente spezifizieren, sind inkonsistent.
  • Die angegebenen nicht-numerischen Eigenschaften sind ungültig; zum Beispiel, wenn monthCode kein gültiger Monatscode in diesem Kalender ist.
  • Die angegebenen numerischen Eigenschaften liegen außerhalb des zulässigen Bereichs, und options.overflow ist auf "reject" gesetzt.
  • Die durch die angegebenen Eigenschaften dargestellte Wanduhrzeit ist in der Zeitzone mehrdeutig, und options.disambiguation ist auf "reject" gesetzt.
  • Das Ergebnis liegt nicht im darstellbaren Bereich, der ±108 Tage oder etwa ±273.972,6 Jahre vom Unix-Epoch umfasst.

Beispiele

Verwendung von with()

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:34:56[America/New_York]",
);
const newZDT = zdt.with({ hour: 13 });
console.log(newZDT.toString()); // "2021-07-01T13:34:56-04:00[America/New_York]"

Weitere Beispiele finden Sie in der Dokumentation zu den einzelnen Eigenschaften, die mit with() gesetzt werden können.

Offset während Datumsänderungen

Standardmäßig wird die offset-Option auf "prefer" gesetzt, was bedeutet, dass wir den ursprünglichen Offset (oder den in info angegebenen) verwenden, wenn er gültig ist, und ansonsten neu berechnen. Das bedeutet, wenn Sie ein anderes Datum einstellen, das aufgrund einer DST-Übergangs einen anderen Offset hat, wird der Offset neu berechnet:

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 });
// The offset is recalculated to -05:00
console.log(newZDT.toString()); // "2021-12-01T12:00:00-05:00[America/New_York]"

Und wenn Sie die Uhrzeit während des DST-Übergangs einstellen, wird der Offset verwendet, um die Mehrdeutigkeit zu lösen:

js
const zdt = Temporal.ZonedDateTime.from(
  "2024-11-02T01:05:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ day: 3 });
console.log(newZDT.toString()); // "2024-11-03T01:05:00-04:00[America/New_York]"

const zdt2 = Temporal.ZonedDateTime.from(
  "2024-11-04T01:05:00-05:00[America/New_York]",
);
const newZDT2 = zdt2.with({ day: 3 });
console.log(newZDT2.toString()); // "2024-11-03T01:05:00-05:00[America/New_York]"

Wenn Sie offset: "use" verwenden, dann wird der Offset unverändert verwendet, um die genaue Zeit zuerst zu ermitteln, und dann wird der Offset neu berechnet:

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
const newZDT = zdt.with({ month: 12 }, { offset: "use" });
// The offset is recalculated to -05:00, but the wall-clock time changes
console.log(newZDT.toString()); // "2021-12-01T11:00:00-05:00[America/New_York]"

Sie können auch offset: "reject" einstellen, um einen Fehler auszulösen, wenn der ursprüngliche Offset ungültig ist, wodurch ein neuer Offset explizit angegeben werden muss:

js
const zdt = Temporal.ZonedDateTime.from(
  "2021-07-01T12:00:00-04:00[America/New_York]",
);
zdt.with({ month: 12 }, { offset: "reject" });
// RangeError: date-time can't be represented in the given time zone
zdt.with({ month: 12, offset: "-05:00" }, { offset: "reject" }).toString();
// "2021-12-01T12:00:00-05:00[America/New_York]"

Spezifikationen

Specification
Temporal proposal
# sec-temporal.zoneddatetime.prototype.with

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
Node.js
with
Experimental

Legend

Tip: you can click/tap on a cell for more information.

No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.

Siehe auch