L'objet Intl.DateTimeFormat
est un constructeur d'objets permettant de formatter des dates et des heures selon une langue.
Le code source de cet exemple interactif est disponible dans un dépôt GitHub. Si vous souhaitez contribuez à ces exemples, n'hésitez pas à cloner https://github.com/mdn/interactive-examples et à envoyer une pull request !
Syntaxe
new Intl.DateTimeFormat([locales[, options]]) Intl.DateTimeFormat.call(this[, locales[, options]])
Paramètres
locales
Facultatif-
Ce paramètre optionnel est une chaine de caractères avec un identifiant de langue BCP 47, ou un tableau de ce type de chaine de caractères. Pour utiliser la locale par défaut du navigateur, on pourra omettre cet argument (ou passer la valeur
undefined
). Pour le format général et l'interprétation de l'argumentlocales
, voir la pageIntl
. Les clefs d'extensions Unicode suivantes sont autorisées :- nu
- Système de numérotation. Les valeurs possibles incluent :
"arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt"
. - ca
- Calendrier. Les valeurs possibles incluent :
"buddhist", "chinese", "coptic", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc"
. hc
- Le type de cycle horaire à utiliser. Les valeurs possibles sont
"h11"
,"h12"
,"h23"
,"h24"
.
options
-
Un objet avec certaines ou toutes les propriétés suivantes :
localeMatcher
- L'algorithme de correspondance à utiliser pour la locale. Les valeurs possibles sont
"lookup"
et"best fit"
; le défaut est"best fit"
. Pour des informations sur cette option, voir la pageIntl
timeZone
- Le fuseau horaire à utiliser. La seule valeur que doivent reconnaitre les implémentations est "UTC" ; la valeur par défaut est le fuseau horaire du moteur JavaScript. Les implémentations peuvent aussi reconnaitre les noms de fuseau horaire de la base de données IANA de fuseaux horaires, tel que
"Asia/Shanghai"
,"Asia/Kolkata"
,"America/New_York"
. hour12
- S'il faut utiliser le format horaire sur 12 heures (au lieu de celui-ci sur 24 heures). Les valeurs possibles sont
true
etfalse
; la valeur par défaut dépend de la locale. Cette option surcharge l'étiquettehc
et/ou l'optionhourCycle
. hourCycle
- Le cycle horaire à utiliser. Les valeurs possibles sont
"h11"
,"h12"
,"h23"
,"h24"
. Cette option surcharge l'étiquettehc
mais sera remplacée parhour12
si cette dernière est présente. formatMatcher
- L'algorithme de correspondance à utiliser pour le formattage. Les valeurs possibles sont
"basic"
et"best fit"
; par défaut"best fit"
. Voir les paragraphes suivants pour des informations concernant l'usage de cette propriété.
Les propriétés suivantes décrivent les composants date-heure à utiliser pour le formattage de la sortie. Les implémentations ont pour obligation de supporter au minimum les 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 implémentations peuvent supporter d'autres sous-ensembles, et les demandes seront évaluées face à toutes les combinaisons de sous-ensembles disponibles pour trouver la meilleure correspondance. Deux algorithmes sont disponibles pour cette évaluation et choisis par la propriété
formatMatcher
: un algorithme "basic" complètement spécifié et un algorithme"best fit"
dépendant de l'implémentation.weekday
- La représentation du jour de la semaine. Les valeurs possibles sont :
"long"
(par exempleThursday
)"short"
(par exempleThu
)"narrow"
(par exempleT
). Deux jours de la semaines pourront partager la même représentation dans certaines locales (par exemple, en anglaisTuesday
sera également représenté avecT
en notation étroite).
era
- La représentation de l'ère. Les valeurs possibles sont :
"long"
(par exempleAnno Domini
)"short"
(par exempleAD
)"narrow"
(par exempleA
)
year
- La représentation de l'année. Les valeurs possibles sont :
"numeric"
(par exemple2012
)"2-digit"
(par exemple12
)
month
- La représentation du mois. Les valeurs possibles sont :
"numeric"
(par exemple2
)"2-digit"
(par exemple02
)"long"
(par exempleMarch
)"short"
(par exempleMar
)"narrow"
(par exempleM
). Dans certaines locales, deux mois pourront partager la même représentation avec le style étroit (par exemple,May
en anglais, sera également représenté avecM
).
day
- La représentation du jour. Les valeurs possibles sont :
"numeric"
(par exemple1
)"2-digit"
(par exemple01
)
hour
- La représentation de l'heure. Les valeurs possibles sont :
"numeric"
(par exemple1
)"2-digit"
(par exemple01
)
minute
- La représentation des minutes. Les valeurs possibles sont :
"numeric"
(par exemple1
)"2-digit"
(par exemple01
)
second
- La représentation des secondes. Les valeurs possibles sont :
"numeric"
(par exemple1
)"2-digit"
(par exemple01
)
timeZoneName
- La représentation du fuseau horaire. Les valeurs possibles sont :
"long"
(par exempleBritish Summer Time
)"short"
(par exempleGMT+1
)
La valeur par défaut pour chaque composante est
undefined
, mais si toutes les composantes valentundefined
, alorsyear
,month
, etday
seront considérés comme"numeric"
.
Description
Propriétés
Intl.DateTimeFormat.prototype
- Permet l'ajout de propriétés à tous les objets.
Méthodes
Intl.DateTimeFormat.supportedLocalesOf()
- Renvoie un tableau contenant les locales supportées parmis les locales fournies, sans qu'il soit nécessaire de recourir à la locale par défaut de l'implémentation.
Instances de DateTimeFormat
Propriétés
Les instances de DateTimeFormat()
héritent des propriétés suivantes depuis leur prototype :
Méthodes
Les instances de DateTimeFormat()
héritent des propriétés suivantes depuis leur prototype :
Intl.DateTimeFormat.prototype.format
- Un accesseur qui renvoie une fonction formattant une date selon les options de format et de locale spécifiées pour l'objet
DateTimeFormat
. Intl.DateTimeFormat.prototype.formatToParts()
- Renvoie un tableau d'objets qui représentent les composants de la date sous forme de chaînes de caractères afin que celles-ci puissent être utilisée dans une mise en forme adaptée à la locale.
Intl.DateTimeFormat.prototype.resolvedOptions()
- Renvoie un nouvel objet dont les propriétés indiquent les options de format et de locale calculées lors de l'initialisation de l'objet.
Exemples
Utiliser DateTimeFormat()
Dans une utilisation basique sans préciser de locale, DateTimeFormat()
utilise la locale et les options par défaut
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)); // DateTimeFormat sans arguments dépend de l'implémentation, // la locale par défaut, et le fuseau horaire par défaut console.log(new Intl.DateTimeFormat().format(date)); // → "20/12/2012" avec une locale fr-Fr et un fuseau horaire CEST
Utiliser locales
Cet exemple montre quelques variations de formattage pour les dates et les heures localisées. Afin d'obtenir le langage utilisé au sein de l'interface utilisateur de votre application, vérifiez de bien fournir ce langage (et éventuellement des locales de recours) en utilisant l'argument locales
:
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// les formats qui suivent se basent sur le
// fuseau horaire CEST
// l'anglais américain utilise l'ordre mois-jour-année
console.log(new Intl.DateTimeFormat("en-US").format(date));
// → "12/20/2012"
// l'anglais britannique utilise l'ordre jour-mois-année
console.log(new Intl.DateTimeFormat("en-GB").format(date));
// → "20/12/2012"
// le coréen utilise l'ordre année-mois-jour
console.log(new Intl.DateTimeFormat("ko-KR").format(date));
// → "2012. 12. 20."
// l'arabe, dans la plupart des pays arabophones, utilise les chiffres arabes
console.log(new Intl.DateTimeFormat("ar-EG").format(date));
// → "٢٠/١٢/٢٠١٢"
// en ce qui concerne le japonais, les applications peuvent
// souhaiter utiliser le calendrier japonais
// pour lequel 2012 était l'année 24 de l'ère Heisei
console.log(new Intl.DateTimeFormat("ja-JP-u-ca-japanese").format(date));
// → "24/12/20"
// quand un langage non support est demandé (ex : le balinais)
// il est possible de fournir un langage de recours (ici l'indonésien)
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// → "20/12/2012"
Utiliser options
Les formats de la date et de l'heure peuvent être personnalisés en utilisant l'argument options
:
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)); // fournir le jour de la semaine avec une date longue var options = {weekday: "long", year: "numeric", month: "long", day: "numeric"}; console.log(new Intl.DateTimeFormat("de-DE", options).format(date)); // → "Donnerstag, 20. Dezember 2012" // une application peut vouloir utiliser UTC et le rendre visible options.timeZone = "UTC"; options.timeZoneName = "short"; console.log(new Intl.DateTimeFormat("en-US", options).format(date)); // → "Thursday, December 20, 2012, GMT" // parfois, vous voulez être précis options = {hour: "numeric", minute: "numeric", second: "numeric", timeZoneName: "short"}; console.log(new Intl.DateTimeFormat("en-AU", options).format(date)); // → "2:00:00 pm AEDT" // parfois, même les USA ont besoin d'afficher une heure sur 24h options = {year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric", second: "numeric", hour12: false}; console.log(new Intl.DateTimeFormat("en-US", options)); // → "12/19/2012, 19:00:00" // pour utiliser la locale par défaut du navigateur : console.log(new Intl.DateTimeFormat('default', options).format(date)); // → "12/19/2012, 19:00:00" (peut varier selon la locale du navigateur)
Spécifications
Compatibilité des navigateurs
Ordinateur | Mobile | Serveur | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
DateTimeFormat | Chrome Support complet 24 | Edge Support complet 12 | Firefox Support complet 29 | IE Support complet 11 | Opera Support complet 15 | Safari Support complet 10 | WebView Android Support complet 4.4 | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android Support complet 14 | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs Support complet Oui |
dateStyle | Chrome Support complet 76 | Edge Aucun support Non | Firefox Aucun support Non | IE Aucun support Non | Opera Support complet 63 | Safari ? | WebView Android Support complet 76 | Chrome Android Support complet 76 | Firefox Android Aucun support Non | Opera Android Aucun support Non | Safari iOS ? | Samsung Internet Android Aucun support Non | nodejs Support complet Oui |
format | Chrome Support complet 24 | Edge Support complet 12 | Firefox Support complet 29 | IE Support complet 11 | Opera Support complet 15 | Safari Support complet 10 | WebView Android Aucun support Non | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android ? | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs ? |
formatRange | Chrome Support complet 76 | Edge Aucun support Non | Firefox Aucun support Non | IE Aucun support Non | Opera Aucun support Non | Safari Aucun support Non | WebView Android Support complet 76 | Chrome Android Support complet 76 | Firefox Android Aucun support Non | Opera Android Aucun support Non | Safari iOS Aucun support Non | Samsung Internet Android Aucun support Non | nodejs Aucun support Non |
formatRangeToParts | Chrome Support complet 76 | Edge Aucun support Non | Firefox Aucun support Non | IE Aucun support Non | Opera Aucun support Non | Safari Aucun support Non | WebView Android Support complet 76 | Chrome Android Support complet 76 | Firefox Android Aucun support Non | Opera Android Aucun support Non | Safari iOS Aucun support Non | Samsung Internet Android Aucun support Non | nodejs Aucun support Non |
formatToParts | Chrome
Support complet
57
| Edge Support complet 18 | Firefox Support complet 51 | IE Aucun support Non | Opera Support complet Oui | Safari Support complet 11 | WebView Android
Support complet
57
| Chrome Android
Support complet
57
| Firefox Android Support complet 56 | Opera Android Aucun support Non | Safari iOS Support complet 11 | Samsung Internet Android
Support complet
7.0
| nodejs Support complet Oui |
hourCycle | Chrome Support complet 73 | Edge Support complet 18 | Firefox Support complet 58 | IE Aucun support Non | Opera Support complet 60 | Safari ? | WebView Android Support complet 73 | Chrome Android Support complet 73 | Firefox Android Support complet 58 | Opera Android Support complet 52 | Safari iOS ? | Samsung Internet Android Aucun support Non | nodejs ? |
IANA time zone names in timeZone option | Chrome Support complet 24 | Edge Support complet 14 | Firefox Support complet 52 | IE Aucun support Non | Opera Support complet 15 | Safari Support complet 10 | WebView Android Support complet 37 | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android ? | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs ? |
prototype | Chrome Support complet 24 | Edge Support complet 12 | Firefox Support complet 29 | IE Support complet 11 | Opera Support complet 15 | Safari Support complet 10 | WebView Android Aucun support Non | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android ? | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs ? |
resolvedOptions | Chrome Support complet 24 | Edge Support complet 12 | Firefox Support complet 29 | IE Support complet 11 | Opera Support complet 15 | Safari Support complet 10 | WebView Android Aucun support Non | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android ? | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs ? |
supportedLocalesOf | Chrome Support complet 24 | Edge Support complet 12 | Firefox Support complet 29 | IE Support complet 11 | Opera Support complet 15 | Safari Support complet 10 | WebView Android Aucun support Non | Chrome Android Support complet 26 | Firefox Android Support complet 56 | Opera Android ? | Safari iOS Support complet 10 | Samsung Internet Android Support complet 1.5 | nodejs ? |
timeStyle | Chrome Support complet 76 | Edge Aucun support Non | Firefox Aucun support Non | IE Aucun support Non | Opera Support complet 63 | Safari ? | WebView Android Support complet 76 | Chrome Android Support complet 76 | Firefox Android Aucun support Non | Opera Android Aucun support Non | Safari iOS ? | Samsung Internet Android Aucun support Non | nodejs Support complet Oui |
Légende
- Support complet
- Support complet
- Aucun support
- Aucun support
- Compatibilité inconnue
- Compatibilité inconnue
- Voir les notes d'implémentation.
- Voir les notes d'implémentation.
Voir aussi
- Introduction : 'The ECMAScript Internationalisation API
- Constructeurs
- Méthodes