Date : méthode toLocaleTimeString()

Exemple interactif

// Selon le fuseau horaire, vos résultats peuvent varier
const event = new Date("August 19, 1975 23:15:30 GMT+00:00");

console.log(event.toLocaleTimeString("en-US"));
// Résultat attendu : "1:15:30 AM"

console.log(event.toLocaleTimeString("it-IT"));
// Résultat attendu : "01:15:30"

console.log(event.toLocaleTimeString("ar-EG"));
// Résultat attendu : "١٢:١٥:٣٠ ص"

Syntaxe

toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)

Paramètres

Les paramètres locales et options personnalisent le comportement de la fonction et permettent aux applications d'indiquer la langue dont les conventions de formatage doivent être utilisées.

Dans les implémentations prenant en charge l'API Intl.DateTimeFormat, ces paramètres correspondent exactement à ceux du constructeur Intl.DateTimeFormat(). Les implémentations sans prise en charge de Intl.DateTimeFormat doivent ignorer ces deux paramètres, rendant la locale utilisée et la forme de la chaîne retournée entièrement dépendantes de l'implémentation.

locales Facultatif

Une chaîne de caractères avec un identifiant de langue BCP 47, ou un tableau de telles chaînes. Correspond au paramètre locales du constructeur Intl.DateTimeFormat().

Dans les implémentations sans prise en charge de Intl.DateTimeFormat, ce paramètre est ignoré et la locale de l'hôte est généralement utilisée.

options Facultatif

Un objet ajustant le format de sortie. Correspond au paramètre options du constructeur Intl.DateTimeFormat(). L'option timeStyle doit être indéfinie, sinon une TypeError sera levée. Si dayPeriod, hour, minute, second, et fractionalSecondDigits sont tous indéfinis, alors hour, minute et second seront définis sur "numeric".

Dans les implémentations sans prise en charge de Intl.DateTimeFormat, ce paramètre est ignoré.

Voir le constructeur Intl.DateTimeFormat() pour plus de détails sur ces paramètres et leur utilisation.

Valeur de retour

Une chaîne de caractères représentant la portion temporelle de la date indiquée selon des conventions propres à la langue.

Dans les implémentations prenant en charge Intl.DateTimeFormat, cela équivaut à new Intl.DateTimeFormat(locales, options).format(date), où options a été normalisé comme décrit ci‑dessus.

Exemples

Utiliser la méthode toLocaleTimeString()

L'utilisation basique de cette méthode sans définir de locale retourne une chaîne de caractères formatée selon la locale par défaut et avec les options par défaut.

const 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 la prise en charge des arguments locales et options

Les paramètres locales et options peuvent ne pas être pris en charge dans toutes les implémentations, car la prise en charge de l'API d'internationalisation est facultative, et certains systèmes peuvent ne pas disposer des données nécessaires. Pour les implémentations sans prise en charge de l'internationalisation, toLocaleString() utilise toujours la locale du système, ce qui peut ne pas être souhaité. Toute implémentation qui prend en charge les paramètres locales et options doit prendre en charge l'API Intl, vous pouvez vérifier l'existence de cette dernière pour la prise en charge :

function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

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 :

const 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 :

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

// une application peut vouloir utiliser UTC et le montrer
const 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"

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Intl.DateTimeFormat
• La méthode Date.prototype.toLocaleDateString()
• La méthode Date.prototype.toLocaleString()
• La méthode Date.prototype.toTimeString()
• La méthode Date.prototype.toString()