Temporal.ZonedDateTime.prototype.with()

info

Ein Objekt, das mindestens eine der von Temporal.ZonedDateTime.from() anerkannten Eigenschaften enthält (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 aus der ursprünglichen Datum-Uhrzeit. Sie müssen nur eines von month oder monthCode, sowie eines von era und eraYear oder year angeben, und das 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 Datum-Uhrzeit in der angegebenen Zeitzone mehrdeutig ist (es gibt mehr als einen Moment mit einer solchen lokalen Zeit oder die lokale Zeit existiert nicht). Mögliche Werte sind "compatible", "earlier", "later" und "reject". Standardmäßig 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 explizit angegeben wird, aber der Offset für die gegebene Zeitzone zu der gegebenen lokalen Zeit ungültig ist. Mögliche Werte sind "use", "ignore", "reject" und "prefer". Standardmäßig ist "prefer". Weitere Informationen zu diesen Werten finden Sie unter Offset-Mehrdeutigkeit.

overflow Optional

Ein String, der das Verhalten angibt, wenn eine Datumskomponente außerhalb des zulässigen Bereichs liegt (wenn das Objekt info verwendet wird). Mögliche Werte sind:

"constrain" (Standard)

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

"reject"

Ein RangeError wird ausgelöst, wenn die Datumskomponente außerhalb des 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 der Rest der Felder von der ursprünglichen Datum-Uhrzeit kopiert wird.

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 bereitgestellten Eigenschaften, die dieselbe Komponente angeben, sind inkonsistent.
• Die bereitgestellten nicht-numerischen Eigenschaften sind ungültig; zum Beispiel, wenn monthCode in diesem Kalender niemals ein gültiger Monatscode ist.
• Die bereitgestellten numerischen Eigenschaften liegen außerhalb des Bereichs und options.overflow ist auf "reject" gesetzt.
• Die durch die bereitgestellten Eigenschaften dargestellte Uhrzeit ist in der Zeitzone mehrdeutig und options.disambiguation ist auf "reject" gesetzt.
• Das Ergebnis liegt nicht im darstellbaren Bereich, was ±10⁸ Tage oder etwa ±273.972,6 Jahre vom Unix-Epoch bedeutet.

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 zu den einzelnen 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) verwenden, wenn er gültig ist, und andernfalls neu berechnen. Das bedeutet, wenn Sie auf ein anderes Datum setzen, das aufgrund eines Sommerzeitsübergangs 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 auf einen Zeitpunkt innerhalb des Sommerzeitsübergangs setzen, wird der Offset zur Klärung der Mehrdeutigkeit verwendet:

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 zuerst unverändert verwendet, um die genaue Uhrzeit zu erhalten, und dann 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 }, { 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 so einen expliziten neuen Offset erfordern:

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()