Date.prototype.toLocaleTimeString()

La méthode toLocaleTimeString() renvoie une chaine de caractères correspondant à l'heure dans la date, 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.toLocaleTimeString([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 hour, minute, second sont toutes undefined, on suppose alors que hour, minute, et second sont "numeric".

Valeur de retour

Une chaîne de caractères qui représente l'heure de la date indiquée selon des conventions de locales spécifiques.

Exemples

Utiliser toLocaleTimeString()

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));

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

function toLocaleTimeStringSupportsLocales() {
    try {
        new Date().toLocaleTimeString("i");
    } catch (e) {
        return e​.name === "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 une heure sur 12h avec AM/PM
console.log(date.toLocaleTimeString("en-US"));
// → "4:00:00 AM"

// l'anglais britanique utilise une heure sur 24h
console.log(date.toLocaleTimeString("en-GB"));
// → "04:00:00"

// le coréen  utilise une heure sur 12h avec AM/PM
console.log(date.toLocaleTimeString("ko-KR"));
// → "오전 4:00:00"

/ l'arabe, dans la plupart des pays arabophones, utilise les chiffres arabes
console.log(date.toLocaleTimeString("ar-EG"));
// → "٤:٠٠:٠٠ ص"

// 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.toLocaleTimeString(["ban", "id"]));
// → "4.00.00"

Utiliser options

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

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

// une application peut vouloir utiliser UTC et le montrer
var options = {timeZone: "UTC", timeZoneName: "short"};
console.log(date.toLocaleTimeString("en-US", options));
// → "3:00:00 AM GMT"

// parfois, même les USA ont besoin du format sur 24h
console.log(date.toLocaleTimeString("en-US", {hour12: false}));
// → "19:00:00"

Performance

Pour formater de nombreuses dates, 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.toLocaleTimeString' dans cette spécification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
La définition de 'Date.prototype.toLocaleTimeString' dans cette spécification.
Standard  
ECMAScript (ECMA-262)
La définition de 'Date.prototype.toLocaleTimeString' dans cette spécification.
Standard évolutif  
ECMAScript Internationalization API 1.0 (ECMA-402)
La définition de 'Date.prototype.toLocaleTimeString' 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.toLocaleTimeString' dans cette spécification.
Standard  
ECMAScript Internationalization API (ECMA-402)
La définition de 'Date.prototype.toLocaleTimeString' dans cette spécification.
Standard évolutif  

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobileServeur
ChromeEdgeFirefoxInternet ExplorerOperaSafariWebview AndroidChrome pour AndroidFirefox pour AndroidOpera pour AndroidSafari sur iOSSamsung InternetNode.js
toLocaleTimeStringChrome Support complet 1Edge Support complet 12Firefox Support complet 1IE Support complet 5.5Opera Support complet 5Safari Support complet 1WebView Android Support complet 1Chrome Android Support complet 18Firefox Android Support complet 4Opera Android Support complet 10.1Safari iOS Support complet 1Samsung Internet Android Support complet 1.0nodejs Support complet 0.1.100
IANA time zone names in timeZone optionChrome Support complet 24Edge Support complet 14Firefox Support complet 52IE Aucun support NonOpera Support complet 15Safari Support complet 6.1WebView Android Support complet 4.4Chrome Android Support complet 25Firefox Android Aucun support NonOpera Android Support complet 14Safari iOS Support complet 7Samsung Internet Android Support complet 1.5nodejs Support complet 0.12
localesChrome Support complet 24Edge Support complet 12Firefox Support complet 29IE Support complet 11Opera Support complet 15Safari Support complet 10WebView Android Support complet 4.4Chrome Android Support complet 25Firefox Android Support complet 56Opera Android Support complet 14Safari iOS Support complet 10Samsung Internet Android Support complet 1.5nodejs Support complet 13.0.0
Support complet 13.0.0
Support partiel 0.12
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. When other locales are specified, the function silently falls back to en-US. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.
optionsChrome Support complet 24Edge Support complet 12Firefox Support complet 29IE Support complet 11Opera Support complet 15Safari Support complet 10WebView Android Support complet 4.4Chrome Android Support complet 25Firefox Android Support complet 56Opera Android Support complet 14Safari iOS Support complet 10Samsung Internet Android Support complet 1.5nodejs Support complet 0.12

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Voir aussi