new Temporal.PlainYearMonth() — Methode · JavaScript-Referenz

Signatur

new Temporal.PlainYearMonth(year, month, calendar, referenceDay)

Beschreibung

Der Konstruktor Temporal.PlainYearMonth() erstellt einen unveränderlichen Wert für eine Kombination aus Jahr und Monat. Das passt gut für Daten, bei denen der Tag keine Rolle spielt, etwa das Ablaufdatum einer Kreditkarte, einen Abrechnungszeitraum, eine Monatsübersicht im Kalender oder ein Berichtsintervall.

Die Argumente werden immer als ISO-8601-Werte gelesen, auch wenn Sie einen anderen Kalender angeben. year und month sind also Jahr und Monat im ISO-Kalender. Mit referenceDay legen Sie einen ISO-Tag fest. Er wird intern gespeichert, damit Monate in anderen Kalendern (z. B. "chinese" oder "hebrew") eindeutig bestimmt sind.

Der Konstruktor ist bewusst streng: Liegt ein Wert außerhalb des gültigen Bereichs (z. B. Monat 13), wird ein RangeError ausgelöst. Werte werden nicht korrigiert. Im Anwendungscode ist deshalb meist Temporal.PlainYearMonth.from() praktischer. Diese Methode nimmt Zeichenketten und Objekte mit Kalenderfeldern an und kann mit overflow: "constrain" ungültige Werte auf den nächsten gültigen Wert setzen.

Parameter

Name	Typ	Default	Beschreibung
$year Pflicht	number		ISO-Jahr als ganze Zahl. Bei Kommazahlen wird der Nachkommateil abgeschnitten. `Infinity` und `NaN` führen zu einem `RangeError`.
$month Pflicht	number		ISO-Monat von `1` (Januar) bis `12` (Dezember). Achtung: Die Zählung beginnt bei 1, nicht bei 0 wie bei `Date`.
$calendar	string	"iso8601"	Kalender-Kennung, z. B. `"iso8601"`, `"gregory"`, `"hebrew"` oder `"chinese"`. Groß- und Kleinschreibung spielt keine Rolle.
$referenceDay	number	1	ISO-Tag, der intern als Bezugspunkt gespeichert wird. Für den ISO-Kalender ist er praktisch egal. Bei anderen Kalendern bestimmt er, welcher Kalendermonat gemeint ist.

Rückgabewert

Typ

Temporal.PlainYearMonth

Beschreibung

Ein neues, unveränderliches Temporal.PlainYearMonth-Objekt für das angegebene Jahr und den angegebenen Monat.

Beispiele

Einfache Instanziierung und Eigenschaften

const ym = new Temporal.PlainYearMonth(2024, 2);

console.log(ym.toString());   // ISO-Darstellung
console.log(ym.year, ym.month);
console.log(ym.daysInMonth);  // Schaltjahr!
console.log(ym.inLeapYear);

2024-02 2024 2 29 true

Strenge Validierung im Vergleich zu from()

try {
  new Temporal.PlainYearMonth(2024, 13);
} catch (err) {
  console.log(err.name);
}

// from() kann ungültige Werte korrigieren
const korrigiert = Temporal.PlainYearMonth.from(
  { year: 2024, month: 13 },
  { overflow: 'constrain' }
);
console.log(korrigiert.toString());

RangeError 2024-12

Prüfen, ob eine Kreditkarte abgelaufen ist

const istAbgelaufen = (jahr, monat) => {
  const ablauf = new Temporal.PlainYearMonth(jahr, monat);
  const heute = Temporal.Now.plainDateISO().toPlainYearMonth();
  // Die Karte gilt bis einschließlich des Ablaufmonats
  return Temporal.PlainYearMonth.compare(ablauf, heute) < 0;
};

console.log(istAbgelaufen(2020, 5));
console.log(istAbgelaufen(2099, 12));

true false

Monatsliste für einen Bericht erzeugen

const start = new Temporal.PlainYearMonth(2024, 11);

const monate = Array.from({ length: 3 }, (_, i) =>
  start.add({ months: i }).toString()
);

console.log(monate);

[ '2024-11', '2024-12', '2025-01' ]

// Wichtig · Fallstricke

Nur mit new aufrufen: Ohne new wird ein TypeError ausgelöst.
Monate zählen ab 1: Anders als bei Date steht 1 für Januar. Wer alten Date-Code überträgt, macht hier leicht einen Fehler um eins.
Keine Korrektur ungültiger Werte: Der Konstruktor löst bei Werten außerhalb des Bereichs immer einen RangeError aus. Für Benutzereingaben ist Temporal.PlainYearMonth.from() meist die bessere Wahl.
Andere Kalender: year und month sind immer ISO-Werte, keine Werte im Zielkalender. Um z. B. einen hebräischen Monat anzugeben, verwenden Sie from({ year, monthCode, calendar }). Bei anderen Kalendern als ISO enthält toString() auch den Bezugstag und die Kalender-Kennung, z. B. 2024-03-01[u-ca=hebrew].
Vergleiche: < und > funktionieren nicht, denn valueOf() löst einen TypeError aus. Nutzen Sie Temporal.PlainYearMonth.compare() oder equals().
Browser-Unterstützung: Temporal ist neu. Es steht ab Firefox 139 und Chrome 144 zur Verfügung, in Safari noch nicht stabil. Für eine breite Unterstützung brauchen Sie einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainYearMonth Temporal.PlainYearMonth.from() Temporal.PlainYearMonth.compare() Temporal.PlainYearMonth.prototype.add() Temporal.PlainYearMonth.prototype.toPlainDate() Temporal.PlainDate Temporal.PlainMonthDay