Temporal.PlainDate.prototype.withCalendar() — Methode · JavaScript-Referenz

Signatur

Temporal.PlainDate.prototype.withCalendar(calendar)

Beschreibung

withCalendar() wandelt ein Temporal.PlainDate in ein anderes Kalendersystem um. Der Tag selbst bleibt gleich, also dasselbe zugrunde liegende ISO-Datum. Es ändert sich nur, wie dieser Tag dargestellt wird: Eigenschaften wie year, month, monthCode, day, era oder daysInMonth werden nach den Regeln des neuen Kalenders berechnet.

Die Methode ist nützlich, wenn ein Datum in einem Kalender gespeichert oder berechnet wird, meist "iso8601", aber in einem regionalen Kalender angezeigt oder weiterverarbeitet werden soll. Dazu gehören etwa der hebräische Kalender für jüdische Feiertage, der japanische Kalender mit Ären oder "islamic-umalqura". Auch Datumsarithmetik mit add(), until() und ähnlichen Methoden folgt danach den Regeln des neuen Kalenders, z. B. bei Monatslängen und Schaltmonaten.

Wie alle Temporal-Objekte ist PlainDate unveränderlich. Die Methode gibt immer eine neue Instanz zurück, das Original bleibt unverändert. Das Kalenderfeld lässt sich nicht über with() ändern, dafür gibt es genau diese Methode.

Parameter

Name	Typ	Default	Beschreibung
$calendar Pflicht	string \| Temporal.PlainDate \| Temporal.PlainDateTime \| Temporal.ZonedDateTime \| Temporal.PlainYearMonth \| Temporal.PlainMonthDay		Kalender-ID wie `"iso8601"`, `"gregory"`, `"hebrew"`, `"japanese"`, `"chinese"` oder `"islamic-umalqura"`. Alternativ ein Temporal-Objekt, dessen Kalender übernommen wird. Groß- und Kleinschreibung spielt bei der ID keine Rolle.

Rückgabewert

Typ

Temporal.PlainDate

Beschreibung

Ein neues Temporal.PlainDate für dasselbe ISO-Datum, aber mit dem angegebenen Kalendersystem.

Beispiele

ISO-Datum im hebräischen Kalender darstellen

const date = Temporal.PlainDate.from("2024-03-15");
const hebrew = date.withCalendar("hebrew");

console.log(hebrew.toString());
console.log(hebrew.year, hebrew.month, hebrew.monthCode, hebrew.day);
console.log(date.calendarId); // Original bleibt unverändert

2024-03-15[u-ca=hebrew] 5784 7 M06 5 iso8601

Japanische Ära für ein Formular bestimmen

const birthday = Temporal.PlainDate.from("2024-03-15");
const jp = birthday.withCalendar("japanese");

console.log(`${jp.era} ${jp.eraYear}, Monat ${jp.month}, Tag ${jp.day}`);

reiwa 6, Monat 3, Tag 15

Vergleich: gleicher Tag, verschiedene Kalender

const iso = Temporal.PlainDate.from("2024-03-15");
const hebrew = iso.withCalendar("hebrew");

// equals() berücksichtigt auch den Kalender
console.log(iso.equals(hebrew));
// compare() vergleicht nur die Position auf der Zeitachse
console.log(Temporal.PlainDate.compare(iso, hebrew));
// Zurück nach ISO
console.log(hebrew.withCalendar("iso8601").equals(iso));

false 0 true

Monatsarithmetik im Zielkalender

const start = Temporal.PlainDate.from("2024-03-15").withCalendar("hebrew");
// Ein hebräischer Monat später (nicht ein ISO-Monat!)
const next = start.add({ months: 1 });

console.log(next.withCalendar("iso8601").toString());

2024-04-13

// Wichtig · Fallstricke

Ungültige Eingaben: Eine unbekannte Kalender-ID löst einen RangeError aus. Andere Typen wie Zahlen oder normale Objekte lösen einen TypeError aus. Fehlt das Argument, gibt es ebenfalls einen TypeError.
with() ist kein Ersatz: date.with({ calendar: \"hebrew\" }) funktioniert nicht und wirft einen TypeError. Nutze dafür withCalendar().
month und monthCode unterscheiden sich: In Kalendern mit Schaltmonaten, etwa dem hebräischen oder chinesischen, ist month nur die laufende Nummer im Jahr. Wenn du einen bestimmten Monat meinst, verwende monthCode, z. B. \"M05L\" für Adar I.
equals() und compare() verhalten sich unterschiedlich: equals() liefert false, wenn sich die Kalender unterscheiden. Temporal.PlainDate.compare() vergleicht dagegen nur die ISO-Daten.
Welche Kalender verfügbar sind, hängt von der Engine ab: Die Liste richtet sich nach den ICU- bzw. Intl-Daten der Umgebung. Prüfen lässt sie sich mit Intl.supportedValuesOf(\"calendar\").
Kompatibilität: Temporal gibt es in Firefox ab Version 139 und in Chrome/Edge ab Version 144. Safari und ältere Node.js-Versionen unterstützen es noch nicht. Dort brauchst du einen Polyfill wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime.prototype.withCalendar() Temporal.PlainDate.prototype.with() Temporal.PlainDate.prototype.since() Temporal.ZonedDateTime.prototype.withCalendar() Temporal.PlainDate.prototype.add()