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 diese Datum-Uhrzeit repräsentiert, wobei einige Felder durch neue Werte ersetzt wurden. Da alle Temporal-Objekte so konstruiert sind, dass sie unveränderlich sind, fungiert diese Methode im Wesentlichen als Setter für die Felder der Datum-Uhrzeit.

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

Syntax

js
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 spezifizierte Eigenschaften übernehmen die Werte der ursprünglichen Datum-Uhrzeit. Sie müssen nur eines der beiden, month oder monthCode, und eines von era und eraYear oder year angeben, und das andere wird entsprechend aktualisiert.

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

overflow Optional

Ein String, der das Verhalten spezifiziert, wenn eine Datumskomponente außerhalb des gültigen Bereichs liegt. 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.

Rückgabewert

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

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

Beispiele

Verwendung von with()

js
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 der einzelnen Eigenschaften, die mit with() gesetzt werden können.

Spezifikationen

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

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch