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

Signatur

Temporal.PlainDateTime.prototype.withCalendar(calendar)

Beschreibung

withCalendar() wechselt nur das Kalendersystem eines Temporal.PlainDateTime. Der zugrunde liegende Tag im ISO-8601-Kalender und die Uhrzeit bleiben gleich. Anders wird nur, wie Datumsfelder wie year, month, monthCode, day, era oder daysInMonth berechnet werden. Stunde, Minute, Sekunde und Sekundenbruchteile ändern sich nicht.

Die Methode ist nützlich, wenn Sie ein Datum in einem regionalen oder religiösen Kalender anzeigen oder damit rechnen wollen, zum Beispiel im hebräischen, islamischen, japanischen oder buddhistischen Kalender. Nach dem Wechsel arbeiten auch add(), with() und until() mit den Regeln des neuen Kalenders, etwa mit dessen Monatslängen und Schaltmonaten.

Wie alle Temporal-Objekte ist PlainDateTime unveränderlich. Das Ausgangsobjekt bleibt also unverändert, und Sie erhalten immer eine neue Instanz. Um wieder zum Standardkalender zu wechseln, rufen Sie withCalendar("iso8601") auf.

Parameter

Name	Typ	Default	Beschreibung
$calendar Pflicht	string \| Temporal.PlainDate \| Temporal.PlainDateTime \| Temporal.PlainMonthDay \| Temporal.PlainYearMonth \| Temporal.ZonedDateTime		Kalenderkennung wie `"iso8601"`, `"gregory"`, `"hebrew"`, `"japanese"`, `"islamic-umalqura"` oder `"chinese"`. Auch ein vollständiger ISO-String mit Annotation `[u-ca=…]` ist erlaubt. Wenn Sie ein Temporal-Objekt übergeben, wird dessen Kalender übernommen.

Rückgabewert

Typ

Temporal.PlainDateTime

Beschreibung

Ein neues Temporal.PlainDateTime mit demselben ISO-Datum und derselben Uhrzeit, das jetzt im angegebenen Kalender ausgewertet wird.

Beispiele

Datum im hebräischen Kalender auswerten

const dt = Temporal.PlainDateTime.from("2024-04-23T18:30:00");
const hebrew = dt.withCalendar("hebrew");

console.log(hebrew.year, hebrew.monthCode, hebrew.day);
console.log(hebrew.hour, hebrew.minute); // Uhrzeit bleibt gleich
console.log(hebrew.toString());

5784 M07 15 18 30 2024-04-23T18:30:00[u-ca=hebrew]

Japanische Ära und Ära-Jahr ermitteln

const dt = Temporal.PlainDateTime.from("2021-07-01T12:34:56");
const jp = dt.withCalendar("japanese");

console.log(jp.era, jp.eraYear);
console.log(jp.toLocaleString("ja-JP", { calendar: "japanese", dateStyle: "long" }));

reiwa 3 令和3年7月1日

Kalender einer anderen Instanz übernehmen und zurück zu ISO wechseln

const termin = Temporal.PlainDateTime.from("2025-03-10T09:00");
const referenz = Temporal.PlainDate.from("2025-01-01[u-ca=islamic-umalqura]");

const islamisch = termin.withCalendar(referenz); // übernimmt den Kalender der Referenz
console.log(islamisch.calendarId);

const iso = islamisch.withCalendar("iso8601");
console.log(iso.toString());
console.log(iso.equals(termin));

islamic-umalqura 2025-03-10T09:00:00 true

Vergleich: equals() berücksichtigt den Kalender, compare() nicht

const a = Temporal.PlainDateTime.from("2024-12-24T20:00");
const b = a.withCalendar("gregory");

console.log(a.equals(b));                          // unterschiedliche Kalender
console.log(Temporal.PlainDateTime.compare(a, b)); // gleicher Zeitpunkt

false 0

// Wichtig · Fallstricke

Nur die Anzeige ändert sich, nicht der Zeitpunkt: withCalendar() rechnet kein Datum um. Das ISO-Datum bleibt gleich, nur year, month, day usw. werden neu berechnet. Wenn Sie stattdessen einzelne Felder setzen wollen, nutzen Sie with().
month und monthCode unterscheiden sich: In Kalendern mit Schaltmonaten, zum Beispiel hebrew oder chinese, zählt month die Monate im Jahr einfach durch. monthCode ist dagegen die feste Bezeichnung des Monats. Für stabile Vergleiche über mehrere Jahre sollten Sie monthCode verwenden.
Fehler: Eine unbekannte Kalenderkennung löst einen RangeError aus. Ein Wert, der weder String noch Temporal-Objekt ist, löst einen TypeError aus. Groß- und Kleinschreibung spielt keine Rolle, und Aliasnamen werden in die kanonische Form umgewandelt (z. B. \"islamicc\" → \"islamic-civil\").
equals() vergleicht auch den Kalender: Zwei Objekte mit demselben Datum, aber unterschiedlichem Kalender sind nicht equals(). Temporal.PlainDateTime.compare() vergleicht dagegen nur den Zeitpunkt.
Kompatibilität: Temporal wird noch nicht überall unterstützt. Firefox unterstützt es ab 139, Chrome und Edge ab 144; in Safari und älteren Node.js-Versionen brauchen Sie den Polyfill @js-temporal/polyfill. Welche Kalender außer iso8601 verfügbar sind, hängt von den Intl-Daten der jeweiligen Umgebung ab (z. B. Node.js mit small-icu).

Siehe auch

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