Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

Źródła