Constructeur Intl.DateTimeFormat()

locales Facultatif

Une chaîne de caractères représentant une balise de langue BCP 47 ou un tableau de telles balises. Pour la forme générale et l'interprétation de cet argument, voir la page Intl. Les clés d'extension Unicode suivantes sont autorisées :

nu

Le système de numération à utiliser. Les valeurs possibles sont : "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".

ca

Le calendrier à utiliser. Les valeurs possibles sont : "buddhist", "chinese", "coptic", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc".

hc

Le cycle horaire à utiliser. Les valeurs possibles sont : "h11", "h12", "h23", "h24".

options Facultatif

Un objet avec une ou plusieurs propriétés parmi les suivantes :

dateStyle

Le style de formatage pour la date à utiliser avec format(). Les valeurs possibles sont :

• "full"
• "long"
• "medium"
• "short"

Note : dateStyle peut être utilisée avec timeStyle, mais pas avec les autres options (comme weekday, hour, month, etc.).

timeStyle

Le style de formatage des heures à utiliser avec format(). Les valeurs possibles sont :

• "full"
• "long"
• "medium"
• "short"

Note : timeStyle peut être utilisée avec dateStyle, mais pas avec les autres options (comme weekday, hour, month, etc.).

calendar

Le calendrier à utiliser. Les valeurs possibles sont : "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc".

dayPeriod

Le style de formatage à utiliser pour les périodes du jour comme « dans la matinée », « à midi », etc. Les valeurs possibles sont : "narrow", "short", " long".

Note : Cette option applique un effet uniquement si une horloge sur 12 heures est utilisée. De nombreuses locales utilisent la même chaîne de caractères quelle que soit la longueur indiquée.

numberingSystem

Le système de numération à utiliser. Les valeurs possibles sont : "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".

localeMatcher

L'algorithme de correspondance des locales à utiliser. Les valeurs possibles sont "lookup" et "best fit" ; la valeur par défaut est "best fit". Pour plus d'information, voir la page Intl.

timeZone

Le fuseau horaire à utiliser. La seule valeur que doivent nécessairement reconnaître les implémentations est "UTC". La valeur par défaut est le fuseau horaire de l'environnement d'exécution. Les implémentations peuvent également reconnaître les noms de fuseaux horaires tels que décrits dans la base de données des fuseaux horaires IANA, comme "Asia/Shanghai", "Asia/Kolkata", "America/New_York".

hour12

Indique si l'heure est exprimée sur 12 heures plutôt que sur 24. Les valeurs possibles sont true et false ; la valeur par défaut dépend de la locale. Cette option surcharge la clé d'extension hc et/ou l'option hourCycle.

hourCycle

Le cycle horaire à utiliser. Les valeurs possibles sont : "h11", "h12", "h23", or "h24". Cette option prévaut sur la clé d'extension hc. L'option hour12 aura la priorité sur cette option si les deux sont utilisées.

formatMatcher

L'algorithme de correspondance des formats à utiliser. Les valeurs possibles sont "basic" et "best fit" ; la valeur par défaut est "best fit". Voir les paragraphes suivants à propos de l'utilisation de cette propriété.

Les propriétés suivantes décrivent les composantes d'horodatage qui peuvent être utilisées pour le format de production ainsi que leurs différentes représentations. Les implémentations doivent au moins prendre en charge les sous-ensembles suivants :

• weekday, year, month, day, hour, minute, second
• weekday, year, month, day
• year, month, day
• year, month
• month, day
• hour, minute, second
• hour, minute

Les moteurs peuvent prendre en charge d'autres sous-ensembles et la recherche de la meilleure correspondance aura lieu parmi toutes les combinaisons disponibles. Deux algorithmes sont disponibles pour cette recherche et la propriété formatMatcher permet de choisir l'un ou l'autre : un algorithme explicitement spécifié, "basic" et un algorithme laissé à l'implémentation : "best fit".

weekday

La représentation du jour de la semaine. Les valeurs possibles sont :

• "long" (par exemple, mardi)
• "short" (par exemple, mar)
• "narrow" (par exemple, m). Deux jours différents de la semaine peuvent avoir la même représentation avec ce style.

era

La représentation d'une ère. Les valeurs possibles sont :

• "long" (par exemple, Anno Domini)
• "short" (par exemple, AD)
• "narrow" (par exemple, A)

year

La représentation de l'année. Les valeurs possibles sont :

• "numeric" (par exemple, 2012)
• "2-digit" (par exemple, 12)

month

La représentation du mois. Les valeurs possibles sont :

• "numeric" (par exemple, 3)
• "2-digit" (par exemple, 03)
• "long" (par exemple, mars)
• "short" (par exemple, mar)
• "narrow" (par exemple, m). Deux mois différents peuvent avoir la même représentation avec ce style.

day

La représentation du jour. Les valeurs possibles sont :

• "numeric" (par exemple, 1)
• "2-digit" (par exemple, 01)

hour

La représentation de l'heure. Les valeurs possibles sont : "numeric", "2-digit".

minute

La représentation des minutes. Les valeurs possibles sont : "numeric", "2-digit".

second

La représentation des secondes. Les valeurs possibles sont : "numeric", "2-digit".

fractionalSecondDigits

Le nombre de chiffres à utiliser pour représenter la partie décimale des secondes (tout chiffre supplémentaire sera tronqué). Les valeurs possibles sont :

• 0 (la partie décimale est tronquée)
• 1
• 2
• 3

timeZoneName

La représentation localisée du nom du fuseau horaire. Les valeurs possibles sont :

• "long" pour le format long (par exemple, Pacific Standard Time, Nordamerikanische Westküsten-Normalzeit)
• "short" pour la forme courte localisée (par exemple, PST, GMT-8)
• "shortOffset" pour la forme courte GMT localisée (par exemple, GMT-8)
• "longOffset" pour la forme longue GMT localisée (par exemple, GMT-0800)
• "shortGeneric" pour la forme courte générique non-localisée (par exemple, PT, Los Angeles Zeit).
• "longGeneric" pour la forme longue générique non-localisée (par exemple, Pacific Time, Nordamerikanische Westküstenzeit)

Note : L'affichage du fuseau horaire pourra basculer sur un autre format si la chaîne de caractères nécessaire n'est pas disponible. Ainsi, les formats non-localisés devraient afficher le fuseau horaire sans indication de pays ou de ville, à la manière de "Pacific Time". Si ce n'est pas possible, le moteur pourra utiliser un nom de fuseau horaire localisé comme "Los Angeles Time".

La valeur par défaut pour chaque composante de l'horodatage est undefined, et si toutes les propriétés valent undefined, ce sera la valeur "numeric" qui sera utilisée pour year, month, et day.

Voici une utilisation simple du constructeur sans indiquer de locale. DateTimeFormat utilise alors la locale par défaut et les options par défaut.

let date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

console.log(new Intl.DateTimeFormat().format(date));
// → "20/12/2012" si exécuté sur un environnement avec la locale en fr-FR et sur le fuseau horaire (UTC+0100)

On utilise l'option dayPeriod pour produire une chaîne de caractères qui indique le moment de la journée (« dans la matinée », « pendant la nuit », etc.). On notera que cela fonctionne uniquement avec un formatage utilisant une horloge sur 12 heures (hourCycle: 'h12') et que pour de nombreuses locales, les chaînes obtenues sont les mêmes quelle que soit la valeur utilisée pour dayPeriod.

let date = Date.UTC(2012, 11, 17, 4, 0, 42);

console.log(
  new Intl.DateTimeFormat("en-GB", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "short",
    timeZone: "UTC",
  }).format(date),
);
// > 4 at night"  (même formatage pour en-GB quelle que soit la valeur de dayPeriod)

console.log(
  new Intl.DateTimeFormat("fr", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "narrow",
    timeZone: "UTC",
  }).format(date),
);
// > "4 mat."  (même formatage pour fr avec narrow ou short)

console.log(
  new Intl.DateTimeFormat("fr", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "long",
    timeZone: "UTC",
  }).format(date),
);
// > "4 du matin"

On utilise l'option timeZoneName pour produire une chaîne de caractères représentant le fuseau horaire ("GMT", "Pacific Time", etc.).

var date = Date.UTC(2021, 11, 17, 3, 0, 42);
const timezoneNames = [
  "short",
  "long",
  "shortOffset",
  "longOffset",
  "shortGeneric",
  "longGeneric",
];

for (const zoneName of timezoneNames) {
  var formatter = new Intl.DateTimeFormat("fr", {
    timeZone: "Europe/Paris",
    timeZoneName: zoneName,
  });
  console.log(zoneName + " : " + formatter.format(date));
}

// Résultat attendu :
// short : 17/12/2021, UTC+1
// long : 17/12/2021, heure normale d'Europe centrale
// shortOffset : 17/12/2021, UTC+1
// longOffset : 17/12/2021, UTC+01:00
// shortGeneric : 17/12/2021, heure : France
// longGeneric : 17/12/2021, heure d'Europe centrale

• Intl.DateTimeFormat
• Intl.supportedValuesOf()
• Intl