1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
---
title: Date.prototype.toLocaleTimeString()
slug: Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString
tags:
- Internacionalização
- Prototype
- data
- data formatada
- fuso horário
- metodo
- time zone
translation_of: Web/JavaScript/Reference/Global_Objects/Date/toLocaleTimeString
---
<div>{{JSRef}}</div>
<div>O método <strong><code>toLocaleTimeString()</code></strong> retorna uma string com uma representação sensível ao idioma de uma porção de tempo desta data. Os novos argumentos <code>locales</code> e <code>options</code> 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 <code>locales</code> e <code>options</code>, o local utilizado e o formato retornado da string são implementações completamente dependentes.</div>
<div> </div>
<div>{{EmbedInteractiveExample("pages/js/date-tolocaletimestring.html")}}</div>
<p class="hidden">A fonte deste exemplo interativo é armazenado em um repositório do GitHub. Se você deseja contribuir em exemplos interativos, por favor, clone <a href="https://github.com/mdn/interactive-examples">https://github.com/mdn/interactive-examples</a> e nos envie um pull request.</p>
<h2 id="Sintaxe">Sintaxe</h2>
<pre class="syntaxbox"><code><var>dateObj</var>.toLocaleTimeString([<var>locales</var>[, <var>options</var>]])</code></pre>
<h3 id="Parâmetros">Parâmetros</h3>
<p>Confira a seção <a href="#Browser_Compatibility">Browser compatibility</a> para ver o suporte em browsers dos argumentos <code>locales</code> e <code>options</code>, e <a href="#Checking_for_support_for_locales_and_options_arguments">Checking for support for <code>locales</code> and <code>options</code> arguments</a> para ver suas features.</p>
<div>{{page('/pt-BR/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat', 'Parameters')}}</div>
<p>O valor default para cada propriedade do componente date-time é {{jsxref("undefined")}}, mas se as propriedades <code>hour</code>, <code>minute</code>, <code>second</code> são todas {{jsxref("undefined")}}, então <code>hour</code>, <code>minute</code>, e <code>second</code> espera-se que seja <code>"numeric"</code>.</p>
<h3 id="Valor_retornado">Valor retornado</h3>
<p>Uma string representando uma porção de tempo de uma instância {{jsxref("Global_Objects/Date", "Date")}}, fornecida de acordo com as convenções específicas do idioma.</p>
<h2 id="Exemplos">Exemplos</h2>
<h3 id="Usando_toLocaleTimeString()">Usando <code>toLocaleTimeString()</code></h3>
<p>Em um uso simples, sem especificar uma localidade, é retornado uma string formatada de uma localidade default e com opções default.</p>
<pre class="brush: js">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
</pre>
<h3 id="Verificando_o_suporte_para_os_argumentos_locales_e_options">Verificando o suporte para os argumentos <code>locales</code> e <code>options</code></h3>
<p>Os argumentos <code>locales</code> e <code>options</code> 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 {{jsxref("RangeError")}}:</p>
<pre class="brush: js">function toLocaleTimeStringSupportsLocales() {
try {
new Date().toLocaleTimeString('i');
} catch (e) {
return e.name === 'RangeError';
}
return false;
}
</pre>
<h3 id="Usando_locales">Usando <code>locales</code></h3>
<p>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 <code>locales</code>:</p>
<pre class="brush: js">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'));
// → "<span dir="rtl">٧:٠٠:٠٠ م</span>"
// 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"
</pre>
<h3 id="Usando_options">Usando <code>options</code></h3>
<p>Os resultados fornecidos por <code>toLocaleTimeString()</code> podem ser customizados usando o argumento <code>options</code>:</p>
<pre class="brush: js">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"
</pre>
<h2 id="Performance">Performance</h2>
<p>Quando se formata um grande número de datas, é aconselhável criar um objeto {{jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")}} e usar a função fornecida pela propriedade dele: {{jsxref("DateTimeFormat.prototype.format", "format")}}.</p>
<h2 id="Especificações">Especificações</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Especificação</th>
<th scope="col">Status</th>
<th scope="col">Comentário</th>
</tr>
<tr>
<td>{{SpecName('ES3')}}</td>
<td>{{Spec2('ES3')}}</td>
<td>Definição inicial, Implementado no JavaScript 1.0.</td>
</tr>
<tr>
<td>{{SpecName('ES5.1', '#sec-15.9.5.7', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ES5.1')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ES6', '#sec-date.prototype.tolocalestring', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ES6')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ESDraft', '#sec-date.prototype.tolocalestring', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ESDraft')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ES Int 1.0', '#sec-13.3.3', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ES Int 1.0')}}</td>
<td>Define os argumentos <code>locales</code> e <code>options</code>.</td>
</tr>
<tr>
<td>{{SpecName('ES Int 2.0', '#sec-13.3.3', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ES Int 2.0')}}</td>
<td> </td>
</tr>
<tr>
<td>{{SpecName('ES Int Draft', '#sec-Date.prototype.toLocaleTimeString', 'Date.prototype.toLocaleTimeString')}}</td>
<td>{{Spec2('ES Int Draft')}}</td>
<td> </td>
</tr>
</tbody>
</table>
<h2 id="Compatibilidade_em_Browsers">Compatibilidade em Browsers</h2>
<p class="hidden">A tabela de compatibilidade nessa página é gerada por dados estruturados. Se você deseja contribuir com esses dados, por favor confira <a href="https://github.com/mdn/browser-compat-data">https://github.com/mdn/browser-compat-data</a> e nos envie um pull request.</p>
<p>{{Compat("javascript.builtins.Date.toLocaleTimeString")}}</p>
<h2 id="Veja_também">Veja também</h2>
<ul>
<li>{{jsxref("Global_Objects/DateTimeFormat", "Intl.DateTimeFormat")}}</li>
<li>{{jsxref("Date.prototype.toLocaleDateString()")}}</li>
<li>{{jsxref("Date.prototype.toLocaleString()")}}</li>
<li>{{jsxref("Date.prototype.toTimeString()")}}</li>
<li>{{jsxref("Date.prototype.toString()")}}</li>
</ul>
|
