Trabalhar com timestamps Unix em JavaScript
Tudo o que precisas para trabalhar com timestamps Unix em JavaScript — obter a hora atual, criar Date a partir de timestamps, formatar para qualquer fuso horário e evitar erros comuns — com um resumo para copiar e colar e ligações para os guias detalhados.
Resumo de timestamps em JavaScript
O JavaScript trabalha em milissegundos: o Date.now() e o construtor Date usam ambos milissegundos desde o epoch Unix, enquanto a maioria dos outros sistemas usa segundos — por isso quase toda tarefa de timestamp em JavaScript se resume a lembrar um × 1000 ou um ÷ 1000. A tabela abaixo é a referência rápida; as secções seguintes explicam cada operação, e os guias detalhados cobrem os fusos e a API Temporal por completo.
| Tarefa | Código | Resultado |
|---|---|---|
| Hora atual (ms) | Date.now() | 1700000000000 |
| Hora atual (s) | Math.floor(Date.now() / 1000) | 1700000000 |
| Segundos → Date | new Date(s * 1000) | Objeto Date |
| Milissegundos → Date | new Date(ms) | Objeto Date |
| Date → ms | date.getTime() | 1700000000000 |
| Date → ISO 8601 | date.toISOString() | 2023-11-15T06:13:20.000Z |
| Cadeia ISO → ms | Date.parse(str) | 1700000000000 |
Obter o timestamp Unix atual
O JavaScript oferece várias formas equivalentes de obter a hora atual como timestamp numérico. Todas devolvem o número de milissegundos desde o epoch Unix.
- Date.now() → o mais rápido e legível — 1700000000000 (milissegundos)
- Math.floor(Date.now() / 1000) → timestamp Unix em segundos — 1700000000
- +new Date() → igual ao Date.now(), com o operador mais unário
- new Date().getTime() → chamada de método explícita, mesmo resultado que Date.now()
Criar um objeto Date a partir de um timestamp Unix
O construtor Date aceita milissegundos desde o epoch. Multiplica sempre um timestamp baseado em segundos por 1000 antes de o passar ao construtor.
- new Date(1700000000 * 1000) → a partir de segundos (o caso mais comum)
- new Date(1700000000000) → a partir de milissegundos (APIs de JavaScript, Java)
- new Date(Date.now()) → hora atual como objeto Date
- new Date(0) → o epoch Unix: 1 de janeiro de 1970 00:00:00 UTC
Formatar datas — métodos de cadeia integrados
O objeto Date tem vários métodos integrados de conversão em cadeia. Cada um produz um formato diferente.
- .toISOString() → '2023-11-15T06:13:20.000Z' — ISO 8601, sempre UTC, legível por máquina
- .toUTCString() → 'Wed, 15 Nov 2023 06:13:20 GMT' — RFC 7231, UTC legível por humanos
- .toString() → cadeia em fuso local com o nome completo da zona
- .toLocaleString() → formato ciente da localização, no fuso local do utilizador
Formatação ciente do fuso horário
Para formatação ciente do fuso, usa Intl.DateTimeFormat com um timeZone explícito — aplica o DST automaticamente e não precisa de biblioteca. Os fusos são um tema profundo por si só; o guia dedicado de fusos em JavaScript cobre formatToParts, detetar o fuso do utilizador e a difícil direção relógio-de-parede-para-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 })
Reconverter uma cadeia de data num timestamp Unix
Para ir na direção oposta — de uma cadeia de data para um timestamp Unix — usa Date.parse() ou passa a cadeia ao construtor Date.
- new Date('2023-11-15T06:13:20Z').getTime() / 1000 → segundos Unix a partir de ISO 8601 UTC
- new Date('2023-11-15T01:13:20-05:00').getTime() → milissegundos Unix a partir de ISO com deslocamento
- Date.parse('2023-11-15T06:13:20Z') → igual a new Date(...).getTime()
- Usa sempre o formato ISO 8601 com fuso explícito para um parsing previsível
Armadilhas comuns
Estes são os erros mais frequentes que os programadores de JavaScript cometem com datas e timestamps:
- new Date(1700000000) — sem o × 1000 converte para o ano ~1970 em vez de 2023
- getMonth() devolve 0–11 e não 1–12 — soma sempre 1 ao mostrar
- new Date('2024-01-01') é meia-noite UTC; new Date('2024/01/01') é meia-noite local
- new Date(2024, 0, 1) = 1 de janeiro (o mês também está indexado a 0 no construtor)
- Somar 86400000 ms para obter 'amanhã' pode falhar nas fronteiras do DST — usa antes setDate(d.getDate() + 1)
A API Temporal — substituto moderno de Date
A API Temporal do TC39 atingiu o Stage 4 e é incluída nos navegadores modernos e no Node.js. Corrige as falhas centrais do Date — é imutável, precisa ao nanossegundo e ciente de fusos — e o Temporal.Instant é o seu tipo timestamp Unix. A API publicada converte epochs em milissegundos ou nanossegundos (o antigo fromEpochSeconds foi removido), por isso multiplica os segundos Unix por 1000. Vê o guia Temporal completo para toda a API.
- Temporal.Now.instant() — o instante atual, com precisão de nanossegundos
- Temporal.Instant.fromEpochMilliseconds(Date.now()) — a partir de um timestamp JS em milissegundos
- Temporal.Instant.fromEpochMilliseconds(1700000000 * 1000) — a partir de segundos Unix (× 1000)
- Temporal.ZonedDateTime — instante + fuso IANA, o tipo que o Date devia ter sido
- Incluído no Firefox 139+, Chrome 144+, Node.js 26+; Safari em Technology Preview; polyfill para o resto
Ir mais longe
FAQ
- Como obtenho um timestamp Unix em segundos em JavaScript?
- Usa Math.floor(Date.now() / 1000). O Date.now() devolve milissegundos, por isso divide por 1000 e arredonda para baixo para obter segundos Unix inteiros.
- Como converto um timestamp Unix numa data legível em JavaScript?
- Multiplica os segundos por 1000, passa-os ao construtor Date e depois formata: new Date(1700000000 * 1000).toISOString() dá "2023-11-14T22:13:20.000Z". Para um fuso específico, usa Intl.DateTimeFormat com uma opção timeZone.
- Porque é que new Date() com um timestamp Unix mostra 1970?
- O construtor Date espera milissegundos. Um timestamp em segundos de 10 dígitos tem de ser multiplicado por 1000: new Date(seconds * 1000).
- Como formato uma data de JavaScript para um fuso específico?
- Usa Intl.DateTimeFormat com uma opção timeZone explícita, como new Intl.DateTimeFormat('en-US', { timeZone: 'America/New_York' }). Aplica o horário de verão automaticamente e não precisa de nenhuma biblioteca externa.
- Devo usar Date ou Temporal?
- Para código novo onde o runtime o suporta, prefere Temporal — é imutável, ciente de fusos e evita as armadilhas do Date. O Date continua bom para trabalho simples em milissegundos epoch e é ainda o mais amplamente suportado.