Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

Date.prototype.toLocaleDateString()

La méthode toLocaleDateString() renvoie une chaine de caractères correspondant à la date (le fragment de l'objet qui correspond à la date : jour, mois, année) exprimée selon une locale. Les arguments locales et options permettent aux applications de définir le langage utilisé 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.

Syntaxe

dateObj.toLocaleDateString([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é.

La valeur par défaut de chacun des composants de la date vaut undefined, si les propriétés weekday, year, month, day sont toutes undefined, on suppose alors que year, month, et day sont « numériques ».

Valeur de retour

Une chaîne de caractères qui représente le jour de la date indiquée selon des options de locales.

Exemples

Utiliser toLocaleDateString()

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(2012, 11, 12, 3, 0, 0));

// toLocaleDateString() sans argument, on utilise donc 
// les valeurs par défaut (de l'implémentation) 
// pour la locale, et le fuseau horaire
date.toLocaleDateString();
// → "12/12/2012" 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 RangeError :

function toLocaleDateStringSupportsLocales() {
    try {
        new Date().toLocaleDateString("i");
    } catch (e) {
        return e​.name === "RangeError";
    }
    return false;
}

Utiliser l'argument 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
alert(date.toLocaleDateString("en-US"));
// → "12/20/2012"

// l'anglais britannique utilise l'ordre jour-mois-année
alert(date.toLocaleDateString("en-GB"));
// → "20/12/2012"

// le coréen utilise l'ordre année-mois-jour
alert(date.toLocaleDateString("ko-KR"));
// → "2012. 12. 20."

// l'arabe, dans la plupart des pays arabophones, utilise les chiffres arabes
alert(date.toLocaleDateString("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
alert(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// → "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)
alert(date.toLocaleDateString(["ban", "id"]));
// → "20/12/2012"

Utiliser l'argument options

Les résultats fournis par toLocaleDateString() peuvent être personnalisés grâce à l'argument options :

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

// fournir le jour de la semaine avec une date longe
var options = {weekday: "long", year: "numeric", month: "long", day: "numeric"};
alert(date.toLocaleDateString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"

// une application peut vouloir utiliser
// UTC et l'afficher
options.timeZone = "UTC";
options.timeZoneName = "short";
alert(date.toLocaleDateString("en-US", options));
// → "Thursday, December 20, 2012, GMT"

Performance

Lorsque des grands nombres ou de grandes dates sont formatés, il est préférable de créer un objet Intl.DateTimeFormat et d'utiliser la fonction fournie par sa propriété format.

Spécifications

Spécification État Commentaires
ECMAScript 3rd 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.toLocaleDateString' dans cette spécification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Date.prototype.toLocaleDateString' dans cette spécification.
Standard  
ECMAScript 2017 Draft (ECMA-262)
La définition de 'Date.prototype.toLocaleDateString' dans cette spécification.
Projet  
ECMAScript Internationalization API 1.0 (ECMA-402)
La définition de 'Date.prototype.toLocaleDateString' 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.toLocaleDateString' dans cette spécification.
Standard  
ECMAScript Internationalization API 4.0 (ECMA-402)
La définition de 'Date.prototype.toLocaleDateString' dans cette spécification.
Projet  

Compatibilité des navigateurs

Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
Support simple (Oui) (Oui) (Oui) (Oui) (Oui)
arguments locales et options 24 [1] 29 (29) 11 15 Nightly build[2]
Fonctionnaltié Android Chrome pour Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Support simple (Oui) (Oui) (Oui) (Oui) (Oui) (Oui)
arguments locales et options Pas de support 26 Pas de support
bug 864843
Pas de support Pas de support Pas de support

[1] Chrome 24 et les versions ultérieures supportent également d'autres fuseaux horaires qu'UTC.

[2] Voir le bug WebKit 147612.

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : SphinxKnight, teoli, tregagnon
 Dernière mise à jour par : SphinxKnight,