Como converter carimbos de data e hora em JavaScript: tutorial completo com exemplos

Introdução

Converter carimbos de data/hora em JavaScript é uma habilidade fundamental para desenvolvedores web. Esteja você trabalhando com APIs, bancos de dados ou interfaces de usuário, você frequentemente precisará converter entre carimbos de data/hora Unix e datas legíveis por humanos. Este tutorial irá guiá-lo através de tudo o que você precisa saber.

O que você aprenderá

• ✅ Obtendo carimbos de data/hora atuais
• ✅ Convertendo carimbos de data/hora em objetos Date
• ✅ Convertendo objetos Date em carimbos de data e hora
• ✅ Formatação de carimbos de data/hora para exibição
• ✅ Lidando com diferentes precisões de carimbo de data/hora
• ✅ Trabalhando com fusos horários
• ✅ Armadilhas comuns e como evitá-las

Pré-requisitos

Conhecimento básico de JavaScript é tudo que você precisa. Nenhuma biblioteca externa é necessária para este tutorial (embora mencionaremos algumas populares no final).

Etapa 1: Obtendo o carimbo de data e hora atual

A operação mais simples é obter a hora atual como carimbo de data/hora.

Método 1: Date.now() (recomendado)

// Get current timestamp in milliseconds
const timestamp = Date.now();
console.log(timestamp);
// Output: 1704067200000 (13 digits)

Por que usar isso?

• ✅ Método mais rápido
• ✅ Não há necessidade de criar um objeto Date
• ✅ Mais comumente usado

Método 2: new Date().getTime()

// Create Date object and get timestamp
const timestamp = new Date().getTime();
console.log(timestamp);
// Output: 1704067200000 (13 digits)

Quando usar isso?

• Quando você já possui um objeto Date
• Quando você precisa encadear métodos

Método 3: Operador Unário Plus

// Shorthand using unary plus
const timestamp = +new Date();
console.log(timestamp);
// Output: 1704067200000 (13 digits)

Quando usar isso?

• Codifique o golfe ou quando a brevidade for importante
• Não recomendado para iniciantes (menos legível)

Obtendo carimbo de data/hora em segundos

JavaScript usa milissegundos por padrão, mas muitas APIs usam segundos:

// Get timestamp in seconds (10 digits)
const timestampInSeconds = Math.floor(Date.now() / 1000);
console.log(timestampInSeconds);
// Output: 1704067200 (10 digits)

// Alternative: Using parseInt
const timestampSec = parseInt(Date.now() / 1000);
console.log(timestampSec);
// Output: 1704067200

Etapa 2: Convertendo carimbo de data / hora em data

Convertendo um carimbo de data/hora Unix em um objeto JavaScript Date.

Conversão Básica

// Millisecond timestamp (13 digits)
const timestamp = 1704067200000;
const date = new Date(timestamp);

console.log(date);
// Output: Mon Jan 01 2024 00:00:00 GMT+0000 (UTC)

console.log(date.toISOString());
// Output: 2024-01-01T00:00:00.000Z

Convertendo segundos carimbos de data/hora

Muitas APIs retornam carimbos de data/hora em segundos (10 dígitos), não em milissegundos:

// Second timestamp (10 digits) - MUST multiply by 1000!
const timestampInSeconds = 1704067200;
const date = new Date(timestampInSeconds * 1000);

console.log(date.toISOString());
// Output: 2024-01-01T00:00:00.000Z

⚠️ Erro comum:

// ❌ WRONG: Using seconds directly
const wrongDate = new Date(1704067200);
console.log(wrongDate.toISOString());
// Output: 1970-01-20T17:27:47.200Z (WRONG!)

// ✅ CORRECT: Multiply by 1000
const correctDate = new Date(1704067200 * 1000);
console.log(correctDate.toISOString());
// Output: 2024-01-01T00:00:00.000Z (CORRECT!)

Detectando a precisão do carimbo de data/hora

Função auxiliar para detectar automaticamente se o carimbo de data/hora está em segundos ou milissegundos:

function createDateFromTimestamp(timestamp) {
    // If timestamp has 10 digits, it's in seconds
    // If timestamp has 13 digits, it's in milliseconds
    const digitCount = timestamp.toString().length;

    if (digitCount === 10) {
        // Seconds - multiply by 1000
        return new Date(timestamp * 1000);
    } else if (digitCount === 13) {
        // Milliseconds - use directly
        return new Date(timestamp);
    } else {
        throw new Error(`Invalid timestamp: ${timestamp}`);
    }
}

// Usage
const date1 = createDateFromTimestamp(1704067200);     // 10 digits (seconds)
const date2 = createDateFromTimestamp(1704067200000);  // 13 digits (milliseconds)

console.log(date1.toISOString());  // 2024-01-01T00:00:00.000Z
console.log(date2.toISOString());  // 2024-01-01T00:00:00.000Z

Etapa 3: Convertendo data em carimbo de data / hora

Convertendo um objeto JavaScript Date de volta em um carimbo de data/hora Unix.

Da data atual

const now = new Date();

// Get timestamp in milliseconds
const timestampMs = now.getTime();
console.log(timestampMs);  // 1704067200000

// Get timestamp in seconds
const timestampSec = Math.floor(now.getTime() / 1000);
console.log(timestampSec);  // 1704067200

Da sequência de data específica

// ISO 8601 format (recommended)
const date1 = new Date('2024-01-01T00:00:00Z');
console.log(date1.getTime());  // 1704067200000

// Different date formats
const date2 = new Date('January 1, 2024');
const date3 = new Date('01/01/2024');
const date4 = new Date('2024-01-01');

console.log(date2.getTime());  // Depends on local timezone
console.log(date3.getTime());  // Depends on local timezone
console.log(date4.getTime());  // Usually 00:00:00 in local timezone

⚠️ Importante: Diferentes formatos de string de data se comportam de maneira diferente com fusos horários!

Dos componentes de data

// Create date from year, month, day, etc.
// Note: Month is 0-indexed (0 = January, 11 = December)
const date = new Date(2024, 0, 1, 0, 0, 0);  // Jan 1, 2024, 00:00:00
const timestamp = date.getTime();

console.log(timestamp);  // Local timezone timestamp

// For UTC, use Date.UTC()
const utcTimestamp = Date.UTC(2024, 0, 1, 0, 0, 0);
console.log(utcTimestamp);  // 1704067200000 (UTC)

Etapa 4: formatação de carimbos de data e hora

Convertendo carimbos de data/hora em formatos legíveis por humanos.

Métodos JavaScript integrados

const date = new Date(1704067200000);

// ISO 8601 format (best for APIs)
console.log(date.toISOString());
// Output: "2024-01-01T00:00:00.000Z"

// Locale-specific date string
console.log(date.toLocaleDateString());
// Output: "1/1/2024" (US) or "01/01/2024" (UK)

// Locale-specific date and time
console.log(date.toLocaleString());
// Output: "1/1/2024, 12:00:00 AM"

// Locale-specific time
console.log(date.toLocaleTimeString());
// Output: "12:00:00 AM"

// Full date string
console.log(date.toDateString());
// Output: "Mon Jan 01 2024"

// UTC string
console.log(date.toUTCString());
// Output: "Mon, 01 Jan 2024 00:00:00 GMT"

Formatação personalizada

function formatTimestamp(timestamp, format = 'full') {
    const date = new Date(timestamp);

    const year = date.getFullYear();
    const month = String(date.getMonth() + 1).padStart(2, '0');
    const day = String(date.getDate()).padStart(2, '0');
    const hours = String(date.getHours()).padStart(2, '0');
    const minutes = String(date.getMinutes()).padStart(2, '0');
    const seconds = String(date.getSeconds()).padStart(2, '0');

    const formats = {
        'full': `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`,
        'date': `${year}-${month}-${day}`,
        'time': `${hours}:${minutes}:${seconds}`,
        'short': `${month}/${day}/${year}`,
        'iso': date.toISOString()
    };

    return formats[format] || formats.full;
}

// Usage
const timestamp = 1704067200000;
console.log(formatTimestamp(timestamp, 'full'));   // "2024-01-01 00:00:00"
console.log(formatTimestamp(timestamp, 'date'));   // "2024-01-01"
console.log(formatTimestamp(timestamp, 'time'));   // "00:00:00"
console.log(formatTimestamp(timestamp, 'short'));  // "01/01/2024"

Usando Intl.DateTimeFormat (abordagem moderna)

const timestamp = 1704067200000;
const date = new Date(timestamp);

// US English format
const usFormatter = new Intl.DateTimeFormat('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
    hour: '2-digit',
    minute: '2-digit'
});
console.log(usFormatter.format(date));
// Output: "January 1, 2024 at 12:00 AM"

// Custom format
const customFormatter = new Intl.DateTimeFormat('en-US', {
    weekday: 'long',
    year: 'numeric',
    month: 'short',
    day: 'numeric',
    hour: '2-digit',
    minute: '2-digit',
    second: '2-digit',
    timeZoneName: 'short'
});
console.log(customFormatter.format(date));
// Output: "Monday, Jan 1, 2024, 12:00:00 AM UTC"

Etapa 5: Trabalhando com fusos horários

Lidar com diferentes fusos horários é crucial para uma conversão precisa do carimbo de data/hora.

UTC versus hora local

const timestamp = 1704067200000;  // Jan 1, 2024, 00:00:00 UTC
const date = new Date(timestamp);

// Get UTC components
console.log('UTC Year:', date.getUTCFullYear());        // 2024
console.log('UTC Month:', date.getUTCMonth() + 1);      // 1
console.log('UTC Date:', date.getUTCDate());            // 1
console.log('UTC Hours:', date.getUTCHours());          // 0

// Get local components (depends on your timezone)
console.log('Local Year:', date.getFullYear());         // 2024
console.log('Local Month:', date.getMonth() + 1);       // 1 (or different)
console.log('Local Date:', date.getDate());             // 1 (or different)
console.log('Local Hours:', date.getHours());           // 0 (or different)

Convertendo para fuso horário específico

const timestamp = 1704067200000;
const date = new Date(timestamp);

// Display in different timezones using Intl.DateTimeFormat
const timezones = ['America/New_York', 'Europe/London', 'Asia/Tokyo'];

timezones.forEach(tz => {
    const formatter = new Intl.DateTimeFormat('en-US', {
        timeZone: tz,
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
        hour: '2-digit',
        minute: '2-digit',
        second: '2-digit',
        timeZoneName: 'short'
    });
    console.log(`${tz}:`, formatter.format(date));
});

// Output:
// America/New_York: 12/31/2023, 07:00:00 PM EST
// Europe/London: 01/01/2024, 12:00:00 AM GMT
// Asia/Tokyo: 01/01/2024, 09:00:00 AM JST

Compensação de fuso horário

const date = new Date();

// Get timezone offset in minutes
const offsetMinutes = date.getTimezoneOffset();
console.log('Offset in minutes:', offsetMinutes);  // e.g., -480 for UTC+8

// Convert to hours
const offsetHours = -offsetMinutes / 60;
console.log('Offset in hours:', offsetHours);  // e.g., 8 for UTC+8

// Format offset as string
const sign = offsetHours >= 0 ? '+' : '-';
const hours = String(Math.abs(Math.floor(offsetHours))).padStart(2, '0');
const minutes = String(Math.abs((offsetHours % 1) * 60)).padStart(2, '0');
console.log(`UTC${sign}${hours}:${minutes}`);  // e.g., "UTC+08:00"

Etapa 6: Armadilhas e soluções comuns

Armadilha 1: Segundos vs Milissegundos

// ❌ WRONG: Assuming all timestamps are in milliseconds
const wrongDate = new Date(1704067200);  // Treats as milliseconds
console.log(wrongDate.toISOString());     // 1970-01-20T17:27:47.200Z (WRONG!)

// ✅ CORRECT: Check and convert properly
const secondsTimestamp = 1704067200;
const correctDate = new Date(secondsTimestamp * 1000);
console.log(correctDate.toISOString());   // 2024-01-01T00:00:00.000Z (CORRECT!)

Armadilha 2: o mês tem indexação zero

// ❌ WRONG: Using 1-12 for months
const wrongDate = new Date(2024, 1, 1);  // Creates Feb 1, not Jan 1
console.log(wrongDate.toDateString());   // Thu Feb 01 2024

// ✅ CORRECT: Use 0-11 for months
const correctDate = new Date(2024, 0, 1);  // Creates Jan 1
console.log(correctDate.toDateString());   // Mon Jan 01 2024

Armadilha 3: Problemas de fuso horário com strings de data

// Different string formats behave differently!

// ISO 8601 with 'Z' - always UTC
const utcDate = new Date('2024-01-01T00:00:00Z');
console.log(utcDate.toISOString());  // 2024-01-01T00:00:00.000Z

// ISO 8601 without 'Z' - treated as local timezone
const localDate = new Date('2024-01-01T00:00:00');
console.log(localDate.toISOString());  // Depends on your timezone

// Date-only format - treated as local timezone at midnight
const dateOnly = new Date('2024-01-01');
console.log(dateOnly.toISOString());  // Usually local midnight

// ✅ BEST PRACTICE: Always use ISO 8601 with 'Z' for UTC
const safeDate = new Date('2024-01-01T00:00:00.000Z');

Armadilha 4: datas inválidas

// Invalid dates can cause silent errors
const invalidDate = new Date('not a date');
console.log(invalidDate);                 // Invalid Date
console.log(invalidDate.getTime());       // NaN

// ✅ BEST PRACTICE: Always validate
function isValidDate(date) {
    return date instanceof Date && !isNaN(date.getTime());
}

const date1 = new Date('2024-01-01');
const date2 = new Date('invalid');

console.log(isValidDate(date1));  // true
console.log(isValidDate(date2));  // false

Passo 7: Exemplos Práticos

Exemplo 1: Exibir formato "Tempo atrás"

function timeAgo(timestamp) {
    const now = Date.now();
    const secondsAgo = Math.floor((now - timestamp) / 1000);

    if (secondsAgo < 60) {
        return `${secondsAgo} seconds ago`;
    } else if (secondsAgo < 3600) {
        const minutes = Math.floor(secondsAgo / 60);
        return `${minutes} minute${minutes > 1 ? 's' : ''} ago`;
    } else if (secondsAgo < 86400) {
        const hours = Math.floor(secondsAgo / 3600);
        return `${hours} hour${hours > 1 ? 's' : ''} ago`;
    } else {
        const days = Math.floor(secondsAgo / 86400);
        return `${days} day${days > 1 ? 's' : ''} ago`;
    }
}

// Usage
console.log(timeAgo(Date.now() - 30000));      // "30 seconds ago"
console.log(timeAgo(Date.now() - 300000));     // "5 minutes ago"
console.log(timeAgo(Date.now() - 7200000));    // "2 hours ago"
console.log(timeAgo(Date.now() - 172800000));  // "2 days ago"

Exemplo 2: manipulador de resposta da API

// Typical API response with timestamps
const apiResponse = {
    created_at: 1704067200,     // Seconds
    updated_at: 1704153600000,  // Milliseconds (mixed precision!)
    expires_at: "2024-01-10T00:00:00Z"  // ISO 8601 string
};

// Convert all to Date objects
function parseApiTimestamps(response) {
    return {
        created: new Date(response.created_at * 1000),  // Convert seconds
        updated: new Date(response.updated_at),          // Already milliseconds
        expires: new Date(response.expires_at)           // Parse ISO string
    };
}

const dates = parseApiTimestamps(apiResponse);
console.log('Created:', dates.created.toLocaleDateString());
console.log('Updated:', dates.updated.toLocaleDateString());
console.log('Expires:', dates.expires.toLocaleDateString());

Exemplo 3: Validador de intervalo de datas

function isWithinRange(timestamp, startDate, endDate) {
    const date = new Date(timestamp);
    const start = new Date(startDate);
    const end = new Date(endDate);

    return date >= start && date <= end;
}

// Usage
const eventTimestamp = 1704067200000;  // Jan 1, 2024
const rangeStart = '2024-01-01';
const rangeEnd = '2024-12-31';

console.log(isWithinRange(eventTimestamp, rangeStart, rangeEnd));  // true

Bibliotecas populares para casos de uso avançados

Para aplicativos de produção, considere estas bibliotecas:

date-fns (recomendado)

import { format, parseISO, formatDistance } from 'date-fns';

// Format timestamp
const timestamp = 1704067200000;
const formatted = format(timestamp, 'PPP');
console.log(formatted);  // "Jan 1st, 2024"

// Time ago
const distance = formatDistance(timestamp, Date.now(), { addSuffix: true });
console.log(distance);  // "2 days ago"

Luxon (moderno, compatível com fuso horário)

import { DateTime } from 'luxon';

// From timestamp
const dt = DateTime.fromMillis(1704067200000);
console.log(dt.toISO());  // "2024-01-01T00:00:00.000Z"

// Timezone conversion
const tokyo = dt.setZone('Asia/Tokyo');
console.log(tokyo.toFormat('yyyy-MM-dd HH:mm:ss'));

Resumo

Você aprendeu como:

• ✅ Obtenha carimbos de data/hora atuais com Date.now()
• ✅ Converta carimbos de data / hora em objetos de data
• ✅ Converta objetos de data de volta em carimbos de data/hora
• ✅ Formatar datas para exibição
• ✅ Lidar com diferentes precisões de carimbo de data/hora
• ✅ Trabalhar com fusos horários
• ✅ Evite armadilhas comuns

Ferramentas relacionadas

Pratique o que você aprendeu com nossas ferramentas gratuitas:

• Unix Timestamp Converter - Conversão interativa de carimbo de data/hora
• Current Timestamp - Obtenha a hora atual em vários formatos
• JavaScript Timestamp Helper - Ferramentas específicas para JavaScript
• Conversor de carimbo de data e hora em lote - Converta vários carimbos de data e hora

Próximas etapas

• Saiba mais sobre Níveis de precisão de carimbo de data/hora
• Explore Compreendendo os fusos horários
• Leia sobre O problema do ano 2038

---

Última atualização: janeiro de 2025