Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

Date.prototype.toLocaleTimeString() — formatage localisé de l’heure

toLocaleTimeString() renvoie une représentation textuelle de l’heure d’un objet Date selon la locale et les options choisies. Cette méthode permet de définir le fuseau horaire, les composants de l’heure et le cycle horaire sans modifier la date.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

date.toLocaleTimeString(locales?, options?)

Le symbole de catalogue Date.toLocaleTimeString désigne la méthode d’instance Date.prototype.toLocaleTimeString, et non une méthode statique du constructeur Date. L’appel date.toLocaleTimeString(locales, options) renvoie une chaîne sans modifier date. Le comportement des paramètres décrit ici concerne les environnements compatibles avec ECMA-402 (Intl).

locales accepte une balise de langue, telle que pl-PL, ou une liste de balises préférées. Si cet argument est omis, la locale par défaut de l’environnement est utilisée. options.timeZone définit le fuseau horaire d’affichage ; sinon, celui de l’environnement est utilisé. Les options hour, minute et second sélectionnent les composants de l’heure. Si hour12 n’est pas défini, hourCycle: 'h23' sélectionne un cycle allant de 0 à 23 heures. L’option hour12 prime sur hourCycle : si vous indiquez à la fois hour12: true et hourCycle: 'h23', le formatage utilise un cycle de 12 heures. En l’absence de style et de composants d’heure précisés, l’heure, les minutes et les secondes sont incluses par défaut.

Vous pouvez utiliser timeStyle, par exemple 'short', à la place des options explicites de composants. Lors du formatage d’une date valide, combiner timeStyle avec une option de composant telle que hour déclenche une TypeError. Pour une date valide, passer dateStyle à toLocaleTimeString() déclenche également une TypeError, même si c’est la seule option. Pour un objet Date invalide, la méthode renvoie "Invalid Date" avant de traiter les options : la combinaison de timeStyle et de hour ne déclenche donc pas d’erreur dans ce cas. Un récepteur qui n’est pas un objet Date provoque une TypeError.

Le résultat est destiné à l’affichage pour l’utilisateur, et non à un stockage stable ou au parsing : les données de locale peuvent modifier la ponctuation et les espaces. L’exemple fixe l’instant, la locale, le fuseau UTC, le cycle horaire et le système de numération afin de réduire les variations. Pour des formatages répétés, envisagez de créer un seul Intl.DateTimeFormat et de réutiliser sa méthode format.

Exemples

const date = new Date('2024-01-15T13:05:09.000Z');
const text = date.toLocaleTimeString('en-GB', {
  timeZone: 'UTC',
  hourCycle: 'h23',
  numberingSystem: 'latn',
  hour: '2-digit',
  minute: '2-digit',
  second: '2-digit'
});
console.log(text);

Résultat

13:05:09

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources