Date.prototype.toLocaleTimeString()
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
(en-US):
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
(en-US) e usar a função fornecida pela propriedade dele: format
(en-US).
Especificações
Especificação | Status | Comentário |
---|---|---|
ECMAScript 3rd Edition (ECMA-262) | Padrão | Definição inicial, Implementado no JavaScript 1.0. |
ECMAScript 5.1 (ECMA-262) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão | |
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão | |
ECMAScript (ECMA-262) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão em tempo real | |
ECMAScript Internationalization API 1.0 (ECMA-402) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão | Define os argumentos locales e options . |
ECMAScript Internationalization API 2.0 (ECMA-402) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão | |
ECMAScript Internationalization API (ECMA-402) The definition of 'Date.prototype.toLocaleTimeString' in that specification. |
Padrão em tempo real |
Compatibilidade com navegadores
BCD tables only load in the browser