O Intl.DurationFormat agora está disponível como referência

Jeremy Wagner

Publicado em 20 de março de 2025

Uma informação comum que você pode encontrar em uma página da Web é um texto que informa quanto tempo falta para um determinado evento ou quanto tempo se passou desde que ele ocorreu. Isso geralmente é representado como uma string que comunica a duração em horas, minutos, segundos ou outras unidades de tempo úteis.

O Intl.DurationFormat é um recurso útil que faz isso para você no navegador, considerando as necessidades de internacionalização que você possa ter, sem a necessidade de JavaScript adicional. A partir de março de 2025, ela passou a ser a referência recém-disponível.

Como o Intl.DurationFormat funciona

Intl.DurationFormat é uma classe que, quando instanciada, retorna uma string que descreve a duração do tempo. Ele funciona especificando um objeto com chaves e valores que correspondem às unidades de tempo para as quais você quer que uma string seja gerada:

// Specify the duration:
const duration = {
  years: 1,
  hours: 20,
  minutes: 15,
  seconds: 35
};

// Output: '1 yr, 20 hr, 15 min, 35 sec'
new Intl.DurationFormat('en').format(duration);

Para retornar uma string em um formato longo, transmita um valor de 'long' para a opção style no segundo argumento do construtor:

const duration = {
  years: 1,
  hours: 20,
  minutes: 15,
  seconds: 35
};

// Output: '1 year, 20 hours, 15 minutes, 35 seconds'
new Intl.DurationFormat('en', { style: 'long' }).format(duration);

Até agora, esses exemplos geram strings em inglês. Como esse é um recurso de internacionalização, ele é útil para transmitir qualquer localidade válida e receber strings formatadas no idioma necessário:

const duration = {
  years: 1,
  hours: 20,
  minutes: 15,
  seconds: 35
};

// Output: '1 Jahr, 20 Stunden, 15 Minuten und 35 Sekunden'
new Intl.DurationFormat('de', { style: 'long' }).format(duration);

// Output: '1 año, 20 horas, 15 minutos y 35 segundos'
new Intl.DurationFormat('es', { style: 'long' }).format(duration);

// Output: '1年20小时15分钟35秒钟'
new Intl.DurationFormat('zh', { style: 'long' }).format(duration);

// Output: '1 år, 20 timer, 15 minutter og 35 sekunder'
new Intl.DurationFormat('no', { style: 'long' }).format(duration);

// Output: 'mwaka 1, saa 20, dakika 15 na sekunde 35'
new Intl.DurationFormat('sw', { style: 'long' }).format(duration);

Esses exemplos apenas mostram o que você pode fazer com esse novo recurso. Para saber mais sobre o que ele pode fazer, leia a documentação do Intl.DurationFormat no MDN.