MDN wants to learn about developers like you: https://qsurvey.mozilla.com/s3/MDN-survey

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.
 

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.

locales

Optional. A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see the Intl page. The following Unicode extension keys are allowed:

nu
Numbering system. Possible values include: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
ca
Calendar. Possible values include: "buddhist", "chinese", "coptic", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc".
hc
Hour cycle. Possible values include: "h11", "h12", "h23", "h24".
options

Optional. An object with some or all of the following properties:

localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.
timeZone
The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".
hour12
Whether to use 12-hour time (as opposed to 24-hour time). Possible values are true and false; the default is locale dependent. This option overrides the hc language tag and/or the hourCycle option in case both are present.
hourCycle
The hour cycle to use. Possible values are "h11", "h12", "h23", or "h24". This option overrides the hc language tag, if both are present, and the hour12 option takes precedence in case both options have been specified.
formatMatcher
The format matching algorithm to use. Possible values are "basic" and "best fit"; the default is "best fit". See the following paragraphs for information about the use of this property.

The following properties describe the date-time components to use in formatted output, and their desired representations. Implementations are required to support at least the following subsets:

  • weekday, year, month, day, hour, minute, second
  • weekday, year, month, day
  • year, month, day
  • year, month
  • month, day
  • hour, minute, second
  • hour, minute

Implementations may support other subsets, and requests will be negotiated against all available subset-representation combinations to find the best match. Two algorithms are available for this negotiation and selected by the formatMatcher property: A fully specified "basic" algorithm and an implementation dependent "best fit" algorithm.

weekday
The representation of the weekday. Possible values are "narrow", "short", "long".
era
The representation of the era. Possible values are "narrow", "short", "long".
year
The representation of the year. Possible values are "numeric", "2-digit".
month
The representation of the month. Possible values are "numeric", "2-digit", "narrow", "short", "long".
day
The representation of the day. Possible values are "numeric", "2-digit".
hour
The representation of the hour. Possible values are "numeric", "2-digit".
minute
The representation of the minute. Possible values are "numeric", "2-digit".
second
The representation of the second. Possible values are "numeric", "2-digit".
timeZoneName
The representation of the time zone name. Possible values are "short", "long".

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

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 Latest Draft (ECMA-262)
The definition of 'Date.prototype.toLocaleTimeString' in that specification.
Rascunho  
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 4.0 (ECMA-402)
The definition of 'Date.prototype.toLocaleTimeString' in that specification.
Rascunho  

Compatibilidade em Browsers

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic support Yes Yes Yes Yes Yes Yes
locales24 ?29111510
options24 ?29111510
IANA time zone names in timeZone option24 ?52 ? ? ?
FeatureAndroid webviewChrome for AndroidEdge mobileFirefox for AndroidOpera AndroidiOS SafariSamsung Internet
Basic support Yes Yes Yes Yes Yes Yes ?
locales No26 ? No No10 ?
options No26 ? No No10 ?
IANA time zone names in timeZone option ? ? ? No ? ? ?

Veja também

Etiquetas do documento e colaboradores

 Colaboradores desta página: jbwestphal
 Última atualização por: jbwestphal,