CKTIS / JavaScript
Intl.DateTimeFormat: consultar as opções efetivas
Usa `resolvedOptions()` para saber que definições de formatação de data e hora a instância utiliza de facto, sem as deduzir dos argumentos do construtor.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
formatter.resolvedOptions()Intl.DateTimeFormat.prototype.resolvedOptions é um método de instância sem argumentos. Cada chamada devolve um novo objeto comum com as definições determinadas ao criar o formatador. Alterar o resultado não altera o formatador. Ao contrário de format(), o método não recebe uma data nem produz texto formatado. Chamá-lo sem o vincular à instância ou com um this incompatível, como {}, lança um TypeError.
O resultado inclui locale (a etiqueta de língua BCP 47 efetivamente selecionada), calendar, numberingSystem e timeZone. Não é uma cópia dos dados passados ao construtor: a negociação das definições regionais e os valores predefinidos podem alterar o resultado. Sem um timeZone explícito, o formatador adota, quando é criado, o fuso horário predefinido do ambiente de execução. O identificador do fuso pode ser normalizado, pelo que pode não coincidir exatamente com a cadeia de caracteres fornecida.
Sem dateStyle nem timeStyle, propriedades como year, month e hour refletem o padrão selecionado; os componentes não usados são omitidos. Com dateStyle ou timeStyle, o resultado indica os estilos pedidos sem os decompor em componentes individuais. Combinar um estilo com uma opção explícita de componente, como hour, lança um TypeError no construtor.
Se o padrão incluir a hora, o resultado tem hourCycle e o valor dele derivado, hour12, mesmo quando timeStyle faz com que a propriedade hour não apareça. hour12 é true para h11 e h12, e false para h23 e h24. Se o padrão não incluir a hora, ambas as propriedades são omitidas. Na escolha do ciclo, a opção hour12 tem prioridade sobre hourCycle e sobre a extensão Unicode hc.
Usa o resultado para diagnosticar diferenças entre ambientes de execução. O suporte das opções e os dados regionais podem variar, e opções efetivas iguais não garantem texto formatado idêntico.
Exemplos
const formatter = new Intl.DateTimeFormat("en-GB", {
timeZone: "UTC",
timeStyle: "short",
hour12: false,
});
const options = formatter.resolvedOptions();
console.log(options.timeZone);
console.log(options.timeStyle);
console.log(options.hour12);
console.log(Object.hasOwn(options, "hour"));
options.timeZone = "Asia/Tokyo";
console.log(formatter.resolvedOptions().timeZone);Resultado
UTC short false false UTC
O código escreve `UTC`, `short`, `false`, `false` e `UTC`, por essa ordem. O primeiro `false` indica o formato de 24 horas; o segundo indica que não há uma propriedade própria `hour`. A atribuição de `Asia/Tokyo` altera apenas o objeto devolvido.
Lições relacionadas
- JavaScript · Lição 25 · Avançado · Versão: 4
Fontes
- ECMAScript® 2024 Internationalization API Specification — Intl.DateTimeFormat.prototype.resolvedOptions
- ECMAScript Internationalization API Specification (living draft) — Intl.DateTimeFormat.prototype.resolvedOptions
- ECMAScript Internationalization API Specification (living draft) — CreateDateTimeFormat