La méthode toLocaleString()
renvoie une chaine de caractères représentant la date selon une locale. Les arguments locales
et options
permettent aux applications de définir le langage à utiliser pour les conventions de format et permettent de personnaliser le comportement de la fonction. Les anciennes implémentations ignorent ces arguments, la locale utilisée et le format de la chaine dépendent uniquement de l'implémentation.
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
dateObj.toLocaleString([locales [, options]])
Paramètres
Voir le tableau de compatibilité des navigateurs afin de déterminer quels navigateurs respectent les arguments locales
et options
ainsi que l'exemple Vérifier le support des arguments locales
et options
qui permet de détecter cette fonctionnalité.
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 le format général et l'interprétation de l'argument
locales
, 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", "ethioaa", "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
"narrow", "short", "long"
. era
- La représentation d'une ère. Les valeur possibles sont
"narrow", "short", "long"
. year
- La représentation d'une année. Les valeur possibles sont
"numeric", "2-digit"
. month
- La représentation d'un mois. Les valeur possibles sont
"numeric", "2-digit", "narrow", "short", "long"
. day
- La représentation d'une journée. Les valeur possibles sont
"numeric", "2-digit"
. hour
- La représentation d'une heure. Les valeur possibles sont
"numeric", "2-digit"
. minute
- La représentation d'une minute. Les valeur possibles sont
"numeric", "2-digit"
. second
- La représentation d'une seconde. Les valeur possibles sont
"numeric", "2-digit"
. timeZoneName
- La représentation du nom d'un fuseau horaire. Les valeur possibles sont
"short", "long"
.
La valeur par défaut de chacun des composants de la date-heure vaut undefined
, mais si les propriétés weekday
, year
, month
, day
, hour
, minute
, second
sont toutes undefined
, alors weekday
, year
, month
, day
, hour
, minute
et second
sont supposés être "numeric".
Valeur de retour
Une chaîne de caractères représentant la date indiquée selon des conventions de locales spécifiques.
Exemples
Utiliser toLocaleString()
Voici un usage simple qui ne définit pas de locale : une chaine de caractères dans une locale et avec des options par défaut est renvoyée.
var date = new Date(Date.UTC(2014, 11, 21, 3, 0, 0)); // toLocaleString() sans argument, on utilise donc // les valeurs par défaut (de l'implémentation) // pour la locale, et le fuseau horaire date.toLocaleString(); // → "21/12/2014 04:00:00" si exécuté dans une locale fr et le fuseau horaire CEST
Vérifier le support des arguments locales
et options
Les arguments locales
et options
ne sont pas encore supportés par tous les navigateurs. Afin de vérifier si l'implementation utilisée les supporte, vous pouvez utiliser le pré-requis suivant : les locales incorrectes sont rejetées avec une exception RangeEr
function toLocaleStringSupportsLocales() { try { new Date().toLocaleString("i"); } catch (e) { return e instanceof RangeError; } return false; }
Utiliser locales
Cet exemple montre quelques variations dues aux formats de dates localisés. 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(date.toLocaleString("en-US")); // → "12/20/2012, 4:00:00 AM" // l'anglais britannique utilise l'ordre jour-mois-année console.log(date.toLocaleString("en-GB")); // → "20/12/2012 04:00:00" // le coréen utilise l'ordre année-mois-jour console.log(date.toLocaleString("ko-KR")); // → "2012. 12. 20. 오전 4:00:00" // l'arabe, dans la plupart des pays arabophones, utilise les chiffres arabes console.log(date.toLocaleString("ar-EG")); // → "٢٠/١٢/٢٠١٢ ٤:٠٠:٠٠ ص" // 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(date.toLocaleString("ja-JP-u-ca-japanese")); // → "24/12/20 4:00:00" // 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(date.toLocaleString(["ban", "id"])); // → "20/12/2012 04.00.00"
Utiliser options
Les résultats fournis par toLocaleString()
peuvent être personnalisés grâce à l'argument options
:
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0)); // obtenir le jour de la semaine avec une date longue var options = {weekday: "long", year: "numeric", month: "long", day: "numeric"}; console.log(date.toLocaleString("de-DE", options)); // → "Donnerstag, 20. Dezember 2012" // une application peut vouloir utiliser UTC et le rendre visible options.timeZone = "UTC"; options.timeZoneName = "short"; console.log(date.toLocaleString("en-US", options)); // → "Thursday, December 20, 2012, GMT" // parfois, même les USA ont besoin d'avoir une heure sur 24h console.log(date.toLocaleString("en-US", {hour12: false})); // → "12/19/2012, 19:00:00"
Comparaison des dates formatées et des valeurs statiques
La plupart du temps, le format renvoyé par toLocaleString()
est cohérent. Toutefois, cela peut évoluer à l'avenir et n'est pas garanti pour l'ensemble des langues (de telles variations sont souhaitables et permises par la spécification). Ainsi, IE et Edge ajoutent des caractères de contrôle bidirectionnels autour des dates afin que le texte produit ait une directionalité cohérente avec le texte avec lequel elles seront concaténées.
Aussi, mieux vaut ne pas comparer un résultat fourni par format()
avec une valeur statique :
"1.1.2019, 01:00:00" === new Date("2019-01-01T00:00:00.000000Z").toLocaleString(); // true pour Firefox et les autres // false pour IE et Edge
Note : Voir aussi ce fil StackOverflow pour plus de détails et d'exemples.
Performance
Quand vous formatez d'importants volumes de dates, il est préférable de créer un objet Intl.DateTimeFormat
et d'utiliser la fonction fournie via la propriété format
.
Spécifications
Spécification | État | Commentaires |
---|---|---|
ECMAScript 1st Edition (ECMA-262) | Standard | Définition initiale. Implémentée avec JavaScript 1.0. |
ECMAScript 5.1 (ECMA-262) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Standard | |
ECMAScript 2015 (6th Edition, ECMA-262) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Standard | |
ECMAScript Latest Draft (ECMA-262) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Projet | |
ECMAScript Internationalization API 1.0 (ECMA-402) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Standard | Définition des arguments locales et options . |
ECMAScript Internationalization API 2.0 (ECMA-402) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Standard | |
ECMAScript Internationalization API 4.0 (ECMA-402) La définition de 'Date.prototype.toLocaleString' dans cette spécification. |
Projet |
Compatibilité des navigateurs
Les données de compatibilité de cette page ont été générées à partir de données structurées. Si vous souhaitez contribuer à ces données, n'hésitez pas à envoyer unepull request sur https://github.com/mdn/browser-compat-data.
Ordinateur | Mobile | Serveur | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Support simple | Chrome Support complet Oui | Edge Support complet Oui | Firefox Support complet 1 | IE Support complet Oui | Opera Support complet Oui | Safari Support complet Oui | WebView Android Support complet Oui | Chrome Android Support complet Oui | Edge Mobile Support complet Oui | Firefox Android Support complet 4 | Opera Android Support complet Oui | Safari iOS Support complet Oui | Samsung Internet Android Support complet Oui | nodejs ? |
locales | Chrome Support complet 24 | Edge ? | 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 | Edge Mobile ? | Firefox Android Support complet 56 | Opera Android Aucun support Non | Safari iOS Support complet 10 | Samsung Internet Android Support complet Oui | nodejs ? |
options | Chrome Support complet 24 | Edge ? | 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 | Edge Mobile ? | Firefox Android Support complet 56 | Opera Android Aucun support Non | Safari iOS Support complet 10 | Samsung Internet Android Support complet Oui | nodejs ? |
IANA time zone names in timeZone option | Chrome Support complet 24 | Edge ? | Firefox Support complet 52 | IE ? | Opera ? | Safari ? | WebView Android ? | Chrome Android ? | Edge Mobile ? | Firefox Android Aucun support Non | Opera Android ? | Safari iOS ? | Samsung Internet Android ? | nodejs ? |
Légende
- Support complet
- Support complet
- Aucun support
- Aucun support
- Compatibilité inconnue
- Compatibilité inconnue