Intl.RelativeTimeFormat

O objeto Intl.RelativeTimeFormat é um construtor de objetos que permitem uma formatação de tempo relativa sensível ao idioma.

Sintaxe

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

Parâmetros

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.

Descrição

Propriedades

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

Métodos

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 

Propriedades

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

Métodos

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

Exemplos

Uso básico do format

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"

Usando a opção auto

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ã"

Usando formatToParts

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"]

Especificações

Especificação Estágio Comentário
Intl.RelativeTime proposal Stage 3  

Compatibilidade com Browsers

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
RelativeTimeFormatChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 12.0.0
Notes
Full support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. See the RelativeTimeFormat() constructor for more details.
RelativeTimeFormat() constructorChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 13.0.0
Full support 13.0.0
Partial support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. When other locales are specified, the RelativeTimeFormat instance silently falls back to en-US. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.
formatChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 12.0.0
Notes
Full support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. See the RelativeTimeFormat() constructor for more details.
formatToPartsChrome Full support 71Edge Full support 79Firefox Full support 70IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android No support NoOpera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 12.0.0
Notes
Full support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. See the RelativeTimeFormat() constructor for more details.
resolvedOptionsChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 12.0.0
Notes
Full support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. See the RelativeTimeFormat() constructor for more details.
supportedLocalesOfChrome Full support 71Edge Full support 79Firefox Full support 65IE No support NoOpera Full support 58Safari Full support 14WebView Android Full support 71Chrome Android Full support 71Firefox Android Full support 65Opera Android Full support 50Safari iOS Full support 14Samsung Internet Android Full support 10.0nodejs Full support 13.0.0
Full support 13.0.0
Partial support 12.0.0
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

 

Veja também