CKTIS / JavaScript
Intl.RelativeTimeFormat.prototype.format() — formatar tempo relativo
Converte um desfasamento temporal com sinal e uma unidade explícita em texto localizado. O método não calcula a diferença entre datas.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
const formatter = new Intl.RelativeTimeFormat(locales, options);
formatter.format(value, unit);Intl.RelativeTimeFormat.prototype.format é um método de instância. formatter.format(value, unit) devolve uma cadeia de caracteres de acordo com a configuração regional efetivamente selecionada e as opções definidas no construtor. A aplicação calcula o desfasamento em relação a um ponto de referência e escolhe a unidade; o método não consulta o relógio nem subtrai datas.
Os valores negativos indicam o passado e os positivos, o futuro. Quando se usa um padrão numérico, -0 seleciona o padrão do passado e +0 o do futuro. unit aceita os identificadores exatos "second", "minute", "hour", "day", "week", "month", "quarter" e "year", bem como as formas terminadas em s. A forma do identificador não determina a gramática do resultado.
numeric: "always" (predefinido) usa um padrão numérico. numeric: "auto" usa uma expressão específica, como yesterday, se estiver disponível; caso contrário, recorre ao padrão numérico. style permite escolher "long" (predefinido), "short" ou "narrow". O suporte varia consoante o ambiente de execução, e o texto pode diferir mesmo com a mesma configuração regional, por exemplo, pelo uso de espaços inquebráveis. Em testes portáveis, não compares o resultado com texto fixo.
O método precisa de uma instância como this; chamá-lo separadamente sem um this válido lança TypeError. Para o usar como função de retorno de chamada, utiliza formatter.format.bind(formatter). Depois de verificar this, o método aplica ToNumber a value e depois ToString a unit. Por exemplo, um BigInt como value lança TypeError. Após a conversão, NaN, Infinity, -Infinity ou um identificador de unidade não suportado provocam RangeError.
Exemplos
{
const numeric = new Intl.RelativeTimeFormat("en", { numeric: "always" });
const auto = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
const past = numeric.format(-1, "day");
console.log(past);
console.log(auto.format(-1, "day"));
console.log(past === numeric.format(-1, "days"));
}Resultado
1 day ago yesterday true
Para o mesmo desfasamento de `-1` dia, as duas primeiras linhas mostram texto típico em inglês com `"always"` e `"auto"`. A terceira mostra que `"day"` e `"days"` são equivalentes.
Lições relacionadas
- JavaScript · Lição 24 · Avançado · Versão: 4
Fontes
- ECMAScript® 2024 Internationalization API Specification — Intl.RelativeTimeFormat.prototype.format
- ECMAScript® 2024 Internationalization API Specification — PartitionRelativeTimePattern
- ECMAScript Internationalization API Specification (living draft) — Intl.RelativeTimeFormat.prototype.format
- Intl.RelativeTimeFormat.prototype.format() - JavaScript | MDN