CKTIS / JavaScript
Intl.DateTimeFormat.formatToParts(): partes da data e da hora
Obtém as partes de uma data ou hora localizada para aplicar um estilo a um componente sem presumir a ordem dos campos nem dividir o texto pela pontuação.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
formatter.formatToParts()
formatter.formatToParts(date)Intl.DateTimeFormat.prototype.formatToParts é um método de instância de Intl.DateTimeFormat. Em vez da única cadeia de caracteres devolvida por format(), fornece um array de objetos { type, value } pela ordem de apresentação. Ambas as propriedades são cadeias de caracteres. Ao juntares todos os value com join(""), obténs o resultado de format() para o mesmo formatador e a mesma entrada. Ao contrário da função devolvida por format, formatToParts não fica automaticamente associado à instância. Passa date => formatter.formatToParts(date) como função de callback ou usa bind; um this incompatível lança TypeError.
Seleciona as partes por type, como month ou dayPeriod, e não pelo índice. Mantém as partes literal: podem conter espaços, pontuação ou palavras. Em alguns calendários, relatedYear (o ano gregoriano correspondente) substitui year, por vezes acompanhado de yearName (o nome do ano). Mantém também as partes desconhecidas. As definições regionais, as opções e os dados do ambiente de execução podem afetar o resultado. Usa as partes para apresentação, não para análise nem armazenamento. Num navegador, insere os valores como texto com textContent, não com innerHTML.
Em ECMA-402 para ECMAScript 2024, passa um objeto Date ou um número de milissegundos desde a época Unix. O método converte o argumento num número; não interpreta cadeias de caracteres como datas. Se omitires o argumento ou passares undefined, é usada a hora atual no momento da chamada. Um Date inválido ou um valor temporal fora do intervalo válido lança RangeError.
Os ambientes com integração de Temporal também aceitam Temporal.Instant e os tipos Temporal.Plain* especificados para este método, com restrições de calendário e formatação que dependem do tipo. Verifica o suporte no ambiente de destino. Passar diretamente um Temporal.ZonedDateTime lança TypeError. Para obteres as partes do mesmo instante no seu fuso horário, passa o resultado de toInstant() e define timeZone do formatador com o fuso desse objeto.
Exemplos
{
const formatter = new Intl.DateTimeFormat("en-US", {
timeZone: "UTC",
calendar: "gregory",
year: "numeric",
month: "long",
day: "numeric",
});
const date = new Date("2024-07-05T12: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 o instante, as definições regionais e o fuso horário UTC. O primeiro `true` confirma a presença de uma parte `month`. O segundo confirma que os valores unidos correspondem a `format(date)`, sem presumir separadores específicos.
Lições relacionadas
- JavaScript · Lição 25 · Avançado · Versão: 4