Intl.RelativeTimeFormat

new Intl.RelativeTimeFormat([locales[, options]])

locales

Opcional. Uma string com uma tag da linguagem BCP 47, ou um array dessas strings. Para a forma geral e interpretação do argumento locales , acesse: Página Intl.

options

Opcional. Um objeto com algumas ou todas as seguintes propriedades:

• localeMatcher O algoritmo para comparação de local a ser usado. Os valores possíveis são "lookup" e "best fit"; o padrão é "best fit". Para informações sobre esta opção, veja Intl.

• numeric O formato de saída da mensagem. Valores possíveis são:

  • "always" (padrão, e.g., há 1 dia),
  • ou "auto" (e.g., ontem). O valor"auto" permite que não seja sempre necessário o uso de valores númericos na saída.

• style O comprimento da mensagem internacionalizada. Valores possíveis são:

  • "long" (padrão, e.g., in 1 month)
  • "short" (e.g., in 1 mo.),
  • ou "narrow" (e.g., in 1 mo.). O estilo narrow pode ser similar ao short em alguns locais.

Intl.RelativeTimeFormat.prototype

Permite a adição de propriedades para todos os objetos.

Intl.RelativeTimeFormat.supportedLocalesOf()

Retorna um array contendo os valores disponíveis dentre os que foram passados como parâmetro sem ter de recorrer ao local padrão do ambiente.

Instâncias RelativeTimeFormat herdam as seguintes propriedades do seu protótipo:

Instâncias RelativeTimeFormat herdam as seguintes propriedades do seu protótipo:

O exemplo a seguir mostra como criar um formatador de tempo relativo usando a língua portuguesa.

// Crie um formatador de tempo relativo no seu local
// com os valores padrão sendo passados explicitamente.
const rtf = new Intl.RelativeTimeFormat("pt", {
  localeMatcher: "best fit", // outros valores: "lookup"
  numeric: "always", // outros valores: "auto"
  style: "long", // outros valores: "short" ou "narrow"
});

// Formatação de tempo relativa usando valor negativo (-1).
rtf.format(-1, "day");
// > "há 1 dia"

// Formatação de tempo relativa usando valor positivo (1).
rtf.format(1, "day");
// > "em 1 dia"

Se a opção numeric:auto é passada, serão produzidas as strings ontem ou amanhã ao invés de há 1 dia ou em 1 dia. Isso permite que não seja necessário sempre utilizar valores numéricos na saída.

// Crie um formatador de tempo relativo no seu local
// com o valor "auto" passado para a propriedade numeric.
const rtf = new Intl.RelativeTimeFormat("pt", { numeric: "auto" });

// Formatação de tempo relativa usando valor negativo (-1).
rtf.format(-1, "day");
// > "ontem"

// Formatação de tempo relativa usando valor positivo (1).
rtf.format(1, "day");
// > "amanhã"

O exemplo a seguir mostra como criar um formatador de tempo relativo que retorna partes formatadas

const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

// Formatação de tempo relativa usando a unidade day.
rtf.formatToParts(-1, "day");
// > [{type: "literal", value: "ontem"}]

rtf.formatToParts(100, "day");
// > [{type: "literal", value: "em "},
// >  { type: "integer", value: "100", unit: "day" },
// >  {type: "literal", value: " dias"]

• The Intl.RelativeTimeFormat API