Comment formater des durées comme 2:30:45 ?

Introduction

Les lecteurs vidéo, les chronomètres et les minuteurs affichent les durées dans un format familier. Vous voyez "2:30:45" et comprenez immédiatement qu'il s'agit de 2 heures, 30 minutes et 45 secondes. Ce format d'horloge numérique utilise des deux-points pour séparer les unités de temps sans étiquettes ni espacement.

Construire ce format manuellement nécessite de compléter les nombres avec des zéros et de gérer différentes longueurs de durée. Une vidéo qui dure 5 minutes et 30 secondes affiche "5:30" tandis qu'une vidéo de 2 heures affiche "2:00:00". La logique devient complexe avec les cas particuliers.

function formatDuration(seconds) {
  const h = Math.floor(seconds / 3600);
  const m = Math.floor((seconds % 3600) / 60);
  const s = Math.floor(seconds % 60);

  if (h > 0) {
    return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
  }
  return `${m}:${String(s).padStart(2, '0')}`;
}

L'API Intl.DurationFormat gère cela automatiquement avec l'option de style digital. Elle produit le format correct pour n'importe quelle longueur de durée.

const duration = { hours: 2, minutes: 30, seconds: 45 };
new Intl.DurationFormat('en', { style: 'digital' }).format(duration);
// "2:30:45"

Utiliser le style digital pour les affichages de minuterie

Le style digital formate les durées comme une horloge numérique. Définissez l'option style sur "digital" lors de la création du formateur.

const formatter = new Intl.DurationFormat('en', { style: 'digital' });

Passez un objet de durée avec les unités de temps que vous souhaitez afficher. Le formateur ajoute des deux-points entre les unités et complète les valeurs avec des zéros si nécessaire.

const duration = { hours: 1, minutes: 5, seconds: 30 };
formatter.format(duration);
// "1:05:30"

Remarquez comment les minutes s'affichent comme "05" au lieu de "5". Le formateur complète automatiquement les minutes à deux chiffres lorsque les heures sont présentes. Cela maintient l'alignement dans les listes et les tableaux.

Pour les durées sans heures, omettez cette propriété de l'objet de durée.

const shortDuration = { minutes: 5, seconds: 30 };
formatter.format(shortDuration);
// "5:30"

Les minutes n'ont plus besoin d'être complétées lorsqu'elles sont l'unité la plus grande. Le format reste compact tout en restant clair.

Comment le format numérique gère différentes longueurs de durée

Le format numérique ajuste l'affichage en fonction des unités que vous incluez dans l'objet de durée. Cela correspond à la façon dont les lecteurs vidéo adaptent leur affichage à la longueur de la vidéo.

Une durée courte affiche uniquement les minutes et les secondes.

const formatter = new Intl.DurationFormat('en', { style: 'digital' });

const short = { minutes: 3, seconds: 42 };
formatter.format(short);
// "3:42"

Une durée plus longue inclut les heures.

const long = { hours: 2, minutes: 15, seconds: 8 };
formatter.format(long);
// "2:15:08"

Lorsque les heures apparaissent, toutes les unités plus petites sont complétées à deux chiffres. Lorsque les heures sont absentes, les minutes s'affichent sans complétion mais les secondes restent complétées.

Cette règle de complétion crée un alignement cohérent sans gaspiller d'espace. Une liste de vidéos courtes affiche "5:30", "12:45", "8:02" avec des deux-points alignés. Une liste de vidéos longues affiche "1:05:30", "2:12:45", "3:08:02" avec un formatage cohérent.

Incluez uniquement les unités dont votre interface a besoin. Un compte à rebours qui ne dépasse jamais une heure peut omettre complètement les heures.

const countdown = { minutes: 42, seconds: 15 };
formatter.format(countdown);
// "42:15"

Contrôler le remplissage par des zéros et les options d'affichage

Le format numérique utilise des règles de complétion par défaut, mais vous pouvez les remplacer en spécifiant des options pour des unités de temps individuelles.

Contrôlez l'affichage de chaque unité en définissant des options spécifiques. La valeur numeric affiche le nombre sans complétion. La valeur 2-digit force la complétion à deux chiffres.

const duration = { hours: 1, minutes: 5, seconds: 3 };

new Intl.DurationFormat('en', {
  style: 'digital',
  hours: 'numeric',
  minutes: '2-digit',
  seconds: '2-digit'
}).format(duration);
// "1:05:03"

C'est le comportement par défaut. Vous n'avez besoin de spécifier ces options que lorsque vous souhaitez un formatage différent.

Forcez l'affichage des heures à toujours montrer deux chiffres.

new Intl.DurationFormat('en', {
  style: 'digital',
  hours: '2-digit',
  minutes: '2-digit',
  seconds: '2-digit'
}).format(duration);
// "01:05:03"

Ce format fonctionne bien pour les affichages synchronisés où une largeur constante évite les décalages de mise en page.

Supprimez la complétion des secondes pour un affichage plus compact.

const shortDuration = { minutes: 5, seconds: 3 };

new Intl.DurationFormat('en', {
  style: 'digital',
  seconds: 'numeric'
}).format(shortDuration);
// "5:3"

Ce format est moins courant car les utilisateurs s'attendent à ce que les secondes soient complétées dans les affichages numériques.

Ajouter des fractions de secondes au format numérique

Certaines applications doivent afficher des millisecondes ou des microsecondes. Le format numérique prend en charge les fractions de secondes avec l'option fractionalDigits.

Définissez le nombre de décimales à afficher après les secondes.

const duration = {
  minutes: 5,
  seconds: 30,
  milliseconds: 123
};

new Intl.DurationFormat('en', {
  style: 'digital',
  fractionalDigits: 3
}).format(duration);
// "5:30.123"

Le formateur ajoute un point décimal après les secondes et affiche le nombre spécifié de chiffres fractionnaires.

Les chronomètres affichent généralement des centièmes de seconde.

const lap = {
  minutes: 1,
  seconds: 23,
  milliseconds: 450
};

new Intl.DurationFormat('en', {
  style: 'digital',
  fractionalDigits: 2
}).format(lap);
// "1:23.45"

Le formateur arrondit à la précision spécifiée. La valeur 450 millisecondes devient 45 centièmes.

Pour une précision en microsecondes, incluez les microsecondes dans l'objet de durée et définissez des chiffres fractionnaires plus élevés.

const precise = {
  seconds: 42,
  milliseconds: 123,
  microseconds: 456
};

new Intl.DurationFormat('en', {
  style: 'digital',
  fractionalDigits: 6
}).format(precise);
// "42.123456"

Quand utiliser le format numérique par rapport aux autres styles

Choisissez le format numérique lorsque votre interface ressemble à un minuteur, un chronomètre ou un lecteur multimédia. Les utilisateurs s'attendent à ce format dans ces contextes.

Utilisez le format numérique pour les contrôles de lecteur vidéo.

function formatVideoTime(seconds) {
  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  const secs = Math.floor(seconds % 60);

  const duration = hours > 0
    ? { hours, minutes, seconds: secs }
    : { minutes, seconds: secs };

  return new Intl.DurationFormat('en', { style: 'digital' }).format(duration);
}

formatVideoTime(6345); // "1:45:45"
formatVideoTime(125);  // "2:05"

Utilisez le format numérique pour les minuteurs de compte à rebours et les chronomètres.

function formatStopwatch(milliseconds) {
  const minutes = Math.floor(milliseconds / 60000);
  const seconds = Math.floor((milliseconds % 60000) / 1000);
  const ms = milliseconds % 1000;

  return new Intl.DurationFormat('en', {
    style: 'digital',
    fractionalDigits: 2
  }).format({ minutes, seconds, milliseconds: ms });
}

formatStopwatch(125450); // "2:05.45"

Utilisez d'autres styles lors de l'affichage des durées dans du texte ou lorsque des étiquettes améliorent la clarté. Les sites de réservation de vols affichent "8 h 15 min" au lieu de "8:15:00" car le contexte n'est pas celui d'un minuteur.

// Bon pour le texte et les descriptions
new Intl.DurationFormat('en', { style: 'short' }).format(duration);
// "1 hr, 46 min and 40 sec"

// Bon pour les affichages de minuterie
new Intl.DurationFormat('en', { style: 'digital' }).format(duration);
// "1:46:40"

Construire manuellement le format numérique pour les navigateurs plus anciens

L'API Intl.DurationFormat est devenue disponible en mars 2025. Pour les navigateurs plus anciens, construisez le format numérique manuellement.

L'approche manuelle nécessite de calculer les unités de temps à partir du total de secondes et de compléter les valeurs avec des zéros.

function formatDigitalDuration(totalSeconds) {
  const hours = Math.floor(totalSeconds / 3600);
  const minutes = Math.floor((totalSeconds % 3600) / 60);
  const seconds = Math.floor(totalSeconds % 60);

  if (hours > 0) {
    const paddedMinutes = String(minutes).padStart(2, '0');
    const paddedSeconds = String(seconds).padStart(2, '0');
    return `${hours}:${paddedMinutes}:${paddedSeconds}`;
  } else {
    const paddedSeconds = String(seconds).padStart(2, '0');
    return `${minutes}:${paddedSeconds}`;
  }
}

formatDigitalDuration(6345); // "1:45:45"
formatDigitalDuration(125);  // "2:05"

La fonction divise le total des secondes par 3600 pour obtenir les heures. Le reste divisé par 60 donne les minutes. Le reste final correspond aux secondes.

La méthode padStart() ajoute des zéros en tête lorsque la valeur est inférieure à 10. Cela garantit que "5" devient "05" pour un formatage cohérent.

Pour les durées stockées sous forme d'objets de durée plutôt que de secondes totales, extrayez directement les valeurs.

function formatDurationObject(duration) {
  const h = duration.hours || 0;
  const m = duration.minutes || 0;
  const s = duration.seconds || 0;

  if (h > 0) {
    return `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
  }
  return `${m}:${String(s).padStart(2, '0')}`;
}

formatDurationObject({ hours: 1, minutes: 5, seconds: 30 }); // "1:05:30"
formatDurationObject({ minutes: 5, seconds: 30 }); // "5:30"

Ajoutez des secondes fractionnaires en incluant des millisecondes et en formatant avec une précision décimale.

function formatWithMilliseconds(duration) {
  const m = duration.minutes || 0;
  const s = duration.seconds || 0;
  const ms = duration.milliseconds || 0;

  const paddedSeconds = String(s).padStart(2, '0');
  const fractional = String(ms).padStart(3, '0').slice(0, 2);

  return `${m}:${paddedSeconds}.${fractional}`;
}

formatWithMilliseconds({ minutes: 1, seconds: 23, milliseconds: 450 });
// "1:23.45"

Vérifiez la prise en charge de l'API avant de l'utiliser.

function formatDuration(duration) {
  if (typeof Intl.DurationFormat !== 'undefined') {
    return new Intl.DurationFormat('en', { style: 'digital' }).format(duration);
  } else {
    return formatDurationObject(duration);
  }
}

Cette approche fournit une sortie cohérente sur tous les navigateurs tout en utilisant l'API native lorsqu'elle est disponible.

Modèles courants pour les lecteurs vidéo et les minuteurs

Les lecteurs vidéo doivent formater à la fois le temps actuel et la durée totale. Créez un formateur réutilisable pour gérer les deux valeurs.

const videoFormatter = new Intl.DurationFormat('en', { style: 'digital' });

function formatVideoPosition(currentSeconds, totalSeconds) {
  const current = secondsToDuration(currentSeconds);
  const total = secondsToDuration(totalSeconds);

  return `${videoFormatter.format(current)} / ${videoFormatter.format(total)}`;
}

function secondsToDuration(seconds) {
  const hours = Math.floor(seconds / 3600);
  const minutes = Math.floor((seconds % 3600) / 60);
  const secs = Math.floor(seconds % 60);

  return hours > 0
    ? { hours, minutes, seconds: secs }
    : { minutes, seconds: secs };
}

formatVideoPosition(125, 6345); // "2:05 / 1:45:45"

Pour les minuteurs de compte à rebours qui se mettent à jour à chaque image, créez le formateur une seule fois et réutilisez-le.

const timerFormatter = new Intl.DurationFormat('en', {
  style: 'digital',
  fractionalDigits: 2
});

function updateTimer(remainingMs) {
  const duration = {
    minutes: Math.floor(remainingMs / 60000),
    seconds: Math.floor((remainingMs % 60000) / 1000),
    milliseconds: remainingMs % 1000
  };

  document.getElementById('timer').textContent = timerFormatter.format(duration);
}

Pour les chronomètres qui affichent les temps au tour, formatez le temps écoulé avec des secondes fractionnaires.

const lapFormatter = new Intl.DurationFormat('en', {
  style: 'digital',
  fractionalDigits: 3
});

function formatLapTime(startMs, endMs) {
  const elapsedMs = endMs - startMs;

  return lapFormatter.format({
    minutes: Math.floor(elapsedMs / 60000),
    seconds: Math.floor((elapsedMs % 60000) / 1000),
    milliseconds: elapsedMs % 1000
  });
}

const lap1Start = performance.now();
// ... le temps passe ...
const lap1End = performance.now();

formatLapTime(lap1Start, lap1End); // "1:23.456"

Ces modèles gèrent les scénarios de formatage de durée les plus courants tout en maintenant un code propre et réutilisable.