API Intl.DateTimeFormat

Formatez les dates et les heures pour n'importe quelle locale sans bibliothèques externes

Introduction

Les dates s'affichent différemment à travers le monde. Le 15 janvier 2024 apparaît comme 1/15/2024 aux États-Unis, 15/1/2024 au Royaume-Uni et 2024/1/15 au Japon. Les formats horaires varient également. Les Américains utilisent des horloges de 12 heures avec AM et PM, tandis que la plupart du monde utilise le format 24 heures.

Construire manuellement une logique de formatage de date pour différentes locales est complexe et sujet aux erreurs. Vous devez gérer l'ordre des jours et des mois, les séparateurs, les formats horaires, les conversions de fuseaux horaires et les cas particuliers comme les calendriers non grégoriens.

L'API Intl.DateTimeFormat résout ce problème. Elle fournit un formatage de date et d'heure intégré et adapté aux locales dans tous les navigateurs modernes. Aucune bibliothèque externe n'est requise.

Utilisation de base

La façon la plus simple de formater une date est de créer une instance Intl.DateTimeFormat et d'appeler sa méthode format().

const date = new Date(2024, 0, 15, 14, 30);

const formatter = new Intl.DateTimeFormat("en-US");
formatter.format(date);
// "1/15/2024"

Changez la locale pour voir différentes conventions de formatage.

const ukFormatter = new Intl.DateTimeFormat("en-GB");
ukFormatter.format(date);
// "15/01/2024"

const japanFormatter = new Intl.DateTimeFormat("ja-JP");
japanFormatter.format(date);
// "2024/1/15"

La même date, formatée de trois manières différentes selon les conventions locales.

Comprendre les locales

Une locale est une chaîne qui identifie une langue et des préférences régionales. Le format suit la norme BCP 47 : code de langue, suivi éventuellement d'un code de région.

Modèles de locales courants :

"en"      // Anglais (générique)
"en-US"   // Anglais (États-Unis)
"en-GB"   // Anglais (Royaume-Uni)
"es"      // Espagnol (générique)
"es-MX"   // Espagnol (Mexique)
"es-ES"   // Espagnol (Espagne)
"zh-CN"   // Chinois (Chine, simplifié)
"zh-TW"   // Chinois (Taïwan, traditionnel)

Si vous omettez le paramètre de locale, le navigateur utilise la locale par défaut de l'utilisateur.

const formatter = new Intl.DateTimeFormat();
formatter.format(date);
// La sortie varie en fonction de la locale du navigateur de l'utilisateur

Vous pouvez également fournir un tableau de locales. Le navigateur utilise la première locale prise en charge.

const formatter = new Intl.DateTimeFormat(["es-MX", "es", "en"]);
// Utilise l'espagnol (Mexique) si disponible, se replie sur l'espagnol générique, puis l'anglais

Aperçu des options de formatage

Le constructeur Intl.DateTimeFormat accepte un objet d'options qui contrôle ce qui apparaît dans le résultat formaté. Il existe deux approches pour le formatage.

La première approche utilise des raccourcis de style. Ceux-ci fournissent un formatage rapide et conventionnel.

const formatter = new Intl.DateTimeFormat("en-US", {
  dateStyle: "full",
  timeStyle: "short"
});

formatter.format(date);
// "Monday, January 15, 2024 at 2:30 PM"

La seconde approche utilise des options de composants. Celles-ci donnent un contrôle granulaire sur chaque partie de la date.

const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "numeric",
  minute: "numeric"
});

formatter.format(date);
// "January 15, 2024 at 2:30 PM"

Vous ne pouvez pas mélanger les raccourcis de style avec les options de composants. Choisissez une approche par formateur.

Raccourcis de style

Les options dateStyle et timeStyle fournissent quatre niveaux de formatage prédéfinis.

L'option dateStyle formate la partie date.

const date = new Date(2024, 0, 15);

const full = new Intl.DateTimeFormat("en-US", { dateStyle: "full" });
full.format(date);
// "Monday, January 15, 2024"

const long = new Intl.DateTimeFormat("en-US", { dateStyle: "long" });
long.format(date);
// "January 15, 2024"

const medium = new Intl.DateTimeFormat("en-US", { dateStyle: "medium" });
medium.format(date);
// "Jan 15, 2024"

const short = new Intl.DateTimeFormat("en-US", { dateStyle: "short" });
short.format(date);
// "1/15/24"

L'option timeStyle formate la partie heure.

const date = new Date(2024, 0, 15, 14, 30, 45);

const full = new Intl.DateTimeFormat("en-US", { timeStyle: "full" });
full.format(date);
// "2:30:45 PM Eastern Standard Time"

const long = new Intl.DateTimeFormat("en-US", { timeStyle: "long" });
long.format(date);
// "2:30:45 PM EST"

const medium = new Intl.DateTimeFormat("en-US", { timeStyle: "medium" });
medium.format(date);
// "2:30:45 PM"

const short = new Intl.DateTimeFormat("en-US", { timeStyle: "short" });
short.format(date);
// "2:30 PM"

Combinez les deux options pour formater la date et l'heure ensemble.

const formatter = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short"
});

formatter.format(date);
// "Jan 15, 2024, 2:30 PM"

Les raccourcis de style s'adaptent automatiquement aux conventions locales.

const usFormatter = new Intl.DateTimeFormat("en-US", {
  dateStyle: "short",
  timeStyle: "short"
});
usFormatter.format(date);
// "1/15/24, 2:30 PM"

const deFormatter = new Intl.DateTimeFormat("de-DE", {
  dateStyle: "short",
  timeStyle: "short"
});
deFormatter.format(date);
// "15.1.24, 14:30"

Le format allemand utilise des points comme séparateurs, inverse l'ordre du jour et du mois, et affiche l'heure au format 24 heures. Le format américain utilise des barres obliques, un ordre mois-jour, et l'heure au format 12 heures avec AM/PM. Mêmes options, résultats différents selon la locale.

Options des composants

Les options des composants offrent un contrôle précis sur ce qui s'affiche et comment. Chaque option spécifie une partie de la date ou de l'heure.

L'option year affiche l'année.

const formatter = new Intl.DateTimeFormat("en-US", { year: "numeric" });
formatter.format(date);
// "2024"

const twoDigit = new Intl.DateTimeFormat("en-US", { year: "2-digit" });
twoDigit.format(date);
// "24"

L'option month affiche le mois dans différents formats.

const numeric = new Intl.DateTimeFormat("en-US", { month: "numeric" });
numeric.format(date);
// "1"

const twoDigit = new Intl.DateTimeFormat("en-US", { month: "2-digit" });
twoDigit.format(date);
// "01"

const long = new Intl.DateTimeFormat("en-US", { month: "long" });
long.format(date);
// "January"

const short = new Intl.DateTimeFormat("en-US", { month: "short" });
short.format(date);
// "Jan"

const narrow = new Intl.DateTimeFormat("en-US", { month: "narrow" });
narrow.format(date);
// "J"

L'option day affiche le jour du mois.

const formatter = new Intl.DateTimeFormat("en-US", { day: "numeric" });
formatter.format(date);
// "15"

const twoDigit = new Intl.DateTimeFormat("en-US", { day: "2-digit" });
twoDigit.format(date);
// "15"

L'option weekday affiche le jour de la semaine.

const long = new Intl.DateTimeFormat("en-US", { weekday: "long" });
long.format(date);
// "Monday"

const short = new Intl.DateTimeFormat("en-US", { weekday: "short" });
short.format(date);
// "Mon"

const narrow = new Intl.DateTimeFormat("en-US", { weekday: "narrow" });
narrow.format(date);
// "M"

Combinez plusieurs options de composants pour créer des formats de date personnalisés.

const formatter = new Intl.DateTimeFormat("en-US", {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric"
});

formatter.format(date);
// "Monday, January 15, 2024"

Le navigateur gère l'espacement et la ponctuation selon les conventions locales.

Formatage de l'heure

Les options du composant de temps contrôlent l'affichage des heures, minutes et secondes.

const date = new Date(2024, 0, 15, 14, 30, 45);

const formatter = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  second: "numeric"
});

formatter.format(date);
// "2:30:45 PM"

L'option hour12 contrôle l'affichage du temps en format 12 heures ou 24 heures.

const hour12 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  hour12: true
});
hour12.format(date);
// "2:30 PM"

const hour24 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  hour12: false
});
hour24.format(date);
// "14:30"

L'option hourCycle offre un contrôle plus précis sur l'affichage des heures. Quatre options existent.

// h11: 0-11
const h11 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  hourCycle: "h11"
});
h11.format(new Date(2024, 0, 15, 0, 30));
// "0:30 AM"

// h12: 1-12
const h12 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  hourCycle: "h12"
});
h12.format(new Date(2024, 0, 15, 0, 30));
// "12:30 AM"

// h23: 0-23
const h23 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  hourCycle: "h23"
});
h23.format(new Date(2024, 0, 15, 0, 30));
// "0:30"

// h24: 1-24
const h24 = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  hourCycle: "h24"
});
h24.format(new Date(2024, 0, 15, 0, 30));
// "24:30"

La différence est importante à minuit. Le cycle h11 utilise 0, tandis que h12 utilise 12. De même, h23 utilise 0, tandis que h24 utilise 24.

L'option dayPeriod ajoute des marqueurs de période descriptifs pour le format 12 heures.

const morning = new Date(2024, 0, 15, 10, 30);
const afternoon = new Date(2024, 0, 15, 14, 30);
const night = new Date(2024, 0, 15, 22, 30);

const formatter = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  dayPeriod: "long"
});

formatter.format(morning);
// "10:30 in the morning"

formatter.format(afternoon);
// "2:30 in the afternoon"

formatter.format(night);
// "10:30 at night"

L'option dayPeriod fonctionne uniquement avec les formats d'heure sur 12 heures.

L'option fractionalSecondDigits affiche la précision des sous-secondes.

const date = new Date(2024, 0, 15, 14, 30, 45, 123);

const oneDigit = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  fractionalSecondDigits: 1
});
oneDigit.format(date);
// "2:30:45.1 PM"

const threeDigits = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  fractionalSecondDigits: 3
});
threeDigits.format(date);
// "2:30:45.123 PM"

Vous pouvez spécifier un, deux ou trois chiffres fractionnaires.

Gestion des fuseaux horaires

L'option timeZone convertit les dates dans des fuseaux horaires spécifiques.

const date = new Date("2024-01-15T14:30:00Z"); // Heure UTC

const newYork = new Intl.DateTimeFormat("en-US", {
  timeZone: "America/New_York",
  dateStyle: "full",
  timeStyle: "long"
});
newYork.format(date);
// "Monday, January 15, 2024 at 9:30:00 AM EST"

const tokyo = new Intl.DateTimeFormat("ja-JP", {
  timeZone: "Asia/Tokyo",
  dateStyle: "full",
  timeStyle: "long"
});
tokyo.format(date);
// "2024年1月15日月曜日 23:30:00 日本標準時"

const london = new Intl.DateTimeFormat("en-GB", {
  timeZone: "Europe/London",
  dateStyle: "full",
  timeStyle: "long"
});
london.format(date);
// "Monday, 15 January 2024 at 14:30:00 GMT"

Le même moment dans le temps s'affiche différemment selon le fuseau horaire. Utilisez les identifiants de fuseau horaire IANA comme America/New_York, Europe/London, ou Asia/Tokyo.

L'option timeZoneName affiche le nom du fuseau horaire.

const formatter = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  timeZone: "America/New_York",
  timeZoneName: "short"
});
formatter.format(date);
// "9:30 AM EST"

const long = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  timeZone: "America/New_York",
  timeZoneName: "long"
});
long.format(date);
// "9:30 AM Eastern Standard Time"

const shortOffset = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  timeZone: "America/New_York",
  timeZoneName: "shortOffset"
});
shortOffset.format(date);
// "9:30 AM GMT-5"

const longOffset = new Intl.DateTimeFormat("en-US", {
  hour: "numeric",
  minute: "numeric",
  timeZone: "America/New_York",
  timeZoneName: "longOffset"
});
longOffset.format(date);
// "9:30 AM GMT-05:00"

Différentes valeurs de timeZoneName fournissent différents niveaux de détail.

Systèmes de calendrier et systèmes de numération

L'option calendar prend en charge les calendriers non grégoriens.

const date = new Date(2024, 0, 15);

const gregorian = new Intl.DateTimeFormat("en-US", {
  calendar: "gregory",
  year: "numeric",
  month: "long",
  day: "numeric"
});
gregorian.format(date);
// "January 15, 2024"

const japanese = new Intl.DateTimeFormat("ja-JP", {
  calendar: "japanese",
  year: "numeric",
  month: "long",
  day: "numeric"
});
japanese.format(date);
// "令和6年1月15日"

const islamic = new Intl.DateTimeFormat("ar-SA", {
  calendar: "islamic",
  year: "numeric",
  month: "long",
  day: "numeric"
});
islamic.format(date);
// "٦ رجب ١٤٤٥"

const chinese = new Intl.DateTimeFormat("zh-CN", {
  calendar: "chinese",
  year: "numeric",
  month: "long",
  day: "numeric"
});
chinese.format(date);
// "2023甲辰年腊月初五"

La même date se convertit dans différents systèmes de calendrier. Les calendriers disponibles comprennent gregory, japanese, islamic, islamic-umalqura, islamic-tbla, islamic-civil, islamic-rgsa, chinese, hebrew, indian, persian, et d'autres.

L'option numberingSystem affiche les chiffres dans différents systèmes d'écriture.

const date = new Date(2024, 0, 15);

const western = new Intl.DateTimeFormat("en-US", {
  numberingSystem: "latn",
  year: "numeric",
  month: "numeric",
  day: "numeric"
});
western.format(date);
// "1/15/2024"

const arabic = new Intl.DateTimeFormat("en-US", {
  numberingSystem: "arab",
  year: "numeric",
  month: "numeric",
  day: "numeric"
});
arabic.format(date);
// "١‏/١٥‏/٢٠٢٤"

const devanagari = new Intl.DateTimeFormat("en-US", {
  numberingSystem: "deva",
  year: "numeric",
  month: "numeric",
  day: "numeric"
});
devanagari.format(date);
// "१/१५/२०२४"

const bengali = new Intl.DateTimeFormat("en-US", {
  numberingSystem: "beng",
  year: "numeric",
  month: "numeric",
  day: "numeric"
});
bengali.format(date);
// "১/১৫/২০২৪"

Les systèmes de numération disponibles comprennent latn (chiffres occidentaux), arab (chiffres indo-arabes), arabext (chiffres indo-arabes étendus), beng (chiffres bengalis), deva (chiffres devanagari), et bien d'autres.

Formatage des plages de dates

La méthode formatRange() formate une plage de dates en omettant intelligemment les informations redondantes.

const start = new Date(2024, 0, 15);
const end = new Date(2024, 0, 20);

const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric"
});

formatter.formatRange(start, end);
// "January 15 – 20, 2024"

Le formateur omet les informations répétées. Les deux dates sont en janvier 2024, donc la sortie n'inclut le mois et l'année qu'une seule fois.

Lorsque la plage s'étend sur différents mois, les deux sont affichés.

const start = new Date(2024, 0, 15);
const end = new Date(2024, 1, 20);

formatter.formatRange(start, end);
// "January 15 – February 20, 2024"

Lorsque la plage s'étend sur différentes années, toutes les informations sont affichées.

const start = new Date(2024, 0, 15);
const end = new Date(2025, 1, 20);

formatter.formatRange(start, end);
// "January 15, 2024 – February 20, 2025"

La méthode formatRange() fonctionne également avec les plages horaires.

const start = new Date(2024, 0, 15, 14, 30);
const end = new Date(2024, 0, 15, 16, 45);

const formatter = new Intl.DateTimeFormat("en-US", {
  month: "long",
  day: "numeric",
  hour: "numeric",
  minute: "numeric"
});

formatter.formatRange(start, end);
// "January 15, 2:30 – 4:45 PM"

La date ne s'affiche qu'une seule fois car les deux horaires se produisent le même jour.

Accès aux parties formatées

La méthode formatToParts() renvoie un tableau d'objets représentant chaque partie de la date formatée. Cela permet une logique de formatage personnalisée.

const date = new Date(2024, 0, 15, 14, 30);

const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric",
  hour: "numeric",
  minute: "numeric"
});

const parts = formatter.formatToParts(date);

Chaque objet du tableau possède une propriété type et value.

[
  { type: "month", value: "January" },
  { type: "literal", value: " " },
  { type: "day", value: "15" },
  { type: "literal", value: ", " },
  { type: "year", value: "2024" },
  { type: "literal", value: " at " },
  { type: "hour", value: "2" },
  { type: "literal", value: ":" },
  { type: "minute", value: "30" },
  { type: "literal", value: " " },
  { type: "dayPeriod", value: "PM" }
]

Vous pouvez filtrer et manipuler ces parties pour créer des formats personnalisés.

const dateParts = parts.filter(part =>
  ["month", "day", "year"].includes(part.type)
);

const dateString = dateParts.map(part => part.value).join("/");
// "January/15/2024"

La méthode formatRangeToParts() offre la même fonctionnalité pour les plages de dates.

const start = new Date(2024, 0, 15);
const end = new Date(2024, 0, 20);

const formatter = new Intl.DateTimeFormat("en-US", {
  year: "numeric",
  month: "long",
  day: "numeric"
});

const parts = formatter.formatRangeToParts(start, end);

Chaque objet partie inclut une propriété source indiquant s'il provient de la date de début ou de fin.

[
  { type: "month", value: "January", source: "startRange" },
  { type: "literal", value: " ", source: "startRange" },
  { type: "day", value: "15", source: "startRange" },
  { type: "literal", value: " – ", source: "shared" },
  { type: "day", value: "20", source: "endRange" },
  { type: "literal", value: ", ", source: "shared" },
  { type: "year", value: "2024", source: "shared" }
]

Bonnes pratiques

Réutilisez les instances de formateur lors du formatage de plusieurs dates avec les mêmes options. La création d'un formateur implique une négociation de locale et une résolution d'options, ce qui entraîne un léger coût de performance.

// Moins efficace
dates.forEach(date => {
  const formatted = new Intl.DateTimeFormat("en-US").format(date);
  console.log(formatted);
});

// Plus efficace
const formatter = new Intl.DateTimeFormat("en-US");
dates.forEach(date => {
  const formatted = formatter.format(date);
  console.log(formatted);
});

Utilisez la locale du navigateur de l'utilisateur lorsque c'est possible en omettant le paramètre de locale. Cela respecte les préférences de l'utilisateur.

const formatter = new Intl.DateTimeFormat();
// Utilise automatiquement la locale du navigateur

Fournissez des locales de repli lorsque vous ciblez des régions spécifiques. Si la locale préférée n'est pas disponible, le navigateur utilise l'option suivante.

const formatter = new Intl.DateTimeFormat(["fr-CA", "fr", "en"]);
// Préfère le français (Canada), se replie sur le français, puis l'anglais

Utilisez des raccourcis de style pour les affichages courants de date et d'heure. Ils s'adaptent automatiquement aux conventions de locale et nécessitent moins de configuration.

const formatter = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short"
});

Utilisez les options de composants lorsque vous avez besoin d'un contrôle précis sur le format de sortie.

const formatter = new Intl.DateTimeFormat("en-US", {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric"
});

Spécifiez toujours le fuseau horaire lors de l'affichage des heures pour les utilisateurs distants ou pour les événements programmés. Sans fuseau horaire, les dates sont formatées dans le fuseau horaire local de l'utilisateur, ce qui peut ne pas correspondre à votre intention.

const formatter = new Intl.DateTimeFormat("en-US", {
  timeZone: "America/New_York",
  dateStyle: "full",
  timeStyle: "long"
});

Utilisez formatRange() pour les plages de dates au lieu de formater chaque date séparément et de les concaténer. La méthode gère l'omission intelligente des informations redondantes.

// Moins clair
const startFormatted = formatter.format(start);
const endFormatted = formatter.format(end);
const range = `${startFormatted} to ${endFormatted}`;

// Meilleur
const range = formatter.formatRange(start, end);

Vérifiez la compatibilité des navigateurs pour les fonctionnalités avancées comme dayPeriod, fractionalSecondDigits, et certaines valeurs de timeZoneName. Tous les navigateurs modernes prennent en charge les fonctionnalités de base, mais les options plus récentes peuvent nécessiter des solutions de repli pour les navigateurs plus anciens.