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.