Intl.Locale.prototype.getHourCycles() — Methode · JavaScript-Referenz

Signatur

Intl.Locale.prototype.getHourCycles()

Beschreibung

Die Methode getHourCycles() einer Intl.Locale-Instanz liefert die Stundenzyklen, die in der jeweiligen Sprache/Region für die Uhrzeitanzeige verwendet werden. So erfahren Sie z. B., ob eine Locale üblicherweise die 12-Stunden-Uhr mit AM/PM ("h12") oder die 24-Stunden-Uhr ("h23") nutzt, ohne dafür erst ein Datum formatieren zu müssen.

Die möglichen Kennungen sind:

"h11" – 12-Stunden-System, Stunden 0–11 (Mitternacht = 0:00 AM)
"h12" – 12-Stunden-System, Stunden 1–12 (Mitternacht = 12:00 AM)
"h23" – 24-Stunden-System, Stunden 0–23 (Mitternacht = 0:00)
"h24" – 24-Stunden-System, Stunden 1–24 (Mitternacht = 24:00)

Das Array ist nach Präferenz sortiert: Der erste Eintrag ist der bevorzugte Zyklus. Enthält das Locale-Tag die Unicode-Erweiterung -u-hc-… (bzw. wurde die Option hourCycle im Konstruktor gesetzt), besteht das Ergebnis nur aus genau diesem einen Wert.

Typische Einsatzgebiete sind Zeitauswahl-Komponenten (Time-Picker), die ihr Layout (AM/PM-Umschalter ja oder nein) an die Nutzer-Locale anpassen, oder Einstellungsdialoge, die einen sinnvollen Standardwert für das Uhrzeitformat vorbelegen.

Rückgabewert

Typ

string[]

Beschreibung

Ein neues Array aus Zeichenketten mit Stundenzyklus-Kennungen ("h11", "h12", "h23", "h24"), nach Präferenz sortiert. Bei gesetzter hc-Erweiterung enthält es genau einen Eintrag. Jeder Aufruf liefert eine neue Kopie.

Beispiele

Stundenzyklen verschiedener Locales abfragen

const locales = ['en-US', 'de-DE', 'fr-FR'];

for (const tag of locales) {
  const locale = new Intl.Locale(tag);
  console.log(tag, locale.getHourCycles());
}

en-US [ 'h12' ] de-DE [ 'h23' ] fr-FR [ 'h23' ]

Explizit gesetzter Stundenzyklus über Erweiterung oder Option

// Über Unicode-Erweiterung im Tag
const viaTag = new Intl.Locale('en-US-u-hc-h23');
console.log(viaTag.getHourCycles());

// Über die Konstruktor-Option
const viaOption = new Intl.Locale('de-DE', { hourCycle: 'h12' });
console.log(viaOption.getHourCycles());
console.log(viaOption.hourCycle);

[ 'h23' ] [ 'h12' ] h12

Time-Picker: 12- oder 24-Stunden-Anzeige mit Fallback ermitteln

const getPreferredHourCycle = (tag) => {
  const locale = new Intl.Locale(tag);

  // Standardmethode
  if (typeof locale.getHourCycles === 'function') {
    return locale.getHourCycles()[0];
  }
  // Ältere Chromium-Versionen: Getter hourCycles
  if (Array.isArray(locale.hourCycles)) {
    return locale.hourCycles[0];
  }
  // Fallback für z. B. Firefox
  return new Intl.DateTimeFormat(tag, { hour: 'numeric' })
    .resolvedOptions().hourCycle;
};

const cycle = getPreferredHourCycle(navigator.language ?? 'de-DE');
const uses12h = cycle === 'h11' || cycle === 'h12';
console.log(`AM/PM-Umschalter anzeigen: ${uses12h}`);

AM/PM-Umschalter anzeigen: false // bei de-DE

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Methode stammt aus dem Vorschlag „Intl Locale Info“. Chromium hat ursprünglich einen Getter hourCycles (ab Version 99) ausgeliefert, der inzwischen durch getHourCycles() ersetzt wurde. Safari unterstützt die Methode ab Version 17, Firefox bislang nicht. Nutzen Sie daher immer eine Feature-Erkennung und als Fallback Intl.DateTimeFormat.prototype.resolvedOptions().hourCycle.
Nicht mit hourCycle verwechseln: Die Eigenschaft Intl.Locale.prototype.hourCycle gibt nur den explizit gesetzten Wert (oder undefined) zurück, während getHourCycles() auch die Standardwerte der Locale aus den CLDR-Daten liefert.
Die Ergebnisse basieren auf den CLDR-Daten der jeweiligen Engine und können sich zwischen Browser- bzw. Node.js-Versionen unterscheiden. Codieren Sie konkrete Werte nicht fest in Tests.
Für die eigentliche Formatierung ist in der Regel die Option hour12 bzw. hourCycle von Intl.DateTimeFormat zuständig. getHourCycles() dient nur zur Abfrage.

Siehe auch

Intl.Locale Intl.Locale.prototype.hourCycle Intl.Locale.prototype.getCalendars() Intl.Locale.prototype.getTimeZones() Intl.Locale.prototype.getWeekInfo() Intl.DateTimeFormat.prototype.resolvedOptions()