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

CKTIS / JavaScript

Fusos horários e ciclos de horas em Intl.DateTimeFormat

`timeZone` escolhe a hora local a apresentar para um instante. `hourCycle` determina como se numeram as horas, por exemplo, se a meia-noite aparece como `00` ou `24`.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

new Intl.DateTimeFormat(locales, { timeZone, hourCycle, hour: "2-digit" })

timeZone escolhe o fuso usado para apresentar um instante, sem alterar o objeto Date nem o valor que contém. Sem esta opção, usa-se o fuso predefinido do ambiente de execução. Um fuso com nome, como "America/New_York", segue as regras em vigor no instante em causa, incluindo as mudanças da hora de verão. Um desvio fixo, como "-05:00", não segue essas regras. Os ambientes mais antigos podem não aceitar identificadores de desvio. timeZoneName controla a designação apresentada, não a escolha do fuso.

hourCycle define o intervalo das horas: "h11" vai de 0 a 11, "h12" de 1 a 12, "h23" de 0 a 23 e "h24" de 1 a 24. Em "h24", 24 designa a hora que começa à meia-noite; não desloca o instante para o dia seguinte. hourCycle não inclui a hora no resultado por si só: pede-a com hour ou timeStyle, mas não combines as duas opções.

hour12: true e hour12: false têm precedência sobre hourCycle e sobre a extensão Unicode hc da configuração regional. true escolhe um ciclo de 12 horas e false um ciclo de 24 horas. Para escolher um ciclo específico, omite hour12 e define hourCycle, que prevalece sobre hc. Sem estas definições, o ciclo predefinido depende da configuração regional.

Um hourCycle inválido ou um identificador timeZone não reconhecido lança um RangeError ao criar o formatador, mesmo que um hour12 válido fosse prevalecer sobre hourCycle. Consulta as definições efetivas com resolvedOptions(); o ciclo não é devolvido se o formato não incluir a hora. Para obter apenas a hora, usa a parte hour de formatToParts() em vez de analisar toda a cadeia de texto localizada.

Exemplos

const instant = new Date("2024-01-15T05:00:00Z");

function showHour(timeZone, hourCycle) {
  const formatter = new Intl.DateTimeFormat("en-US", {
    timeZone,
    hourCycle,
    hour: "2-digit",
    numberingSystem: "latn",
    formatMatcher: "basic",
  });
  const hour = formatter.formatToParts(instant).find(part => part.type === "hour");
  const displayHour = hour.value.padStart(2, "0");
  console.log(`${timeZone} ${formatter.resolvedOptions().hourCycle}: ${displayHour}`);
}

showHour("UTC", "h23");
showHour("America/New_York", "h23");
showHour("America/New_York", "h24");

Resultado

UTC h23: 05
America/New_York h23: 00
America/New_York h24: 24

Nas primeiras duas linhas muda apenas o fuso: o mesmo instante corresponde à hora `05` em UTC e à meia-noite em Nova Iorque. Na última linha muda apenas o ciclo, pelo que a mesma hora local é apresentada como `24` em vez de `00`.

Lições relacionadas

  • JavaScript · Lição 25 · Avançado · Versão: 4

Fontes