Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

CKTIS / JavaScript

Intl.DateTimeFormat.prototype.format — formattare date e orari in base alle impostazioni locali

Usa `formatter.format()` per mostrare una data e un orario secondo le impostazioni locali e il fuso orario. Il risultato è testo da visualizzare, non un formato per memorizzare dati.

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

Sintassi

const formatter = new Intl.DateTimeFormat(locales, options);
formatter.format(date);
formatter.format();
const format = formatter.format;
format(date);

Chiama formatter.format(...) su un’istanza di Intl.DateTimeFormat, non sul costruttore. Crea un formattatore con new Intl.DateTimeFormat(locales, options) per scegliere le impostazioni locali, il fuso orario e i campi da mostrare. La chiamata restituisce una stringa e non modifica l’oggetto Date. Se ometti locales o timeZone, il formattatore usa il valore predefinito corrispondente dell’ambiente di esecuzione.

In ECMA-402 (2024), passa un oggetto Date o un timestamp numerico in millisecondi dall’epoca Unix, non in secondi. Se ometti l’argomento o passi undefined, viene formattato l’istante corrente al momento della chiamata. format() non interpreta le stringhe di data: converti prima il testo in un Date valido o in un timestamp. Un Date non valido, NaN, un valore infinito o un timestamp fuori dall’intervallo di Date genera un RangeError.

Intl.DateTimeFormat.prototype.format è una proprietà con un getter. La lettura di formatter.format restituisce la stessa funzione associata a quell’istanza, perciò puoi passarla direttamente come callback, ad esempio con dates.map(formatter.format), senza chiamare bind().

Gli ambienti che integrano Temporal possono anche formattare Temporal.PlainDateTime, Temporal.PlainDate, Temporal.PlainTime, Temporal.PlainYearMonth o Temporal.PlainMonthDay se il tipo è compatibile con le impostazioni del formattatore. Temporal.ZonedDateTime genera un TypeError; usa Temporal.ZonedDateTime.prototype.toLocaleString() per formattare il valore nel suo fuso orario.

Anche con le stesse impostazioni, il risultato può variare tra ambienti di esecuzione, per esempio negli spazi, nella punteggiatura o nei caratteri di controllo bidirezionale. Non confrontarlo con testo fisso nel codice e non usarlo come formato di scambio dei dati.

Esempi

const formatter = new Intl.DateTimeFormat("en-GB", {
  year: "numeric",
  month: "long",
  day: "numeric",
  timeZone: "UTC",
});
const date = new Date("2024-06-15T00:00:00Z");
const format = formatter.format;
const text = formatter.format(date);

console.log(typeof text);
console.log(text === format(date.getTime()));

Risultato

string
true

L’esempio fissa l’istante, le impostazioni locali e il fuso orario UTC. Controlla il tipo del risultato e verifica che la funzione chiamata separatamente formatti un timestamp come la chiamata sull’istanza con l’oggetto `Date` equivalente, senza presupporre il testo esatto.

Lezioni correlate

  • JavaScript · Lezione 15 · Base · Versione: 4

Fonti