API Intl.DateTimeFormat

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

Introduction

Les dates s'affichent différemment dans 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 majeure partie du monde utilise le format 24 heures.

Construire une logique de formatage de dates manuelle 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 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, éventuellement suivi d'un code de région.

Modèles de locale courants :

"en"      // English (generic)
"en-US"   // English (United States)
"en-GB"   // English (United Kingdom)
"es"      // Spanish (generic)
"es-MX"   // Spanish (Mexico)
"es-ES"   // Spanish (Spain)
"zh-CN"   // Chinese (China, Simplified)
"zh-TW"   // Chinese (Taiwan, Traditional)

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);
// Output varies based on user's browser locale

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"]);
// Uses Spanish (Mexico) if available, falls back to generic Spanish, then English

Aperçu des options de formatage

Le constructeur Intl.DateTimeFormat accepte un objet d'options qui contrôle ce qui apparaît dans la sortie formatée. Il existe deux approches de 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 offrent 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, l'ordre mois-jour, et l'heure au format 12 heures avec AM/PM. Mêmes options, résultat différent selon la locale.

Options de composants

Les options de composants offrent un contrôle précis sur ce qui est affiché 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 en fonction des conventions locales.

Formatage de l'heure

Les options de composants temporels 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 de l'heure au 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 l'heure au 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 12 heures.

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

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 vers des fuseaux horaires spécifiques.

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

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 instant 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 en différents systèmes de calendrier. Les calendriers disponibles incluent 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 scripts.

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 incluent latn (chiffres occidentaux), arab (chiffres arabo-indiens), arabext (chiffres arabo-indiens é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 avec omission intelligente des 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 s'affichent.

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 s'affichent.

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 s'affiche une seule fois car les deux heures 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() fournit 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 de 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 a un léger coût en termes de performances.

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

// More efficient
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();
// Uses browser locale automatically

Fournissez des locales de secours 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"]);
// Prefers French (Canada), falls back to French, then English

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

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

Utilisez les options de composant 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 d'heures pour des utilisateurs distants ou pour des événements planifié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.

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

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

Vérifiez la compatibilité du navigateur pour les fonctionnalités avancées comme dayPeriod, fractionalSecondDigits et certaines valeurs 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 secours pour les navigateurs plus anciens.