Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / JavaScript

Date.prototype.toLocaleTimeString() — lokalizované formátování času

toLocaleTimeString() vrací textovou reprezentaci času objektu Date podle zvoleného locale a možností. Umožňuje vybrat časové pásmo, složky času a hodinový cyklus, aniž by se změnilo datum.

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

Syntaxe

date.toLocaleTimeString(locales?, options?)

Katalogový symbol Date.toLocaleTimeString označuje instanční metodu Date.prototype.toLocaleTimeString, nikoli statickou metodu konstruktoru Date. Volání date.toLocaleTimeString(locales, options) vrací řetězec a nemění date. Zde popsané chování parametrů platí pro prostředí podporující ECMA-402 (Intl).

locales přijímá jazykovou značku, například pl-PL, nebo seznam upřednostňovaných značek. Pokud tento argument vynecháte, použije se výchozí locale prostředí. options.timeZone vybírá časové pásmo pro zobrazení; jinak se použije pásmo prostředí. Možnosti hour, minute a second vybírají složky času. Pokud není nastavena možnost hour12, hourCycle: 'h23' nastavuje hodiny od 0 do 23. Možnost hour12 má přednost před hourCycle: pokud zadáte současně hour12: true a hourCycle: 'h23', použije se 12hodinový cyklus. Pokud není zadán styl ani složky času, ve výchozím nastavení se zahrnou hodiny, minuty a sekundy.

Místo výslovných možností pro složky lze použít timeStyle, například 'short'. Při formátování platného data vyvolá kombinace timeStyle s možností pro složku času, například hour, chybu TypeError. Pokud při volání toLocaleTimeString() pro platné datum zadáte dateStyle, vyvolá se také TypeError, i když je to jediná možnost. U neplatného objektu Date metoda vrátí "Invalid Date" ještě před zpracováním možností, takže kombinace timeStyle a hour v tomto případě chybu nevyvolá. Příjemce, který není objektem Date, způsobí TypeError.

Výsledek je určen k zobrazení uživateli, nikoli ke stabilnímu ukládání nebo parsování: lokalizační data mohou měnit interpunkci a mezery. Příklad pevně stanovuje okamžik, locale, pásmo UTC, hodinový cyklus a číselnou soustavu, aby omezil odchylky. Při opakovaném formátování zvažte vytvoření jednoho objektu Intl.DateTimeFormat a opakované použití jeho metody format.

Příklady

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);

Výsledek

13:05:09

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje