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

CKTIS / JavaScript

Intl.DateTimeFormat: obter as partes de uma data com formatToParts()

Obtém as partes de uma data ou hora formatada segundo as definições regionais para realçar um campo como o mês, sem dividir o texto por separadores nem presumir a ordem dos campos.

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

Sintaxe

formatter.formatToParts()
formatter.formatToParts(date)

formatToParts() é um método de instância de Intl.DateTimeFormat, definido em Intl.DateTimeFormat.prototype, e não um método estático do construtor. Chama-o com formatter.formatToParts(date). Ao contrário de format(), não fica automaticamente associado à instância: chamar a função extraída sem o this correto lança um TypeError.

Passa um objeto Date ou um timestamp em milissegundos desde a época Unix, não em segundos. Se omitires o argumento ou passares undefined, é usado o instante atual devolvido por Date.now(). Um Date inválido ou um timestamp fora do intervalo válido provoca um RangeError. O método formata valores; não interpreta texto que represente uma data. Os ambientes com integração de Temporal podem também aceitar alguns tipos Temporal.Plain*; passar diretamente um Temporal.ZonedDateTime lança um TypeError.

O resultado é um array de objetos { type, value } pela ordem de apresentação; ambas as propriedades são cadeias de caracteres. Um type como month, day ou year identifica um campo. literal indica texto do padrão, como uma vírgula, um espaço ou uma palavra. Nos calendários em que os anos têm nome, relatedYear (o ano gregoriano correspondente) pode substituir year, e o padrão também pode incluir yearName (o nome do ano).

Seleciona as partes por type, não pelo índice no array. Para reproduzir o resultado de format() com a mesma instância e a mesma data, junta todos os value sem separador, incluindo os de tipo literal. As definições regionais e opções como o calendário e o fuso horário influenciam o resultado. A grafia e a pontuação podem variar entre ambientes, mesmo com as mesmas definições regionais. Não uses o resultado como formato de intercâmbio de dados.

Exemplos

const formatter = new Intl.DateTimeFormat("en-US", {
  timeZone: "UTC",
  year: "numeric",
  month: "long",
  day: "numeric",
});
const date = new Date("2024-07-09T12:00:00Z");
const parts = formatter.formatToParts(date);

console.log(parts.some(({ type }) => type === "month"));
console.log(parts.map(({ value }) => value).join("") === formatter.format(date));

Resultado

true
true

O exemplo fixa a data, as definições regionais e o fuso horário UTC. O primeiro `true` confirma que existe uma parte `month`; o segundo confirma que os valores concatenados coincidem com `format()`.

Lições relacionadas

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

Fontes