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

Signatur

Temporal.ZonedDateTime.prototype.withCalendar(calendar)

Beschreibung

withCalendar() tauscht nur das Kalendersystem eines Temporal.ZonedDateTime aus. Zeitpunkt (epochNanoseconds), Zeitzone und Uhrzeit bleiben gleich. Neu berechnet werden nur die kalenderabhängigen Felder wie year, month, monthCode, day, era, eraYear, daysInMonth oder inLeapYear.

Die Methode brauchst du, wenn du einen Zeitpunkt in einem nicht-gregorianischen Kalender anzeigen oder damit rechnen willst, zum Beispiel im japanischen, hebräischen, islamischen, persischen oder buddhistischen Kalender. Arithmetik wie add({ months: 1 }) folgt danach den Regeln des neuen Kalenders. Ein „Monat“ kann dann also eine andere Länge haben.

Wie alle Temporal-Objekte ist ZonedDateTime unveränderlich: Das Original bleibt unverändert und du bekommst immer eine neue Instanz zurück. Das Gegenstück zum Wechseln der Zeitzone ist withTimeZone().

Parameter

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

Rückgabewert

Typ

Temporal.ZonedDateTime

Beschreibung

Ein neues Temporal.ZonedDateTime mit demselben Zeitpunkt und derselben Zeitzone, aber dem angegebenen Kalender.

Beispiele

In den japanischen Kalender wechseln

const zdt = Temporal.ZonedDateTime.from("2024-03-15T10:30:00+01:00[Europe/Berlin]");
const jp = zdt.withCalendar("japanese");

console.log(jp.toString());
console.log(jp.era, jp.eraYear); // Ära Reiwa, Jahr 6
console.log(zdt.calendarId);     // Original bleibt unverändert

2024-03-15T10:30:00+01:00[Europe/Berlin][u-ca=japanese] reiwa 6 iso8601

Hebräisches Datum für einen Termin ermitteln

const termin = Temporal.ZonedDateTime.from("2024-03-15T18:00:00+02:00[Asia/Jerusalem]");
const hebr = termin.withCalendar("hebrew");

console.log(hebr.year, hebr.monthCode, hebr.day);
console.log(hebr.inLeapYear); // 5784 ist ein Schaltjahr (Adar I + Adar II)

5784 M06 5 true

Gleicher Zeitpunkt, aber nicht „gleich“

const a = Temporal.ZonedDateTime.from("2024-03-15T10:30:00+01:00[Europe/Berlin]");
const b = a.withCalendar("buddhist");

console.log(a.epochNanoseconds === b.epochNanoseconds); // derselbe Zeitpunkt
console.log(Temporal.ZonedDateTime.compare(a, b));      // vergleicht nur den Zeitpunkt
console.log(a.equals(b));                              // berücksichtigt auch den Kalender
console.log(b.year);                                   // buddhistische Zeitrechnung

true 0 false 2567

Monatsarithmetik im Zielkalender

const start = Temporal.ZonedDateTime.from("2024-03-15T09:00:00+01:00[Europe/Berlin]")
  .withCalendar("hebrew");

// "Ein Monat später" im hebräischen Kalender
const naechster = start.add({ months: 1 });

// Zur Kontrolle wieder im ISO-Kalender ausgeben
console.log(naechster.withCalendar("iso8601").toPlainDate().toString());

2024-04-13

// Wichtig · Fallstricke

Fehler: Eine unbekannte Kalender-ID löst einen RangeError aus. Ist das Argument weder ein String noch ein Temporal-Objekt mit Kalender, gibt es einen TypeError. Auch das Weglassen des Arguments führt zu einem TypeError, denn es gibt keinen Standardwert.
equals() und compare(): equals() vergleicht auch Kalender und Zeitzone. Zwei Objekte, die sich nur im Kalender unterscheiden, sind also nicht gleich. Temporal.ZonedDateTime.compare() vergleicht dagegen nur den Zeitpunkt.
Kalender-Objekte gibt es nicht mehr: Frühere Entwürfe des Vorschlags kannten Temporal.Calendar-Objekte und eigene Kalender. Beides wurde gestrichen, heute gehen nur noch String-IDs.
with({ calendar }) geht nicht: Den Kalender kannst du nicht über with() ändern. Dafür ist withCalendar() da.
Unterstützte Kalender: Welche Kalender es gibt, hängt von den ICU-Daten der Umgebung ab. Intl.supportedValuesOf(\"calendar\") liefert die Liste.
Kompatibilität: Temporal ist noch nicht überall verfügbar. Native Unterstützung gibt es in Firefox 139+ und in Chromium-Browsern ab Version 144, Safari und ältere Node.js-Versionen fehlen noch. Für den Produktiveinsatz brauchst du einen Polyfill, etwa @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

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