Temporal.PlainDateTime.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.PlainDateTime-Instanzen gibt ein neues Temporal.PlainDateTime-Objekt zurück, das dieses Datum und die Uhrzeit mit einigen durch neue Werte ersetzten Feldern darstellt. Da alle Temporal-Objekte so entworfen sind, dass sie unveränderlich sind, fungiert diese Methode im Wesentlichen als Setter für die Felder des Datums und der Uhrzeit.

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

Syntax

with(info)
with(info, options)

Parameter

info

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

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

overflow Optional

Ein String, der das Verhalten spezifiziert, wenn eine Datums-Komponente außerhalb des Bereichs liegt. Mögliche Werte sind:

"constrain" (Standard): Die Datums-Komponente wird auf den gültigen Bereich eingeschränkt.
"reject": Ein RangeError wird ausgelöst, wenn die Datums-Komponente außerhalb des Bereichs liegt.

Rückgabewert

Ein neues Temporal.PlainDateTime-Objekt, bei dem die Felder, die in info spezifiziert und nicht undefined sind, durch die entsprechenden Werte ersetzt wurden, und der Rest der Felder aus dem ursprünglichen Datum und der Uhrzeit kopiert 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 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.
Das Ergebnis liegt nicht im darstellbaren Bereich, der ±(10⁸ + 1) Tage oder etwa ±273.972,6 Jahre ab dem Unix-Epoch-Datum umfasst.

Beispiele

Verwendung von with()

const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56");
const newDT = dt.with({ hour: 13 });
console.log(newDT.toString()); // "2021-07-01T13:34:56"
const newDT2 = dt.with({ month: 2, day: 22, millisecond: 222 });
console.log(newDT2.toString()); // "2021-02-22T13:34:56.222"
const nextDecade = dt.with({ year: dt.year + 10 });
console.log(nextDecade.toString()); // "2031-07-01T13:34:56"

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

Spezifikationen

Specification
Temporal # sec-temporal.plaindatetime.prototype.with