CKTIS / JavaScript
Date.prototype.toLocaleTimeString() — lokalizowane formatowanie czasu
toLocaleTimeString() zwraca tekstową reprezentację czasu obiektu Date zgodną z wybranym locale i opcjami. Pozwala określić strefę czasową, składniki czasu oraz cykl godzinowy bez zmieniania daty.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
date.toLocaleTimeString(locales?, options?)Symbol katalogowy Date.toLocaleTimeString oznacza metodę instancji Date.prototype.toLocaleTimeString, a nie metodę statyczną konstruktora Date. Wywołanie date.toLocaleTimeString(locales, options) zwraca ciąg znaków i nie zmienia obiektu date. Opis parametrów dotyczy środowisk obsługujących ECMA-402 (Intl).
locales przyjmuje identyfikator językowy, np. pl-PL, lub listę preferowanych identyfikatorów; pominięcie go wybiera domyślne locale środowiska. options.timeZone wybiera strefę prezentacji, a bez tej opcji używana jest strefa środowiska. Opcje hour, minute i second wybierają składniki czasu. Bez opcji hour12 ustawienie hourCycle: 'h23' oznacza godziny od 0 do 23. Opcja hour12 ma pierwszeństwo przed hourCycle: jeśli podasz jednocześnie hour12: true i hourCycle: 'h23', zostanie użyty cykl 12-godzinny. Bez stylu i bez określonych składników czasu domyślnie uwzględniane są godzina, minuta i sekunda.
Można użyć timeStyle, np. 'short', zamiast jawnych opcji składników. Przy formatowaniu prawidłowej daty połączenie timeStyle z opcją składnika, taką jak hour, powoduje TypeError. Podanie dateStyle w wywołaniu toLocaleTimeString() dla prawidłowej daty również powoduje TypeError, nawet jeśli jest to jedyna opcja. W przypadku nieprawidłowego obiektu Date metoda zwraca "Invalid Date" przed przetworzeniem opcji, więc połączenie timeStyle z hour nie powoduje wtedy błędu. Odbiorca niebędący obiektem Date powoduje TypeError.
Wynik służy do prezentacji użytkownikowi, nie jako stabilny format zapisu lub wejście do parsowania: dane locale mogą zmieniać interpunkcję i odstępy. Przykład ustala chwilę, locale, strefę UTC, cykl godzinowy i system cyfr, ograniczając zmienność. Przy wielokrotnym formatowaniu warto utworzyć jeden Intl.DateTimeFormat i używać jego metody format.
Przykłady
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);Wynik
13:05:09
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.