CKTIS / JavaScript
Fusi orari e cicli orari in Intl.DateTimeFormat
`timeZone` sceglie l’ora locale da mostrare per un istante, mentre `hourCycle` stabilisce come numerare le ore, per esempio se indicare la mezzanotte con `00` o `24`.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
new Intl.DateTimeFormat(locales, { timeZone, hourCycle, hour: "2-digit" })timeZone seleziona il fuso in cui visualizzare un istante, senza modificare l’oggetto Date o il valore che contiene. Se omesso, si usa il fuso predefinito dell’ambiente di esecuzione. Un fuso con nome come "America/New_York" applica le regole valide per quell’istante, compresi i cambi dell’ora legale. Uno scostamento fisso come "-05:00" non segue tali regole. Gli ambienti meno recenti potrebbero non supportare gli identificatori di scostamento. timeZoneName controlla l’etichetta visualizzata, non la scelta del fuso.
hourCycle stabilisce l’intervallo delle ore: "h11" va da 0 a 11, "h12" da 1 a 12, "h23" da 0 a 23 e "h24" da 1 a 24. In "h24", 24 indica l’ora che inizia a mezzanotte, senza spostare l’istante al giorno successivo. hourCycle da solo non aggiunge l’ora al risultato: richiedila con hour o timeStyle, senza combinare le due opzioni.
hour12: true e hour12: false prevalgono sia su hourCycle sia sull’estensione Unicode hc delle impostazioni locali. true sceglie un ciclo di 12 ore, false un ciclo di 24. Per imporre un ciclo preciso, ometti hour12 e imposta hourCycle, che prevale su hc. In assenza di queste impostazioni, il ciclo predefinito dipende dalle impostazioni locali.
Un hourCycle non valido o un identificatore timeZone non riconosciuto genera un RangeError alla creazione del formattatore, anche se un hour12 valido avrebbe la precedenza su hourCycle. Controlla le impostazioni effettive con resolvedOptions(): il ciclo non compare se il formato non include l’ora. Per estrarre solo l’ora usa la parte hour di formatToParts(), anziché analizzare l’intera stringa localizzata.
Esempi
const instant = new Date("2024-01-15T05:00:00Z");
function showHour(timeZone, hourCycle) {
const formatter = new Intl.DateTimeFormat("en-US", {
timeZone,
hourCycle,
hour: "2-digit",
numberingSystem: "latn",
formatMatcher: "basic",
});
const hour = formatter.formatToParts(instant).find(part => part.type === "hour");
const displayHour = hour.value.padStart(2, "0");
console.log(`${timeZone} ${formatter.resolvedOptions().hourCycle}: ${displayHour}`);
}
showHour("UTC", "h23");
showHour("America/New_York", "h23");
showHour("America/New_York", "h24");Risultato
UTC h23: 05 America/New_York h23: 00 America/New_York h24: 24
Nelle prime due righe cambia solo il fuso: lo stesso istante corrisponde all’ora `05` in UTC e alla mezzanotte a New York. Nell’ultima riga cambia solo il ciclo, quindi la stessa ora locale è visualizzata come `24` anziché `00`.
Lezioni correlate
- JavaScript · Lezione 25 · Avanzato · Versione: 4
Fonti
- ECMAScript® 2024 Internationalization API Specification — CreateDateTimeFormat
- ECMAScript Internationalization API Specification — CreateDateTimeFormat (living specification)
- Intl.DateTimeFormat() constructor — MDN
- Intl.DateTimeFormat.prototype.resolvedOptions() — MDN
- Intl.DateTimeFormat.prototype.formatToParts() — MDN