mozilla
Vos résultats de recherche

    Date.prototype.toLocaleDateString()

    Résumé

    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é.

    locales

    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 page Intl. 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".
    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 page Intl
    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 et false ; la valeur par défaut dépend de la locale.
    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 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 ».

    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 Statut Commentaires
    Troisième édition d'ECMAScript. 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 6 (ECMA-262)
    La définition de 'Date.prototype.toLocaleDateString' dans cette spécification.
    Draft  
    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.

    Compatibilité des navigateurs

    Fonctionnalité Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Support simple (Oui) (Oui) (Oui) (Oui) (Oui)
    arguments locales et options 24 + supporte d'autres fuseaux qu'UTC 29 (29) 11 15 Pas de support
    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

    Voir aussi

    Étiquettes et contributeurs liés au document

    Contributors to this page: tregagnon, teoli, SphinxKnight
    Dernière mise à jour par : SphinxKnight,
    Masquer la barre latérale