Signatur
Beschreibung
Temporal.PlainYearMonth ist Teil der Temporal-API und modelliert einen bestimmten Monat innerhalb eines Jahres – losgelöst von Tag und Uhrzeit. Typische Anwendungsfälle sind Rechnungsperioden, Monatsbudgets, Abonnementzeiträume oder Kalenderansichten, bei denen nur Jahr und Monat relevant sind.
Objekte dieser Klasse sind unveränderlich (immutable): Alle Methoden, die einen veränderten Zustand liefern, geben stets ein neues Objekt zurück. Das verhindert schwer nachvollziehbare Mutation und erleichtert funktionale Programmiermuster.
Temporal.PlainYearMonth unterstützt mehrere Kalendersysteme (ISO 8601 ist der Standard, aber auch islamic, hebrew, chinese u. a. sind möglich). Beim Vergleich oder Kombinieren von Werten verschiedener Kalender ist Vorsicht geboten.
Da die Temporal-API noch kein offizieller Webstandard ist, wird in der Produktion ein Polyfill (z. B. @js-temporal/polyfill) benötigt. Die Spezifikation befindet sich im TC39-Stage-3-Prozess und kann sich noch geringfügig ändern.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $isoYear Pflicht | number | Das ISO-Jahr als ganzzahliger Wert, z. B. 2024. |
|
| $isoMonth Pflicht | number | Der ISO-Monat als Zahl von 1 (Januar) bis 12 (Dezember). |
|
| $calendar | string|Temporal.Calendar | "iso8601" | Optionaler Kalender-Bezeichner, z. B. "iso8601", "gregory" oder "hebrew". |
| $referenceISODay | number | 1 | Interner Referenztag für Kalenderimplementierungen, die einen Tag zur Darstellung des Monats benötigen. Normalerweise nicht manuell gesetzt. |
Rückgabewert
Temporal.PlainYearMonth-Instanz, die Jahr und Monat repräsentiert.Beispiele
Basisbeispiel: Instanz erstellen und Eigenschaften lesen
// Polyfill einbinden (Browser/Node ohne native Unterstützung)
// import { Temporal } from '@js-temporal/polyfill';
const ym = new Temporal.PlainYearMonth(2024, 3);
console.log(ym.year); // 2024
console.log(ym.month); // 3
console.log(ym.monthCode); // 'M03'
console.log(ym.daysInMonth); // 31
console.log(ym.toString()); // '2024-03'Monat addieren und mit Monatsende arbeiten
const budget = Temporal.PlainYearMonth.from('2024-01');
// Drei Monate später
const nextQuarter = budget.add({ months: 3 });
console.log(nextQuarter.toString()); // '2024-04'
// Alle Tage des Monats als PlainDate iterieren
const start = budget.toPlainDate({ day: 1 });
const days = budget.daysInMonth;
for (let d = 0; d < days; d++) {
const date = start.add({ days: d });
// z. B. Arbeitstage prüfen …
}
// Vergleich zweier YearMonth-Werte
const a = Temporal.PlainYearMonth.from('2023-12');
const b = Temporal.PlainYearMonth.from('2024-01');
console.log(Temporal.PlainYearMonth.compare(a, b)); // -1 (a liegt vor b)
console.log(a.equals(b)); // falseAus String parsen und in anderen Kalender konvertieren
// ISO-String parsen
const iso = Temporal.PlainYearMonth.from('2024-11');
// In den hebräischen Kalender übertragen
const hebrew = iso.withCalendar('hebrew');
console.log(hebrew.calendarId); // 'hebrew'
console.log(hebrew.year); // hebräisches Jahr (z. B. 5785)
// Wieder zurück zu ISO konvertieren
const backToISO = hebrew.withCalendar('iso8601');
console.log(backToISO.toString()); // '2024-11'// Wichtig · Fallstricke
Browser-Kompatibilität: Temporal ist noch nicht flächendeckend nativ verfügbar (Stand 2024). In V8 (Chrome/Node) hinter einem Flag, in Firefox und Safari experimentell. Für Produktionscode ist der Polyfill @js-temporal/polyfill empfohlen.
Unveränderlichkeit: Methoden wie add(), subtract() oder with() geben immer ein neues Objekt zurück – das Original bleibt unverändert.
Kein Tag, kein Datum: PlainYearMonth lässt sich nicht direkt mit PlainDate oder ZonedDateTime verrechnen, ohne explizit einen Tag anzugeben (über toPlainDate({ day })).
Kalender-Interoperabilität: Vergleiche und arithmetische Operationen zwischen Instanzen verschiedener Kalender werfen einen RangeError. Stets sicherstellen, dass beide Operanden denselben Kalender verwenden.