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 September 2017.
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
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 Language Specification # sec-date.prototype.tolocaletimestring |
ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |
Compatibilidade com navegadores
BCD tables only load in the browser