WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Date.prototype.toLocaleTimeString() — lokalisierte Zeitformatierung

toLocaleTimeString() gibt eine Textdarstellung der Uhrzeit eines Date-Objekts zurück, formatiert nach der ausgewählten Locale und den angegebenen Optionen. Damit lassen sich Zeitzone, Zeitbestandteile und Stundenzyklus festlegen, ohne das Datum zu ändern.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

date.toLocaleTimeString(locales?, options?)

Das Katalogsymbol Date.toLocaleTimeString bezeichnet die Instanzmethode Date.prototype.toLocaleTimeString, nicht eine statische Methode des Date-Konstruktors. Der Aufruf date.toLocaleTimeString(locales, options) gibt eine Zeichenfolge zurück, ohne date zu ändern. Die hier beschriebenen Parameter gelten für Umgebungen, die ECMA-402 (Intl) unterstützen.

locales akzeptiert ein Sprach-Tag wie pl-PL oder eine Liste bevorzugter Tags. Wird es weggelassen, wird die Standard-Locale der Umgebung verwendet. options.timeZone legt die Anzeigezeitzone fest; andernfalls gilt die Zeitzone der Umgebung. Mit den Optionen hour, minute und second werden Zeitbestandteile ausgewählt. Ist hour12 nicht festgelegt, legt hourCycle: 'h23' Stunden von 0 bis 23 fest. Die Option hour12 hat Vorrang vor hourCycle: Wenn Sie sowohl hour12: true als auch hourCycle: 'h23' angeben, wird ein 12-Stunden-Zyklus verwendet. Wenn weder ein Stil noch Zeitbestandteile angegeben werden, sind standardmäßig Stunde, Minute und Sekunde enthalten.

Anstelle expliziter Optionen für Zeitbestandteile können Sie timeStyle verwenden, zum Beispiel 'short'. Beim Formatieren eines gültigen Datums löst die Kombination von timeStyle mit einer Option für einen Zeitbestandteil wie hour einen TypeError aus. Wird dateStyle beim Aufruf von toLocaleTimeString() für ein gültiges Datum angegeben, löst das ebenfalls einen TypeError aus, selbst wenn es die einzige Option ist. Bei einem ungültigen Date gibt die Methode "Invalid Date" zurück, bevor sie die Optionen verarbeitet. Die Kombination von timeStyle und hour löst in diesem Fall also keinen Fehler aus. Ein Empfänger, der kein Date-Objekt ist, verursacht einen TypeError.

Das Ergebnis ist für die Anzeige für Nutzerinnen und Nutzer gedacht, nicht für eine stabile Speicherung oder zum Parsen: Locale-Daten können Zeichensetzung und Abstände verändern. Das Beispiel legt Zeitpunkt, Locale, UTC-Zeitzone, Stundenzyklus und Nummerierungssystem fest, um Abweichungen zu verringern. Für wiederholte Formatierungen empfiehlt es sich, ein Intl.DateTimeFormat-Objekt zu erstellen und dessen Methode format wiederzuverwenden.

Beispiele

const date = new Date('2024-01-15T13:05:09.000Z');
const text = date.toLocaleTimeString('en-GB', {
  timeZone: 'UTC',
  hourCycle: 'h23',
  numberingSystem: 'latn',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit'
});
console.log(text);

Ergebnis

13:05:09

Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.

Quellen