CKTIS / JavaScript
Intl.RelativeTimeFormat.prototype.format() — formater un temps relatif
Transforme un décalage temporel signé et une unité explicite en texte localisé. La méthode ne calcule pas elle-même la différence entre deux dates.
Version : ECMAScript 2024 and the current web platform; runtime support varies
Syntaxe
const formatter = new Intl.RelativeTimeFormat(locales, options);
formatter.format(value, unit);Intl.RelativeTimeFormat.prototype.format est une méthode d’instance. formatter.format(value, unit) renvoie une chaîne qui suit les paramètres régionaux effectivement retenus et les options définies à la construction. L’application calcule le décalage par rapport à un point de référence et choisit l’unité ; la méthode ne consulte pas l’horloge et ne soustrait pas de dates.
Une valeur négative désigne le passé, une valeur positive le futur. Avec un modèle numérique, -0 sélectionne le modèle du passé et +0 celui du futur. unit accepte les identifiants exacts "second", "minute", "hour", "day", "week", "month", "quarter" et "year", ainsi que leurs formes terminées par s. La forme de l’identifiant ne fixe pas la grammaire du résultat.
numeric: "always" (par défaut) utilise un modèle numérique. numeric: "auto" utilise une expression dédiée, comme yesterday, s’il en existe une ; sinon, il revient au modèle numérique. style sélectionne "long" (par défaut), "short" ou "narrow". La prise en charge varie selon l’environnement d’exécution. Même avec les mêmes paramètres régionaux, le texte peut différer, par exemple par la présence d’espaces insécables. Dans les tests portables, ne comparez pas le résultat à un texte codé en dur.
La méthode exige une instance comme this ; un appel détaché sans this valide déclenche une TypeError. Pour l’utiliser comme fonction de rappel, utilisez formatter.format.bind(formatter). Après avoir vérifié this, la méthode applique ToNumber à value, puis ToString à unit. Un BigInt passé comme value déclenche par exemple une TypeError. Après conversion, NaN, Infinity, -Infinity ou un identifiant d’unité non pris en charge déclenche une RangeError.
Exemples
{
const numeric = new Intl.RelativeTimeFormat("en", { numeric: "always" });
const auto = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
const past = numeric.format(-1, "day");
console.log(past);
console.log(auto.format(-1, "day"));
console.log(past === numeric.format(-1, "days"));
}Résultat
1 day ago yesterday true
Pour le même décalage de `-1` jour, les deux premières lignes montrent le texte anglais habituel pour `"always"` et `"auto"`. La troisième montre que `"day"` et `"days"` sont équivalents.
Leçons associées
- JavaScript · Leçon 24 · Avancé · Version : 4
Sources
- ECMAScript® 2024 Internationalization API Specification — Intl.RelativeTimeFormat.prototype.format
- ECMAScript® 2024 Internationalization API Specification — PartitionRelativeTimePattern
- ECMAScript Internationalization API Specification (living draft) — Intl.RelativeTimeFormat.prototype.format
- Intl.RelativeTimeFormat.prototype.format() - JavaScript | MDN