Lavorare con i timestamp Unix in JavaScript
Tutto ciò che serve per lavorare con i timestamp Unix in JavaScript — ottenere l'ora attuale, creare Date da timestamp, formattare per qualsiasi fuso orario ed evitare gli errori comuni — con un riepilogo da copiare e incollare e link alle guide approfondite.
Riepilogo dei timestamp in JavaScript
JavaScript lavora in millisecondi: Date.now() e il costruttore Date usano entrambi millisecondi dall'epoch Unix, mentre la maggior parte degli altri sistemi usa secondi — quindi quasi ogni compito di timestamp in JavaScript si riduce a ricordare un × 1000 o un ÷ 1000. La tabella sotto è il riferimento rapido; le sezioni successive spiegano ogni operazione, e le guide approfondite coprono i fusi e l'API Temporal per intero.
| Compito | Codice | Risultato |
|---|---|---|
| Ora attuale (ms) | Date.now() | 1700000000000 |
| Ora attuale (s) | Math.floor(Date.now() / 1000) | 1700000000 |
| Secondi → Date | new Date(s * 1000) | Oggetto Date |
| Millisecondi → Date | new Date(ms) | Oggetto Date |
| Date → ms | date.getTime() | 1700000000000 |
| Date → ISO 8601 | date.toISOString() | 2023-11-15T06:13:20.000Z |
| Stringa ISO → ms | Date.parse(str) | 1700000000000 |
Ottenere il timestamp Unix attuale
JavaScript offre diversi modi equivalenti per ottenere l'ora attuale come timestamp numerico. Tutti restituiscono il numero di millisecondi dall'epoch Unix.
- Date.now() → il più veloce e leggibile — 1700000000000 (millisecondi)
- Math.floor(Date.now() / 1000) → timestamp Unix in secondi — 1700000000
- +new Date() → uguale a Date.now(), con l'operatore più unario
- new Date().getTime() → chiamata di metodo esplicita, stesso risultato di Date.now()
Creare un oggetto Date da un timestamp Unix
Il costruttore Date accetta millisecondi dall'epoch. Moltiplica sempre un timestamp basato sui secondi per 1000 prima di passarlo al costruttore.
- new Date(1700000000 * 1000) → da secondi (il caso più comune)
- new Date(1700000000000) → da millisecondi (API JavaScript, Java)
- new Date(Date.now()) → ora attuale come oggetto Date
- new Date(0) → l'epoch Unix: 1° gennaio 1970 00:00:00 UTC
Formattare le date — metodi stringa integrati
L'oggetto Date ha diversi metodi integrati di conversione in stringa. Ognuno produce un formato diverso.
- .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, sempre UTC, leggibile dalla macchina
- .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, UTC leggibile dall'uomo
- .toString() → stringa nel fuso locale con il nome completo della zona
- .toLocaleString() → formato consapevole della locale, nel fuso locale dell'utente
Formattazione consapevole del fuso orario
Per una formattazione consapevole del fuso, usa Intl.DateTimeFormat con un timeZone esplicito — applica il DST automaticamente e non richiede librerie. I fusi sono un tema profondo a sé; la guida dedicata ai fusi in JavaScript copre formatToParts, il rilevamento del fuso dell'utente e la difficile direzione orologio-da-parete-verso-UTC.
- new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York', dateStyle: 'full', timeStyle: 'long' }).format(date)
- date.toLocaleString('en-GB', { timeZone: 'Europe/London', hour12: false })
Riconvertire una stringa di data in un timestamp Unix
Per andare nella direzione opposta — da una stringa di data a un timestamp Unix — usa Date.parse() o passa la stringa al costruttore Date.
- new Date('2023-11-15T06:13:20Z').getTime() / 1000 → secondi Unix da ISO 8601 UTC
- new Date('2023-11-15T01:13:20-05:00').getTime() → millisecondi Unix da ISO con offset
- Date.parse('2023-11-15T06:13:20Z') → uguale a new Date(...).getTime()
- Usa sempre il formato ISO 8601 con fuso esplicito per un parsing prevedibile
Insidie comuni
Questi sono gli errori più frequenti che gli sviluppatori JavaScript commettono con date e timestamp:
- new Date(1700000000) — senza il × 1000 converte all'anno ~1970 invece del 2023
- getMonth() restituisce 0–11 e non 1–12 — aggiungi sempre 1 quando lo mostri
- new Date('2024-01-01') è mezzanotte UTC; new Date('2024/01/01') è mezzanotte locale
- new Date(2024, 0, 1) = 1° gennaio (il mese è indicizzato da 0 anche nel costruttore)
- Aggiungere 86400000 ms per ottenere 'domani' può fallire ai confini del DST — usa invece setDate(d.getDate() + 1)
L'API Temporal — sostituto moderno di Date
L'API Temporal di TC39 ha raggiunto lo Stage 4 ed è inclusa nei browser moderni e in Node.js. Corregge i difetti centrali di Date — è immutabile, precisa al nanosecondo e consapevole dei fusi — e Temporal.Instant è il suo tipo timestamp Unix. L'API rilasciata converte gli epoch in millisecondi o nanosecondi (il vecchio fromEpochSeconds è stato rimosso), quindi moltiplica i secondi Unix per 1000. Vedi la guida Temporal completa per l'intera API.
- Temporal.Now.instant() — l'istante attuale, con precisione al nanosecondo
- Temporal.Instant.fromEpochMilliseconds(Date.now()) — da un timestamp JS in millisecondi
- Temporal.Instant.fromEpochMilliseconds(1700000000 * 1000) — da secondi Unix (× 1000)
- Temporal.ZonedDateTime — istante + fuso IANA, il tipo che Date avrebbe dovuto essere
- Incluso in Firefox 139+, Chrome 144+, Node.js 26+; Safari in Technology Preview; polyfill per il resto
Per approfondire
FAQ
- Come ottengo un timestamp Unix in secondi in JavaScript?
- Usa Math.floor(Date.now() / 1000). Date.now() restituisce millisecondi, quindi dividi per 1000 e arrotonda per difetto per ottenere secondi Unix interi.
- Come converto un timestamp Unix in una data leggibile in JavaScript?
- Moltiplica i secondi per 1000, passali al costruttore Date, poi formatta: new Date(1700000000 * 1000).toISOString() dà "2023-11-14T22:13:20.000Z". Per un fuso specifico, usa Intl.DateTimeFormat con un'opzione timeZone.
- Perché new Date() con un timestamp Unix mostra il 1970?
- Il costruttore Date si aspetta millisecondi. Un timestamp in secondi a 10 cifre va moltiplicato per 1000: new Date(seconds * 1000).
- Come formatto una data di JavaScript per un fuso specifico?
- Usa Intl.DateTimeFormat con un'opzione timeZone esplicita, come new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }). Applica l'ora legale automaticamente e non richiede alcuna libreria esterna.
- Dovrei usare Date o Temporal?
- Per codice nuovo dove il runtime lo supporta, preferisci Temporal — è immutabile, consapevole dei fusi ed evita le insidie di Date. Date resta ottimo per semplici lavori in millisecondi epoch ed è ancora il più ampiamente supportato.