Date.prototype.toLocaleTimeString()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since julho de 2015.
O método toLocaleTimeString() retorna uma string com uma representação sensível ao idioma de uma porção de tempo desta data. Os novos argumentos locales e options possibilitam aplicações especificarem que formato de linguagem deve ser usado, podendo customizar o comportamento da função. Em implementações antigas, que ignoram os argumentos locales e options, o local utilizado e o formato retornado da string são implementações completamente dependentes.
Experimente
// Depending on timezone, your results will vary
const event = new Date("August 19, 1975 23:15:30 GMT+00:00");
console.log(event.toLocaleTimeString("en-US"));
// Expected output: "1:15:30 AM"
console.log(event.toLocaleTimeString("it-IT"));
// Expected output: "01:15:30"
console.log(event.toLocaleTimeString("ar-EG"));
// Expected output: "١٢:١٥:٣٠ ص"
Sintaxe
dateObj.toLocaleTimeString([locales[, options]])
Parâmetros
Confira a seção Browser compatibility para ver o suporte em browsers dos argumentos locales e options, e Checking for support for locales and options arguments para ver suas features.
O valor default para cada propriedade do componente date-time é undefined, mas se as propriedades hour, minute, second são todas undefined, então hour, minute, e second espera-se que seja "numeric".
Valor retornado
Uma string representando uma porção de tempo de uma instância Date, fornecida de acordo com as convenções específicas do idioma.
Exemplos
Usando toLocaleTimeString()
Em um uso simples, sem especificar uma localidade, é retornado uma string formatada de uma localidade default e com opções default.
var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
// toLocaleTimeString() sem argumentos, depende da implementação,
// da localidade padrão, e do fuso horário padrão
console.log(date.toLocaleTimeString());
// → "7:00:00 PM" se rodar em en-US com o fuso horário de America/Los_Angeles
Verificando o suporte para os argumentos locales e options
Os argumentos locales e options não são suportados em todos os browsers ainda. Para conferir se uma implementação já os suporta, você pode usar a exigência que tags ilegais de liguagem são rejeitadas com uma exceção RangeError:
function toLocaleTimeStringSupportsLocales() {
try {
new Date().toLocaleTimeString("i");
} catch (e) {
return e.name === "RangeError";
}
return false;
}
Usando locales
Este exemplo mostra algumas das variações em um formato de tempo localizado. Para obter o formato do idioma usado na interface do usuário da sua aplicação, tenha certeza de especificar esse idioma (e possivelmente alguns idiomas de retorno) usando o argumento locales:
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// Os formatos abaixo assumem o fuso horário local da região;
// America/Los_Angeles for the US
// US English usa o formato 12 horas com AM/PM
console.log(date.toLocaleTimeString("en-US"));
// → "7:00:00 PM"
// British English usa o formato 24 horas sem AM/PM
console.log(date.toLocaleTimeString("en-GB"));
// → "03:00:00"
// Korean usa o formato 12 horas com AM/PM
console.log(date.toLocaleTimeString("ko-KR"));
// → "오후 12:00:00"
// Arabic na maiorias dos países que falam árabe usa-se os dígitos arábicos reais
console.log(date.toLocaleTimeString("ar-EG"));
// → "٧:٠٠:٠٠ م"
// quando solicitar um idioma que talvez não seja suportado, como o
// Balinese, inclua um idioma de fallback, nesse caso Indonesian
console.log(date.toLocaleTimeString(["ban", "id"]));
// → "11.00.00"
Usando options
Os resultados fornecidos por toLocaleTimeString() podem ser customizados usando o argumento options:
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// uma aplicação pode querer usar UTC e tornar isso visível
var options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// → "3:00:00 AM GMT"
// ás vezes, até em US precise usar o formato 24 horas
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// → "19:00:00"
Performance
Quando se formata um grande número de datas, é aconselhável criar um objeto Intl.DateTimeFormat e usar a função fornecida pela propriedade dele: format.
Especificações
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-date.prototype.tolocaletimestring |
| ECMAScript® 2026 Internationalization API Specification # sup-date.prototype.tolocaletimestring |