Date.prototype.toLocaleTimeString()
===================================

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.

{{page('/pt-BR/docs/Web/JavaScript/Reference/Global\_Objects/DateTimeFormat', 'Parameters')}}
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.


```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
```

### 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):


```js
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`:


```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"));
// → "٧:٠٠:٠٠ م"

// 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`:


```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"
```

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
--------------

| 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 with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

* `Intl.DateTimeFormat` (en-US)
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleString()` (en-US)
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`