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

CKTIS / JavaScript

Intl.DateTimeFormat.prototype.format — formatar datas e horas segundo a região

Usa `formatter.format()` para apresentar uma data e hora de acordo com as definições regionais e o fuso horário. O resultado é texto para apresentação, não para guardar dados.

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

Sintaxe

const formatter = new Intl.DateTimeFormat(locales, options);
formatter.format(date);
formatter.format();
const format = formatter.format;
format(date);

Chama formatter.format(...) numa instância de Intl.DateTimeFormat, não no construtor. Cria um formatador com new Intl.DateTimeFormat(locales, options) para escolher as definições regionais, o fuso horário e os campos a apresentar. A chamada devolve uma cadeia de caracteres e não altera o objeto Date. Se omitires locales ou timeZone, o formatador usa o valor predefinido correspondente do ambiente de execução.

Em ECMA-402 (2024), passa um objeto Date ou um valor temporal numérico em milissegundos desde a época Unix, não em segundos. Se omitires o argumento ou passares undefined, é formatado o instante atual no momento da chamada. format() não interpreta texto de datas: converte primeiro o texto num Date válido ou num valor temporal numérico. Um Date inválido, NaN, um valor infinito ou um valor temporal fora do intervalo de Date lança um RangeError.

Intl.DateTimeFormat.prototype.format é uma propriedade com um getter. Ler formatter.format devolve a mesma função ligada à instância, pelo que a podes passar diretamente como função de retorno de chamada, por exemplo em dates.map(formatter.format), sem chamar bind().

Os ambientes que integram Temporal também podem formatar Temporal.PlainDateTime, Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainYearMonth ou Temporal.PlainMonthDay se o tipo for compatível com as definições do formatador. Temporal.ZonedDateTime lança um TypeError; usa Temporal.ZonedDateTime.prototype.toLocaleString() para formatar o valor no seu próprio fuso horário.

Mesmo com as mesmas definições, o resultado pode variar entre ambientes de execução, nomeadamente nos espaços, na pontuação ou nos caracteres de controlo bidirecional. Não o compares com texto fixo no código nem o uses como formato de intercâmbio de dados.

Exemplos

const formatter = new Intl.DateTimeFormat("en-GB", {
  year: "numeric",
  month: "long",
  day: "numeric",
  timeZone: "UTC",
});
const date = new Date("2024-06-15T00:00:00Z");
const format = formatter.format;
const text = formatter.format(date);

console.log(typeof text);
console.log(text === format(date.getTime()));

Resultado

string
true

O exemplo fixa o instante, as definições regionais e o fuso horário UTC. Verifica o tipo do resultado e se a função chamada em separado formata o valor temporal numérico da mesma forma que a chamada sobre a instância com o `Date` equivalente, sem pressupor o texto exato.

Lições relacionadas

  • JavaScript · Lição 15 · Básico · Versão: 4

Fontes