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

Signatur

get Intl.Locale.prototype.hourCycle

Beschreibung

Die Zugriffs-Eigenschaft hourCycle gibt an, welcher Stundenzyklus für eine Intl.Locale-Instanz gesetzt wurde. Der Stundenzyklus legt fest, ob die Uhrzeit im 12- oder 24-Stunden-Format angezeigt wird und bei welcher Zahl die Zählung beginnt:

"h11": 12-Stunden-Format, Zählung 0–11 (Mitternacht = 0:00 AM, z. B. in Japan gebräuchlich)
"h12": 12-Stunden-Format, Zählung 1–12 (Mitternacht = 12:00 AM, z. B. in den USA)
"h23": 24-Stunden-Format, Zählung 0–23 (Mitternacht = 0:00, z. B. in Deutschland)
"h24": 24-Stunden-Format, Zählung 1–24 (Mitternacht = 24:00, selten)

Es gibt zwei Wege, den Wert zu setzen: über die Unicode-Erweiterung hc im Sprach-Tag (z. B. "de-DE-u-hc-h12") oder über die Option hourCycle im Konstruktor new Intl.Locale(tag, { hourCycle }). Wenn beide angegeben sind, gilt die Option im Konstruktor.

Wichtig: Die Eigenschaft liefert nicht den üblichen Stundenzyklus einer Region. Hat man keinen Wert ausdrücklich gesetzt, ist das Ergebnis undefined. Den tatsächlich verwendeten Zyklus erhält man über Intl.DateTimeFormat.prototype.resolvedOptions().hourCycle oder über Intl.Locale.prototype.getHourCycles().

Rückgabewert

Typ

"h11" | "h12" | "h23" | "h24" | undefined

Beschreibung

Der ausdrücklich gesetzte Stundenzyklus der Locale. Wurde weder die Erweiterung -u-hc- noch die Option hourCycle angegeben, ist der Wert undefined.

Beispiele

Stundenzyklus per Option und per Unicode-Erweiterung setzen

const perOption = new Intl.Locale('en-US', { hourCycle: 'h23' });
console.log(perOption.hourCycle);
console.log(perOption.toString());

const perTag = new Intl.Locale('de-DE-u-hc-h12');
console.log(perTag.hourCycle);

// Die Option im Konstruktor gilt vor der Erweiterung im Tag
const beides = new Intl.Locale('ja-JP-u-hc-h12', { hourCycle: 'h11' });
console.log(beides.hourCycle);

h23 en-US-u-hc-h23 h12 h11

Fallstrick: ohne Angabe ist der Wert undefined – tatsächlichen Zyklus ermitteln

const locale = new Intl.Locale('de-DE');
console.log(locale.hourCycle); // nicht gesetzt

// Tatsächlich verwendeten Zyklus über DateTimeFormat ermitteln
const effektiv = new Intl.DateTimeFormat(locale, { hour: 'numeric' })
  .resolvedOptions().hourCycle;
console.log(effektiv);

const zyklus = locale.hourCycle ?? effektiv;
console.log(zyklus);

undefined h23 h23

Benutzereinstellung 12/24 Stunden bei der Zeitformatierung anwenden

const formatiereZeit = (datum, sprache, nutzt24h) => {
  const locale = new Intl.Locale(sprache, {
    hourCycle: nutzt24h ? 'h23' : 'h12'
  });
  return new Intl.DateTimeFormat(locale, {
    hour: 'numeric',
    minute: '2-digit'
  }).format(datum);
};

const termin = new Date(2024, 4, 15, 14, 30);
console.log(formatiereZeit(termin, 'en-US', true));
console.log(formatiereZeit(termin, 'de-DE', false));

14:30 2:30 PM

// Wichtig · Fallstricke

Kein Standardwert: hourCycle zeigt nicht, was in einer Region üblich ist. Ohne ausdrückliche Angabe ist der Wert undefined, auch bei "en-US".
Nur lesbar: Die Eigenschaft hat nur einen Getter. Eine Zuweisung wird ignoriert und löst im Strict Mode einen TypeError aus. Für einen anderen Wert erzeugt man eine neue Locale, z. B. new Intl.Locale(alt, { hourCycle: 'h23' }).
Ungültige Werte: Ein ungültiger Wert in der Option hourCycle, etwa "h13", löst einen RangeError aus.
Vorrang bei DateTimeFormat: Die Option hour12 von Intl.DateTimeFormat gilt vor hourCycle, auch vor einem Wert, der aus der Locale kommt. Deshalb sollte man die beiden Optionen nicht mischen.
Kompatibilität: Intl.Locale mit hourCycle gibt es ab Chrome 74, Firefox 75, Safari 14 und Node.js 12. Die ergänzende Methode getHourCycles() ist neuer und wird nicht überall unterstützt. Die ältere Zugriffs-Eigenschaft hourCycles gibt es nur in einigen Browsern, und sie ist veraltet.

Siehe auch

Intl.Locale Intl.Locale.prototype.getHourCycles() Intl.Locale.prototype.calendar Intl.DateTimeFormat Intl.DateTimeFormat.prototype.resolvedOptions()