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

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