Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Intl.RelativeTimeFormat.prototype.format() — formattare il tempo relativo

Converte uno scostamento temporale con segno e un’unità esplicita in testo localizzato. Non calcola la differenza tra due date.

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

Sintassi

const formatter = new Intl.RelativeTimeFormat(locales, options);
formatter.format(value, unit);

Intl.RelativeTimeFormat.prototype.format è un metodo di istanza. formatter.format(value, unit) restituisce una stringa secondo la lingua effettivamente selezionata e le opzioni impostate nel costruttore. L’applicazione calcola lo scostamento da un punto di riferimento e sceglie l’unità; il metodo non consulta l’orologio né sottrae date.

I valori negativi indicano il passato, quelli positivi il futuro. Se si usa uno schema numerico, -0 seleziona quello del passato e +0 quello del futuro. unit accetta gli identificatori esatti "second", "minute", "hour", "day", "week", "month", "quarter" e "year", oltre alle rispettive forme con s finale. La forma dell’identificatore non determina la grammatica del risultato.

numeric: "always" (predefinito) usa uno schema numerico. numeric: "auto" usa un’espressione specifica, come yesterday, se disponibile; altrimenti usa lo schema numerico. style seleziona "long" (predefinito), "short" o "narrow". Il supporto dipende dall’ambiente di esecuzione e il testo può variare anche a parità di impostazioni locali, per esempio per la presenza di spazi unificatori. Nei test portabili non confrontare il risultato con un testo fisso.

Il metodo richiede un’istanza come this; chiamarlo separatamente senza un this valido genera TypeError. Se serve una callback, usa formatter.format.bind(formatter). Dopo aver verificato this, il metodo applica ToNumber a value, poi ToString a unit. Per esempio, un BigInt come value genera TypeError. Dopo la conversione, NaN, Infinity, -Infinity o un identificatore di unità non supportato generano RangeError.

Esempi

{
  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"));
}

Risultato

1 day ago
yesterday
true

Per lo stesso scostamento di `-1` giorno, le prime due righe mostrano il testo inglese tipico per `"always"` e `"auto"`. La terza mostra che `"day"` e `"days"` sono equivalenti.

Lezioni correlate

  • JavaScript · Lezione 24 · Avanzato · Versione: 4

Fonti