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

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