CKTIS / JavaScript
Intl.DateTimeFormat — formatação localizada de datas e horas
Intl.DateTimeFormat formata datas e horas segundo as convenções locais e um fuso horário selecionado. Saiba mais sobre format(), formatToParts(), resolvedOptions() e a diferença entre timeZone e hourCycle.
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
const formatter = new Intl.DateTimeFormat(locales, options);
formatter.format(date);
formatter.formatToParts(date);
formatter.resolvedOptions();Intl.DateTimeFormat pertence à norma de internacionalização ECMA-402, não à API DOM. Crie um formatador com new Intl.DateTimeFormat(locales, options) e reutilize-o. Uma localidade determina as convenções de apresentação; não seleciona automaticamente o fuso horário correspondente a esse país.
Os nomes Intl.DateTimeFormat.format e Intl.DateTimeFormat.formatToParts referem-se aqui a operações de instância, não a métodos estáticos do construtor. formatter.format(date) devolve texto; a propriedade format é um accessor que disponibiliza uma função associada. formatter.formatToParts(date) devolve objetos { type, value } ordenados, incluindo partes literal. A junção de todos os valores value reconstrói format(date). Não analise texto localizado dividindo-o pelos separadores.
timeZone, por exemplo UTC ou Europe/Warsaw, seleciona o fuso usado para apresentar o mesmo instante, sem alterar o objeto Date. Se a opção for omitida, é usado o fuso horário do ambiente. hourCycle seleciona o intervalo das horas: h11 corresponde a 0–11, h12 a 1–12, h23 a 0–23 e h24 a 1–24. É relevante ao formatar horas; se for indicada, a opção hour12 tem prioridade.
Intl.DateTimeFormat.prototype.resolvedOptions, chamado como formatter.resolvedOptions(), expõe as definições efetivamente selecionadas, incluindo locale, timeZone e, quando o formato inclui horas, hourCycle. Os dados de localidade podem variar entre ambientes, por isso não presuma pontuação ou espaçamento idênticos. A norma não é uma tabela de compatibilidade de browsers: verifique os métodos e as opções necessários nos ambientes de destino; o Node 24 não comprova o suporte nos browsers.
Exemplos
const formatter = new Intl.DateTimeFormat('en-GB', {
timeZone: 'UTC',
numberingSystem: 'latn',
hour: '2-digit',
minute: '2-digit',
hourCycle: 'h23'
});
const date = new Date('2024-01-02T00:05:00Z');
const parts = formatter.formatToParts(date);
const field = type => parts.find(part => part.type === type).value;
console.log(`${field('hour')}:${field('minute')}`);
console.log(parts.map(part => part.value).join('') === formatter.format(date));
console.log(formatter.resolvedOptions().hourCycle);Resultado
00:05 true h23
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
- ECMAScript® 2027 Internationalization API Specification
- ECMAScript® 2024 Internationalization API Specification
- ECMAScript® 2026 Internationalization API Specification
- Official reference — tc39.es: ecma402
- Official reference — tc39.es: ecma402
- Official reference — developer.mozilla.org: Intl / DateTimeFormat