Temporal.PlainYearMonth.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 Methode with() von Temporal.PlainYearMonth-Instanzen gibt ein neues Temporal.PlainYearMonth-Objekt zurück, das diesen Jahr-Monat mit einigen durch neue Werte ersetzten Feldern darstellt. Da alle Temporal-Objekte unveränderlich konzipiert sind, fungiert diese Methode im Wesentlichen als Setter für die Felder des Jahr-Monats.

Es gibt keine offensichtliche Möglichkeit, ein neues Temporal.PlainYearMonth-Objekt zu erstellen, das denselben Jahr-Monat in einem anderen Kalender darstellt. Um also seine calendarId-Eigenschaft zu ersetzen, müssen Sie es zuerst mit toPlainDate() in ein Temporal.PlainDate-Objekt umwandeln, den Kalender ändern und dann zurück konvertieren.

Syntax

js
with(info)
with(info, options)

Parameter

info

Ein Objekt, das mindestens eine der von Temporal.PlainYearMonth.from() erkannten Eigenschaften (außer calendar) enthält: era und eraYear, month, monthCode, year. Nicht angegebene Eigenschaften verwenden die Werte des ursprünglichen Jahr-Monats. Sie müssen nur eines von 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 angibt, wenn eine Datumskomponente außerhalb des Bereichs liegt. Mögliche Werte sind:

"constrain" (Standard)

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

"reject"

Es wird ein RangeError ausgelöst, wenn die Datumskomponente außerhalb des Bereichs liegt.

Rückgabewert

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

Beispiele

Verwendung von with()

js
const ym = Temporal.PlainYearMonth.from("2021-07");
const newYM = ym.with({ year: 2024 });
console.log(newYM.toString()); // "2024-07"

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

Spezifikationen

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

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch