Signatur
Beschreibung
Temporal.PlainDate ist Teil der Temporal API und modelliert ein Datum bestehend aus Jahr, Monat und Tag, vollständig losgelöst von Zeitzonen und Uhrzeiten. Es eignet sich hervorragend für Anwendungsfälle wie Geburtstage, Feiertage oder andere ganztägige Ereignisse, bei denen der genaue Zeitpunkt im Tagesverlauf irrelevant ist.
Im Gegensatz zum klassischen Date-Objekt ist Temporal.PlainDate unveränderlich (immutable): Methoden wie add(), subtract() oder with() geben stets neue Instanzen zurück. Das verhindert ungewollte Seiteneffekte durch gemeinsam genutzte Referenzen.
Die Klasse unterstützt verschiedene Kalender-Systeme (z. B. ISO 8601, hebräisch, islamisch, japanisch) über den optionalen calendar-Parameter. Ohne Angabe wird der ISO-8601-Kalender verwendet. Alle arithmetischen Operationen berücksichtigen die kalendarischen Regeln des jeweiligen Systems.
Da sich die Temporal API noch im TC39-Stage-3-Stadium befindet, ist ein Polyfill (z. B. @js-temporal/polyfill) für den produktiven Einsatz in aktuellen Browsern erforderlich. Native Unterstützung ist in modernen Browsern in Vorbereitung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $isoYear Pflicht | number | Das Jahr im ISO-8601-Kalender (z. B. 2024). Negative Werte sind für Jahre vor Christus zulässig. |
|
| $isoMonth Pflicht | number | Der Monat als Integer von 1 (Januar) bis 12 (Dezember). |
|
| $isoDay Pflicht | number | Der Tag des Monats als Integer von 1 bis zum letzten Tag des jeweiligen Monats. |
|
| $calendar | string|Temporal.Calendar | "iso8601" | Das zu verwendende Kalender-System, z. B. "hebrew", "islamic" oder "japanese". Standardmäßig wird ISO 8601 verwendet. |
Rückgabewert
Temporal.PlainDate-Instanz, die das angegebene Datum repräsentiert.Beispiele
Grundlegende Erstellung und Eigenschaften
// Erstellung eines PlainDate-Objekts
const geburtstag = new Temporal.PlainDate(1990, 6, 15);
console.log(geburtstag.year); // 1990
console.log(geburtstag.month); // 6
console.log(geburtstag.day); // 15
console.log(geburtstag.dayOfWeek); // 5 (Freitag, 1 = Montag)
console.log(geburtstag.toString()); // "1990-06-15"
// Aus einem ISO-String parsen
const feiertag = Temporal.PlainDate.from("2024-12-25");
console.log(feiertag.toString()); // "2024-12-25"Datumsarithmetik und Vergleiche
const heute = Temporal.PlainDate.from("2024-03-01");
// Tage addieren
const inZweiWochen = heute.add({ weeks: 2 });
console.log(inZweiWochen.toString()); // "2024-03-15"
// Monate subtrahieren
const vorEinemMonat = heute.subtract({ months: 1 });
console.log(vorEinemMonat.toString()); // "2024-02-01"
// Differenz zwischen zwei Daten berechnen
const projektstart = Temporal.PlainDate.from("2024-01-15");
const projektende = Temporal.PlainDate.from("2024-04-30");
const dauer = projektstart.until(projektende, { largestUnit: "months" });
console.log(`${dauer.months} Monate und ${dauer.days} Tage`); // "3 Monate und 15 Tage"
// Vergleich zweier Daten
const vergleich = Temporal.PlainDate.compare(projektstart, projektende);
console.log(vergleich); // -1 (projektstart liegt vor projektende)
// Datum anpassen (with gibt neue Instanz zurück)
const jahresende = heute.with({ month: 12, day: 31 });
console.log(jahresende.toString()); // "2024-12-31"Verwendung alternativer Kalender
// Hebräischer Kalender
const hebraeisch = new Temporal.PlainDate(2024, 3, 1, "hebrew");
console.log(hebraeisch.calendarId); // "hebrew"
console.log(hebraeisch.toLocaleString("de-DE", { calendar: "hebrew" }));
// ISO-Datum in ein PlainDateTime umwandeln
const datum = Temporal.PlainDate.from("2024-07-04");
const mitUhrzeit = datum.toPlainDateTime({ hour: 9, minute: 0 });
console.log(mitUhrzeit.toString()); // "2024-07-04T09:00:00"// Wichtig · Fallstricke
Noch kein nativer Browser-Support: Temporal.PlainDate ist Teil des TC39-Stage-3-Proposals. Für den produktiven Einsatz wird der Polyfill @js-temporal/polyfill empfohlen. Erste native Implementierungen sind in einigen Browsern in Entwicklung.
Unveränderlichkeit beachten: Alle Methoden wie add(), subtract() und with() geben neue Instanzen zurück — das Original wird nie verändert.
Kein Vergleich mit == oder ===: Da es sich um Objekte handelt, vergleicht === nur Referenzen. Für inhaltliche Vergleiche Temporal.PlainDate.compare(a, b) oder a.equals(b) verwenden.
Kalender-Kompatibilität: Bei Operationen zwischen PlainDate-Objekten mit unterschiedlichen Kalendern wird eine RangeError-Exception geworfen. Stets denselben Kalender verwenden oder explizit konvertieren.