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.A fonte deste exemplo interativo é armazenado em um repositório do GitHub. Se você deseja contribuir em exemplos interativos, por favor, clone https://github.com/mdn/interactive-examples e nos envie um pull request.
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
Compatibilidade em Browsers
A tabela de compatibilidade nessa página é gerada por dados estruturados. Se você deseja contribuir com esses dados, por favor confira https://github.com/mdn/browser-compat-data e nos envie um pull request.
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Basic support | Chrome Full support Yes | Edge Full support Yes | Firefox Full support 1 | IE Full support Yes | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Edge Mobile Full support Yes | Firefox Android Full support 4 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes | nodejs ? |
locales | Chrome Full support 24 | Edge ? | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Edge Mobile ? | Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
options | Chrome Full support 24 | Edge ? | Firefox Full support 29 | IE Full support 11 | Opera Full support 15 | Safari Full support 10 | WebView Android No support No | Chrome Android Full support 26 | Edge Mobile ? | Firefox Android Full support 56 | Opera Android No support No | Safari iOS Full support 10 | Samsung Internet Android Full support Yes | nodejs ? |
IANA time zone names in timeZone option | Chrome Full support 24 | Edge ? | Firefox Full support 52 | IE ? | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android No support No | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs ? |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown