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

Signatur

new Temporal.PlainDate(year, month, day, calendar)

Beschreibung

Der Konstruktor Temporal.PlainDate() erzeugt ein unveränderliches Objekt, das ein Kalenderdatum ohne Uhrzeit und ohne Zeitzone darstellt. Beispiele dafür sind Geburtstage, Feiertage, Fälligkeitstermine oder Buchungstage. Anders als beim alten Date gibt es keine versteckte Uhrzeit um Mitternacht und keine Verschiebung durch die lokale Zeitzone.

Die drei Zahlen werden immer als ISO-8601-Werte interpretiert. Der Monat zählt dabei ab 1 (Januar = 1, nicht 0 wie bei Date). Mit dem optionalen vierten Argument legst du einen anderen Kalender fest, etwa "japanese" oder "hebrew". Das Datum wird dann in diesem Kalender dargestellt, die übergebenen Werte bleiben aber ISO-Werte.

Der Konstruktor ist streng: Ein ungültiges Datum wie der 30. Februar löst sofort einen RangeError aus. Es wird nichts stillschweigend korrigiert. In Anwendungscode ist deshalb oft Temporal.PlainDate.from() die bessere Wahl. Diese Methode nimmt auch Strings und Objekte an und kann mit der Option overflow: "constrain" Werte auf den gültigen Bereich begrenzen.

Parameter

Name	Typ	Default	Beschreibung
$year Pflicht	number		ISO-Jahr als ganze Zahl, auch negativ oder 0 (astronomische Zählung). Nachkommastellen werden abgeschnitten.
$month Pflicht	number		ISO-Monat von `1` bis `12`.
$day Pflicht	number		ISO-Tag von `1` bis zur Anzahl der Tage im jeweiligen Monat.
$calendar	string	"iso8601"	Kalender-ID, z. B. `"gregory"`, `"japanese"`, `"hebrew"` oder `"islamic-umalqura"`. Groß-/Kleinschreibung spielt keine Rolle.

Rückgabewert

Typ

Temporal.PlainDate

Beschreibung

Ein neues, unveränderliches Temporal.PlainDate-Objekt. Bei ungültigen Werten wird ein RangeError ausgelöst.

Beispiele

Einfaches Datum erzeugen und auslesen

const termin = new Temporal.PlainDate(2024, 3, 15);

console.log(termin.toString());
console.log(termin.dayOfWeek);   // 1 = Montag … 7 = Sonntag
console.log(termin.daysInMonth);
console.log(termin.toLocaleString('de-DE', { dateStyle: 'full' }));

2024-03-15 5 31 Freitag, 15. März 2024

Strenge Prüfung: ungültiges Datum vs. from()

try {
  new Temporal.PlainDate(2023, 2, 29); // 2023 ist kein Schaltjahr
} catch (err) {
  console.log(err.constructor.name);
}

// from() begrenzt standardmäßig auf den gültigen Bereich
const korrigiert = Temporal.PlainDate.from(
  { year: 2023, month: 2, day: 29 },
  { overflow: 'constrain' }
);
console.log(korrigiert.toString());

RangeError 2023-02-28

Fälligkeitsdatum berechnen (Monatsende-Logik)

const rechnungsdatum = new Temporal.PlainDate(2024, 1, 31);
const faellig = rechnungsdatum.add({ months: 1 });

console.log(faellig.toString());
console.log(rechnungsdatum.until(faellig).days);
// Das Original bleibt unverändert (immutable)
console.log(rechnungsdatum.toString());

2024-02-29 29 2024-01-31

Datum mit anderem Kalender

// Die Argumente sind immer ISO-Werte, nur die Darstellung ändert sich
const datum = new Temporal.PlainDate(2024, 3, 15, 'japanese');

console.log(datum.toString());
console.log(datum.era, datum.eraYear);
console.log(datum.calendarId);

2024-03-15[u-ca=japanese] reiwa 6 japanese

// Wichtig · Fallstricke

Monat zählt ab 1: Anders als bei new Date(2024, 2, 15) steht new Temporal.PlainDate(2024, 3, 15) für den 15. März. Das ist beim Umstieg eine häufige Fehlerquelle.
Nur mit new: Ein Aufruf ohne new löst einen TypeError aus.
Keine automatische Korrektur: Werte außerhalb des gültigen Bereichs (z. B. Monat 13 oder der 31. April) führen zu einem RangeError. Infinity und NaN sind ebenfalls ungültig. Wenn Werte begrenzt statt abgelehnt werden sollen, nimm Temporal.PlainDate.from() mit overflow: "constrain".
Kalender-Argument: Das Jahr ist immer das ISO-Jahr, auch wenn ein anderer Kalender angegeben ist. Ein Datum mit kalenderspezifischen Feldern (z. B. era/eraYear oder hebräischer Monat) erzeugst du mit Temporal.PlainDate.from({ ..., calendar }). Kalender-Objekte werden nicht mehr unterstützt, nur noch String-IDs.
Wertebereich: Erlaubt sind Daten von etwa -271821-04-19 bis +275760-09-13.
Vergleich: === vergleicht Objekt-Referenzen. Für Datumsvergleiche nimm equals() oder Temporal.PlainDate.compare().
Browser-Kompatibilität: Temporal ist neu. Unterstützt wird es in Firefox ab 139 und in Chromium-Browsern ab 144. Safari und ältere Node.js-Versionen brauchen einen Polyfill, etwa @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDate Temporal.PlainDate.from() Temporal.PlainDate.compare() Temporal.PlainDate.prototype.add() Temporal.PlainDateTime Temporal.Now.plainDateISO() Date