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

CKTIS / JavaScript

Intl.DateTimeFormat.formatToParts() : parties d’une date ou d’une heure

Récupérez les parties d’une date ou d’une heure localisée pour mettre en forme un élément sans supposer l’ordre des champs ni découper le texte selon sa ponctuation.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

formatter.formatToParts()
formatter.formatToParts(date)

Intl.DateTimeFormat.prototype.formatToParts est une méthode d’instance de Intl.DateTimeFormat. Au lieu de la chaîne unique renvoyée par format(), elle fournit un tableau d’objets { type, value } dans l’ordre d’affichage. Les deux propriétés sont des chaînes. Réunir tous les value avec join("") reproduit le résultat de format() pour le même formateur et la même entrée. Contrairement à la fonction renvoyée par format, formatToParts n’est pas automatiquement liée à l’instance. Passez date => formatter.formatToParts(date) comme fonction de rappel ou utilisez bind ; un this incompatible déclenche une TypeError.

Sélectionnez les parties par type, par exemple month ou dayPeriod, et non par indice. Conservez les parties literal : elles peuvent contenir des espaces, de la ponctuation ou des mots. Dans certains calendriers, relatedYear (l’année grégorienne correspondante) remplace year, parfois accompagné de yearName (le nom de l’année). Conservez aussi les parties inconnues. Les paramètres régionaux, les options et les données de l’environnement peuvent modifier le résultat. Ces parties servent à l’affichage, pas à l’analyse ni au stockage. Dans un navigateur, insérez les valeurs comme texte avec textContent, pas avec innerHTML.

Dans ECMA-402 pour ECMAScript 2024, passez un objet Date ou un nombre de millisecondes depuis l’époque Unix. La méthode convertit l’argument en nombre ; elle n’interprète pas les chaînes comme des dates. Si l’argument est omis ou vaut undefined, elle utilise l’heure courante au moment de l’appel. Un Date invalide ou un horodatage hors limites déclenche une RangeError.

Les environnements qui intègrent Temporal acceptent aussi Temporal.Instant et les types Temporal.Plain* prévus pour cette méthode, avec des restrictions de calendrier et de formatage propres au type. Vérifiez la prise en charge dans l’environnement cible. Passer directement un Temporal.ZonedDateTime déclenche une TypeError. Pour obtenir les parties du même instant dans son fuseau, passez le résultat de toInstant() et réglez timeZone du formateur sur le fuseau de cet objet.

Exemples

{
  const formatter = new Intl.DateTimeFormat("en-US", {
    timeZone: "UTC",
    calendar: "gregory",
    year: "numeric",
    month: "long",
    day: "numeric",
  });
  const date = new Date("2024-07-05T12:00:00Z");
  const parts = formatter.formatToParts(date);

  console.log(parts.some(({ type }) => type === "month"));
  console.log(parts.map(({ value }) => value).join("") === formatter.format(date));
}

Résultat

true
true

L’exemple fixe l’instant, les paramètres régionaux et le fuseau UTC. Le premier `true` confirme la présence d’une partie `month`. Le second confirme que les valeurs réunies correspondent à `format(date)`, sans supposer de séparateurs précis.

Leçons associées

  • JavaScript · Leçon 25 · Avancé · Version : 4

Sources