</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Date.prototype.toLocaleTimeString()

Date.prototype.toLocaleTimeString()

Methode

Gibt den Uhrzeit-Anteil eines <code>Date</code>-Objekts als sprachabhängig formatierten String zurück, standardmäßig in der lokalen Zeitzone.

seit JavaScript ES1; Parameter locales/options ab ES5.1 (ECMA-402) Kategorie: method-property

Signatur

Date.prototype.toLocaleTimeString(locales, options)

Beschreibung

toLocaleTimeString() wandelt nur die Uhrzeit eines Date-Objekts in eine gut lesbare, an Sprache und Region angepasste Darstellung um – etwa 14:05:09 im Deutschen oder 2:05:09 PM im amerikanischen Englisch. Das Datum wird dabei weggelassen.

Über locales legst du die Sprache fest (z. B. "de-DE"), über options steuerst du die Ausgabe genau: Stunden/Minuten/Sekunden einzeln ein- oder ausblenden, 12- oder 24-Stunden-Format (hour12, hourCycle), eine andere Zeitzone (timeZone) oder den Namen der Zeitzone (timeZoneName). In Umgebungen mit Intl-Unterstützung wird intern Intl.DateTimeFormat verwendet.

Die Methode eignet sich für Anzeigen in der Oberfläche – Uhrzeiten in Chats, Logs für Nutzer, Terminlisten. Für maschinenlesbare Formate (Speichern, APIs) ist sie ungeeignet; nutze dafür toISOString(). Wenn du viele Werte formatierst, erstelle einmalig ein Intl.DateTimeFormat-Objekt und verwende dessen format()-Methode.

Parameter

Name Typ Default Beschreibung
$locales string | string[] | Intl.Locale | undefined Standard-Locale der Laufzeitumgebung BCP-47-Sprachkennung wie "de-DE" oder "en-US" bzw. ein Array davon (Fallback-Reihenfolge).
$options Intl.DateTimeFormatOptions { hour: "numeric", minute: "numeric", second: "numeric" } Formatierungsoptionen, u. a. hour, minute, second ("numeric" | "2-digit"), hour12, hourCycle ("h11", "h12", "h23", "h24"), timeZone (z. B. "Europe/Berlin", "UTC"), timeZoneName, fractionalSecondDigits und timeStyle. Ohne Zeitkomponenten werden Stunde, Minute und Sekunde ergänzt.

Rückgabewert

Typ
string
Beschreibung
Die Uhrzeit als sprachabhängig formatierter String. Bei einem ungültigen Datum wird "Invalid Date" zurückgegeben.

Beispiele

Uhrzeit in verschiedenen Sprachen

const termin = new Date(Date.UTC(2024, 4, 17, 12, 5, 9));

// Ausgabe in fester Zeitzone, damit das Ergebnis reproduzierbar ist
const opts = { timeZone: 'Europe/Berlin' };
console.log(termin.toLocaleTimeString('de-DE', opts));
console.log(termin.toLocaleTimeString('en-US', opts));
console.log(termin.toLocaleTimeString('ja-JP', opts));
14:05:09 2:05:09 PM 14:05:09

Nur Stunden und Minuten für einen Chat-Zeitstempel

const formatiereChatZeit = (date) =>
  date.toLocaleTimeString('de-DE', {
    hour: '2-digit',
    minute: '2-digit',
    timeZone: 'Europe/Berlin'
  });

const nachricht = { text: 'Hallo!', gesendet: new Date('2024-05-17T07:03:00Z') };
console.log(`[${formatiereChatZeit(nachricht.gesendet)}] ${nachricht.text}`);
[09:03] Hallo!

Weltuhr mit Zeitzonenname

const jetzt = new Date(Date.UTC(2024, 0, 15, 18, 30));
const staedte = {
  Berlin: 'Europe/Berlin',
  'New York': 'America/New_York',
  Tokio: 'Asia/Tokyo'
};

for (const [stadt, timeZone] of Object.entries(staedte)) {
  const zeit = jetzt.toLocaleTimeString('de-DE', {
    timeZone,
    hour: '2-digit',
    minute: '2-digit',
    timeZoneName: 'short'
  });
  console.log(`${stadt}: ${zeit}`);
}
Berlin: 19:30 MEZ New York: 13:30 GMT-5 Tokio: 03:30 GMT+9

Performant viele Zeiten formatieren

// Für Listen: Formatter einmal erzeugen und wiederverwenden
const fmt = new Intl.DateTimeFormat('de-DE', {
  timeStyle: 'short',
  timeZone: 'UTC'
});

const logs = [
  new Date('2024-05-17T08:00:00Z'),
  new Date('2024-05-17T08:15:30Z')
];
console.log(logs.map((d) => fmt.format(d)));
[ '08:00', '08:15' ]

// Wichtig · Fallstricke

  • Ausgabe nicht parsen oder vergleichen: Das exakte Format hängt von Browser, ICU-Version und Betriebssystem ab. Manche Engines verwenden z. B. ein schmales geschütztes Leerzeichen (U+202F) vor „PM“, sodass String-Vergleiche in Tests plötzlich fehlschlagen.
  • Zeitzone: Ohne timeZone wird die Zeitzone des Systems verwendet. Auf Servern (Node.js, oft UTC) sieht die Ausgabe daher anders aus als im Browser – für reproduzierbare Ergebnisse timeZone immer explizit angeben.
  • timeStyle darf nicht mit einzelnen Komponenten wie hour oder minute kombiniert werden, sonst wird ein TypeError geworfen. Ungültige Locale-Angaben lösen einen RangeError aus, ebenso unbekannte Zeitzonen.
  • Datumsoptionen wie year oder month werden zwar akzeptiert, dateStyle jedoch führt bei toLocaleTimeString() zu einem TypeError.
  • Performance: Jeder Aufruf erzeugt intern einen neuen Formatter. Bei vielen Werten ist Intl.DateTimeFormat deutlich schneller.
  • Kompatibilität: In allen modernen Browsern und Node.js (ab 13 mit vollständigen ICU-Daten) unterstützt. fractionalSecondDigits und timeStyle sind neuer und fehlen in sehr alten Umgebungen.

Siehe auch

Date.prototype.toLocaleDateString() Date.prototype.toLocaleString() Date.prototype.toTimeString() Date.prototype.toISOString() Intl.DateTimeFormat Date
← Vorheriger Eintrag Date.prototype.toLocaleString()