Temporal.ZonedDateTime.prototype.with()

info

Ein Objekt, das mindestens eine der von Temporal.ZonedDateTime.from() erkannten Eigenschaften (außer calendar) enthält: day, era und eraYear, hour, microsecond, millisecond, minute, month, monthCode, nanosecond, offset, second, year. Nicht angegebene Eigenschaften verwenden die Werte des ursprünglichen Datums und der Uhrzeit. Es reicht, nur eine der Eigenschaften month oder monthCode sowie eine der Eigenschaften era und eraYear oder year anzugeben, die andere 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 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 Mehrdeutigkeit und Lücken von lokaler Zeit zu UTC-Zeit.

offset Optional

Was zu tun ist, wenn der Offset in info ausdrücklich angegeben wird, aber der Offset für die angegebene Zeitzone und die angegebene lokale 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 Zeichenfolge, die das Verhalten angibt, wenn eine Datums-Komponente außerhalb des gültigen Bereichs liegt (bei Verwendung des Objekts info). Mögliche Werte sind:

"constrain" (Standard)

Die Datums-Komponente wird auf den gültigen Bereich begrenzt.

"reject"

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

Ein neues Temporal.ZonedDateTime-Objekt, bei dem die in info angegebenen Felder, die nicht undefined sind, durch die entsprechenden Werte ersetzt werden und die restlichen Felder vom ursprünglichen Datum und Uhrzeit übernommen werden.

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 niemals ein gültiger Monatscode in diesem Kalender ist.
• Die angegebenen numerischen Eigenschaften liegen außerhalb des gültigen Bereichs und options.overflow ist auf "reject" gesetzt.

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]"

Für weitere Beispiele siehe die Dokumentation der individuellen Eigenschaften, die mit with() gesetzt werden können.

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

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 innerhalb der Zeitumstellungswechsel einstellen, wird der Offset verwendet, um die Mehrdeutigkeit zu lösen:

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, wird der Offset wie angegeben verwendet, um die genaue Zeit zuerst zu erhalten und dann den Offset neu zu berechnen:

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" setzen, um einen Fehler auszulösen, wenn der ursprüngliche Offset ungültig ist, und einen expliziten neuen Offset zu erzwingen:

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]"

• Temporal.ZonedDateTime
• Temporal.ZonedDateTime.prototype.withCalendar()
• Temporal.ZonedDateTime.prototype.withTimeZone()
• Temporal.ZonedDateTime.prototype.withPlainTime()
• Temporal.ZonedDateTime.from()
• Temporal.ZonedDateTime.prototype.add()
• Temporal.ZonedDateTime.prototype.subtract()