Objeto `Date`

Este artigo explica o objeto Date.

Explicaremos o objeto Date passo a passo, desde os mecanismos básicos até as operações mais comuns no trabalho prático, com exemplos concretos.

YouTube Video

Objeto Date

O que é o objeto Date?

O objeto Date do JavaScript é um objeto padrão para manipulação de datas e horários. Internamente, ele gerencia data e hora com base no número de milissegundos decorridos desde 1º de janeiro de 1970, 00:00:00 UTC.

Primeiro, vamos criar um objeto Date representando a data e hora atual, e verificar seu conteúdo.

1const now = new Date();
2console.log(now);

• Este código cria um objeto Date que representa a data e hora atuais no momento da execução. O formato de exibição depende do ambiente de execução, como o navegador ou o sistema operacional.

Como criar um objeto Date

Objetos Date podem ser criados de várias formas, dependendo da sua necessidade. Um ponto particularmente importante e fácil de errar é que o argumento do construtor para mês começa em zero, ou seja, os meses começam no 0.

1const d1 = new Date();                     // Current date and time
2const d2 = new Date("2025-01-01");         // Create from an ISO date string
3const d3 = new Date(2025, 0, 1);           // January 1, 2025 (month is zero-based)
4const d4 = new Date(2025, 0, 1, 10, 30);   // January 1, 2025, 10:30
5
6console.log(d1, d2, d3, d4);

• Em new Date(ano, mês, dia), o campo mês significa que 0 é janeiro e 11 é dezembro. Se você não compreender esta especificação, pode acabar criando uma data com um mês de diferença sem querer, portanto, preste sempre atenção.

Obtendo cada elemento da data e hora

Você pode obter individualmente o ano, mês, dia, hora e dia da semana de um objeto Date. Todos os métodos para obter informações retornam valores numéricos.

1const date = new Date();
2
3console.log(date.getFullYear()); // Year
4console.log(date.getMonth());    // Month (0-based: 0 = January)
5console.log(date.getDate());     // Day of the month
6console.log(date.getHours());    // Hours
7console.log(date.getMinutes());  // Minutes
8console.log(date.getSeconds());  // Seconds
9console.log(date.getDay());      // Day of the week (0 = Sunday, 6 = Saturday)

• Assim como na criação, tome cuidado que o método getMonth() também começa em zero. Ao exibir, é comum adicionar 1 ao valor para ajustá-lo.
• getDay() retorna o dia da semana como um número. 0 representa domingo e 6 representa sábado.

Modificando datas e horários

Date é um objeto mutável, ou seja, você pode alterar seus valores depois. Essa característica é útil, mas você deve tomar cuidado com efeitos colaterais indesejados.

Você pode usar os métodos set para alterar os valores de um objeto Date existente.

1const date = new Date("2025-01-01");
2
3date.setFullYear(2026);
4date.setMonth(5);   // June
5date.setDate(15);
6
7console.log(date);

• O método setMonth() também começa em zero. O objeto original é modificado diretamente.

Adicionando e subtraindo datas

É comum realizar cálculos de datas usando milissegundos ou o método setDate(). Para cálculos baseados em dias, usar o setDate() é especialmente intuitivo e seguro.

1const date = new Date("2025-01-01");
2
3date.setDate(date.getDate() + 7);
4console.log(date);

• Neste exemplo, estamos calculando a data 7 dias após a data especificada. Mesmo que a soma ultrapasse para um novo mês, o ajuste é feito automaticamente.

Comparando objetos Date

Objetos Date podem ser comparados como números. Isso ocorre porque o valor interno em milissegundos é comparado.

1const a = new Date("2025-01-01");
2const b = new Date("2025-01-10");
3
4console.log(a < b);   // true
5console.log(a > b);   // false

• Se quiser determinar a ordem das datas, nenhuma conversão adicional é necessária. Você pode usar os operadores de comparação diretamente.

Trabalhando com timestamps (milissegundos)

O Date pode ser convertido para e a partir de números representando milissegundos (timestamps). Esse formato é frequentemente utilizado em APIs ou integrações com bancos de dados.

1const now = Date.now();
2console.log(now);
3
4const date = new Date(now);
5console.log(date);

• O método Date.now() retorna o horário atual em milissegundos. É muito útil quando você deseja armazenar ou comparar o valor como número.

Formatando datas como strings

Exibir um objeto Date como está geralmente resulta em um formato que pode não atender às suas necessidades. Portanto, você deve formatá-lo explicitamente de acordo com suas necessidades.

1const date = new Date("2025-01-01");
2
3const formatted = `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;
4console.log(formatted);

• Formatando manualmente desta forma, você pode controlar totalmente o formato de exibição. No trabalho prático, bibliotecas são frequentemente usadas para esse fim.

Diferença entre UTC e hora local

O objeto Date fornece métodos para manipular tanto hora local quanto UTC. É importante compreender corretamente essa diferença para integrações com servidores e compatibilidade internacional.

1const date = new Date();
2
3console.log(date.getHours());    // Local time (hours)
4console.log(date.getUTCHours()); // UTC time (hours)

• Os métodos getUTC* sempre retornam valores baseados em UTC. Tome cuidado especial ao manipular dados entre diferentes fusos horários.

Cuidados ao usar objetos Date

Date é conveniente, mas também possui alguns aspectos complicados. Em particular, o mês começando em zero e a mutabilidade costumam causar erros.

Vamos analisar exemplos específicos abaixo para ver os efeitos do fato de Date ser mutável.

1const original = new Date("2025-01-01");
2const copy = new Date(original);
3
4copy.setDate(10);
5
6console.log(original);
7console.log(copy);

• Se quiser manter a data e hora originais, sempre crie uma cópia. Apenas estar ciente desse ponto ajudará a evitar bugs indesejados.

Razões pelas quais Date é difícil de lidar e critérios para usar bibliotecas

O objeto Date oferece recursos suficientes como função padrão, mas há situações na prática em que pode ser difícil de usar. Questões típicas incluem meses e dias da semana começando do zero, a tendência de confundir horário local e UTC, e o fato de o objeto ser mutável. Esses problemas podem causar mais bugs à medida que o processamento de datas aumenta.

Date é suficiente para obter e comparar datas de forma simples, mas a legibilidade e a manutenção do código tendem a piorar com mais cálculos de datas ou formatações de exibição.

Se você tem requisitos como os seguintes, pode considerar usar bibliotecas de datas leves como dayjs ou date-fns.

• Você precisa lidar explicitamente com fusos horários
• Você precisa frequentemente realizar cálculos de datas ou intervalos
• Você deseja alterar o formato de exibição de forma flexível
• Você deseja manipular datas e horas de forma imutável

Resumo

Os objetos Date são a ferramenta mais fundamental para manipulação de datas e horários no JavaScript. Compreendendo suas peculiaridades e realizando corretamente a criação, consulta, cálculo e formatação, você pode utilizá-lo de forma segura em trabalhos reais.

Depois de dominar o básico, usar bibliotecas para datas conforme a necessidade é uma escolha prática.

Você pode acompanhar o artigo acima usando o Visual Studio Code em nosso canal do YouTube. Por favor, confira também o canal do YouTube.

YouTube Video