Intl.Locale.prototype.calendar — Eigenschaft · JavaScript-Referenz

Signatur

get Intl.Locale.prototype.calendar

Beschreibung

Die Accessor-Eigenschaft calendar einer Intl.Locale-Instanz liefert den Kalendertyp, der im Locale festgelegt ist. Er kann auf zwei Wegen gesetzt werden: über die Unicode-Erweiterung -u-ca- im Sprach-Tag (z. B. "th-TH-u-ca-buddhist") oder über die Option calendar im Konstruktor new Intl.Locale(tag, { calendar: "…" }). Gibt es beide, hat die Option Vorrang.

Wichtig: Die Eigenschaft gibt nur den ausdrücklich gesetzten Wert zurück. Fehlt die Angabe, ist das Ergebnis undefined. Der Standardkalender der Region wird dabei nicht ermittelt. Welche Kalender für ein Locale üblich sind, verrät Intl.Locale.prototype.getCalendars(). Welcher Kalender beim Formatieren tatsächlich verwendet wird, zeigt Intl.DateTimeFormat.prototype.resolvedOptions().calendar.

Typische Einsatzfälle sind das Auslesen und Prüfen von Benutzereinstellungen, das Weitergeben eines Locales samt Kalender an Intl.DateTimeFormat und die Normalisierung von Sprach-Tags. Gültige Werte sind BCP-47-Kalenderkennungen wie buddhist, chinese, coptic, ethiopic, gregory, hebrew, indian, islamic, islamic-umalqura, iso8601, japanese und persian. Eine vollständige Liste liefert Intl.supportedValuesOf("calendar").

Da es sich um eine reine Getter-Eigenschaft handelt, ist sie schreibgeschützt. Um einen anderen Kalender zu setzen, erzeugt man eine neue Intl.Locale-Instanz.

Rückgabewert

Typ

string | undefined

Beschreibung

Die kanonische Kalenderkennung in Kleinbuchstaben (z. B. "gregory") oder undefined, wenn im Locale kein Kalender festgelegt ist.

Beispiele

Kalender aus dem Sprach-Tag auslesen

const thai = new Intl.Locale("th-TH-u-ca-buddhist");
console.log(thai.calendar);

const de = new Intl.Locale("de-DE");
console.log(de.calendar);

buddhist undefined

Kalender per Option setzen – Option hat Vorrang

const loc = new Intl.Locale("ja-JP-u-ca-gregory", { calendar: "japanese" });
console.log(loc.calendar);
console.log(loc.toString());

japanese ja-JP-u-ca-japanese

Locale mit Kalender zum Formatieren von Datumsangaben nutzen

const datum = new Date(Date.UTC(2024, 0, 15));
const loc = new Intl.Locale("de-DE", { calendar: "hebrew" });

const fmt = new Intl.DateTimeFormat(loc, { dateStyle: "long", timeZone: "UTC" });
console.log(loc.calendar);
console.log(fmt.format(datum));
console.log(fmt.resolvedOptions().calendar);

hebrew 5. Schevat 5784 hebrew

Fallback auf den regionalen Standardkalender

const kalenderFuer = (tag) => {
  const loc = new Intl.Locale(tag);
  // calendar ist nur gesetzt, wenn explizit angegeben
  return loc.calendar ?? loc.getCalendars?.()[0] ?? "gregory";
};

console.log(kalenderFuer("fa-IR"));
console.log(kalenderFuer("en-US-u-ca-iso8601"));

persian iso8601

// Wichtig · Fallstricke

Kein Standardwert: calendar gibt undefined zurück, wenn kein Kalender angegeben wurde. Das gilt auch für Regionen wie th-TH, in denen ein anderer Kalender üblich ist. Für den tatsächlich verwendeten Kalender Intl.DateTimeFormat().resolvedOptions().calendar verwenden.
Nur lesbar: Die Eigenschaft hat keinen Setter. Eine Zuweisung wie loc.calendar = "gregory" bleibt wirkungslos (im Strict Mode TypeError).
Validierung: Der Konstruktor prüft nur, ob der Wert syntaktisch gültig ist (3–8 alphanumerische Zeichen pro Teil). Unbekannte, aber formal gültige Werte wie "foobar" werden akzeptiert, sonst wird ein RangeError geworfen. Zum Prüfen dient Intl.supportedValuesOf("calendar").
Kanonisierung: Veraltete Aliasse können normalisiert werden, etwa "islamicc" zu "islamic-civil" und "ethiopic-amete-alem" zu "ethioaa".
Kompatibilität: Intl.Locale ist seit Chrome 74, Firefox 75, Safari 14 und Node.js 12 verfügbar. getCalendars() ist neuer; in älteren Firefox-Versionen fehlt es, einige Engines kennen stattdessen nur den Getter calendars.

Siehe auch

Intl.Locale Intl.Locale.prototype.getCalendars() Intl.Locale.prototype.numberingSystem Intl.Locale.prototype.hourCycle Intl.DateTimeFormat Intl.Locale.prototype.variants