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
- ECMAScript® 2024 Internationalization API Specification — CreateDateTimeFormat
- ECMAScript Internationalization API Specification — CreateDateTimeFormat (living specification)
- Intl.DateTimeFormat() constructor — MDN
- Intl.DateTimeFormat.prototype.resolvedOptions() — MDN
- Intl.DateTimeFormat.prototype.formatToParts() — MDN