Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Date.prototype.toLocaleTimeString() — formatação localizada da hora

toLocaleTimeString() devolve uma representação textual da hora de um objeto Date, de acordo com a localização e as opções selecionadas. Permite escolher o fuso horário, os componentes da hora e o ciclo horário sem alterar a data.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

date.toLocaleTimeString(locales?, options?)

O símbolo de catálogo Date.toLocaleTimeString refere-se ao método de instância Date.prototype.toLocaleTimeString, e não a um método estático do construtor Date. A chamada date.toLocaleTimeString(locales, options) devolve uma cadeia de caracteres sem alterar date. O comportamento dos parâmetros aqui descrito aplica-se a ambientes compatíveis com ECMA-402 (Intl).

locales aceita uma etiqueta de idioma, como pl-PL, ou uma lista de etiquetas preferidas. Se for omitido, é utilizada a localização predefinida do ambiente. options.timeZone seleciona o fuso horário de apresentação; caso contrário, é utilizado o fuso do ambiente. As opções hour, minute e second selecionam os componentes da hora. Se hour12 não for definido, hourCycle: 'h23' define horas de 0 a 23. A opção hour12 tem precedência sobre hourCycle: se indicar hour12: true e hourCycle: 'h23' em simultâneo, é utilizado um ciclo de 12 horas. Se não for indicado um estilo nem componentes da hora, são incluídos por predefinição a hora, os minutos e os segundos.

Pode utilizar timeStyle, por exemplo 'short', em vez de opções explícitas para os componentes. Ao formatar uma data válida, combinar timeStyle com uma opção de componente como hour provoca um TypeError. Para uma data válida, indicar dateStyle numa chamada a toLocaleTimeString() também provoca um TypeError, mesmo que seja a única opção. Se o objeto Date for inválido, o método devolve "Invalid Date" antes de processar as opções, pelo que a combinação de timeStyle com hour não provoca um erro nesse caso. Um recetor que não seja um objeto Date provoca um TypeError.

O resultado destina-se à apresentação ao utilizador, não a armazenamento estável nem a análise: os dados de localização podem alterar a pontuação e os espaços. O exemplo fixa o instante, a localização, o fuso UTC, o ciclo horário e o sistema de numeração para reduzir variações. Para formatações repetidas, considere criar um único Intl.DateTimeFormat e reutilizar o respetivo método format.

Exemplos

const date = new Date('2024-01-15T13:05:09.000Z');
const text = date.toLocaleTimeString('en-GB', {
  timeZone: 'UTC',
  hourCycle: 'h23',
  numberingSystem: 'latn',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit'
});
console.log(text);

Resultado

13:05:09

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes