Trabalhando com Datas em JavasScrit

Trabalhar com datas e horários é uma necessidade frequente no desenvolvimento web. No JavaScript, o objeto nativo Date fornece uma série de métodos que permitem criar, acessar e manipular datas e horas de forma eficiente. Neste artigo, vamos explorar as principais funcionalidades do Date, apresentando exemplos práticos que vão te ajudar a entender como lidar com datas no dia a dia da programação.

Criando uma data

Para criar um objeto de data em JavaScript, utilizamos o construtor new Date(). Quando chamado sem nenhum parâmetro, ele gera um objeto que representa a data e hora atual, baseada no relógio do sistema.

let data = new Date();
console.log(data); // 2025-06-02T19:29:06.438Z

O construtor Date aceita diferentes tipos de argumentos. Um deles é um número inteiro que representa o timestamp, ou seja, a quantidade de milissegundos decorridos desde 1º de janeiro de 1970, às 00:00:00 UTC — conhecido como Época Unix. Valores positivos correspondem a datas posteriores a essa referência, enquanto valores negativos representam datas anteriores a 01/01/1970.

// horas * minutos * segundos * milisegundos = 1 dias

let umDiaAntes = new Date( - 24 * 60 * 60 * 1000); 
let inicio = new Date( 0 );
let umDiaDepois = new Date( 24 * 60 * 60 * 1000);

console.log(umDiaAntes); // 1969-12-31T00:00:00.000Z
console.log(inicio); // 1970-01-01T00:00:00.000Z
console.log(umDiaDepois); // 1970-01-02T00:00:00.000Z

Também é possível obter o timestamp de um objeto Date utilizando o método .getTime().

let agora = new Date();

console.log(agora.getTime()); // 1748893183318

Quando passamos uma string como argumento para o construtor Date, ela é convertida para uma data. O JavaScript segue, por padrão, o formato ISO 8601, que tem a seguinte estrutura:

YYYY-MM-DDTHH:mm:ss.sssZ

Onde:

  • YYYY – Ano com quatro dígitos (de 0000 a 9999).
  • MM – Mês com dois dígitos (de 01 a 12). O valor padrão é 01
  • DD – Dia do mês com dois dígitos (de 01 a 31). O valor padrão é 01.
  • T – Um caractere literal que separa a data da hora. Ele é obrigatório quando a parte de hora é informada.
  • HH – Hora no formato de 24 horas (de 00 a 23). Existe um caso especial onde 24:00:00 é válido e representa a meia-noite. O valor padrão é 00.
  • mm – Minutos, com dois dígitos (de 00 a 59). O valor padrão é 00.
  • ss – Segundos, com dois dígitos (de 00 a 59). O valor padrão é 00.
  • sss – Milissegundos, com três dígitos (de 000 a 999). O valor padrão é 000.
  • Z – Indica o fuso horário. Pode ser o literal Z (que significa UTC) ou um deslocamento no formato +HH:mm ou -HH:mm, representando a diferença em relação ao horário UTC.

Nem todas as partes do formato precisam ser informadas — elas podem ser omitidas. Caso a string não siga exatamente o padrão ISO 8601, o construtor Date tentará interpretar a data de outras formas. No entanto, é importante destacar que formatos diferentes podem gerar resultados inconsistentes, dependendo do ambiente ou do navegador.

let data1 = new Date('2024-03-10');
let data2 = new Date('2024-03-10T15:30:31');
let data3 = new Date('2023-12-07T00:30:31.000Z');
let data4 = new Date('2023-12-07T00:30:31-03:00');
let data5 = new Date('01/01/2025');
let data6 = new Date('01/01/2025 10:30');
let data7 = new Date('Wed Jan 01 2025 00:00:00 GMT-0300');
let data8 = new Date('abc');

console.log(data1); // 2024-03-10T00:00:00.000Z
console.log(data2); // 2024-03-10T18:30:31.000Z
console.log(data3); // 2023-12-07T00:30:31.000Z
console.log(data4);// 2023-12-07T03:30:31.000Z
console.log(data5);// 2025-01-01T03:00:00.000Z
console.log(data6);// 2025-01-01T13:30:00.000Z
console.log(data7);// 2025-01-01T03:00:00.000Z
console.log(data8);// Invalid Date

Também é possível criar uma data passando seus componentes separadamente como números para o construtor Date. A ordem dos parâmetros é:

new Date(year, month, day, hours, minutes, seconds, milliseconds)

Dos parâmetros, apenas os dois primeiros — ano (year) e mês (month) — são obrigatórios. Os demais são opcionais e, caso não sejam informados, assumem o valor zero (ou um, no caso do dia).

🛑 Atenção: o mês é baseado em índice zero, ou seja:

  • 0 representa janeiro
  • 1 representa fevereiro
  • …
  • 11 representa dezembro
let data1 = new Date(2025, 1);
let data2 = new Date(2025, 1 , 15);
let data3 = new Date(2025, 1 , 15, 10, 30, 21);

console.log(data1); // 2025-02-01T03:00:00.000Z
console.log(data2); // 2025-02-15T03:00:00.000Z
console.log(data3); // 2025-02-15T13:30:21.000Z

Observação: Um comportamento interessante do construtor Date é que ele faz ajustes automáticos quando algum valor está fora do intervalo válido. Por exemplo, se informarmos o dia 32 para um mês que possui apenas 31 dias, o JavaScript automaticamente ajusta a data para o dia 1 do mês seguinte. Esse comportamento também se aplica para horas, minutos e outros componentes que excedam seus limites.

let data1 = new Date(2025, 0 , 32);
let data2 = new Date(2025, 0 , 0);
let data3 = new Date(2025, 12 , 1);
let data4 = new Date(2025, 11 , 1, 24);

console.log(data1); // 2025-02-01T03:00:00.000Z
console.log(data2); // 2024-12-31T03:00:00.000Z
console.log(data3); // 2026-01-01T03:00:00.000Z
console.log(data4); // 2025-12-02T03:00:00.000Z

Acessando os componentes da data

A classe Date nos fornece métodos para acessar cada uma das partes.

  • getFullYear(): Retorna o ano completo com quatro dígitos. Ex.: 2025
  • getMonth(): Retorna o mês, onde janeiro é 0 e dezembro é 11. ⚠️ Atenção: esse índice começa em zero!
  • getDate(): Retorna o dia do mês, de 1 a 31. retorna o dia do mês, de 1 até 31. Cuidado: nome do método não é muito intuitivo, e pode ser confundido com o método getDay().
  • getDay(): Retorna o dia da semana, onde: 0 = Domingo, 1 = Segunda, …, 6 = Sábado
  • getHours(): Retorna a hora, no formato de 0 a 23.
  • getMinutes(): Retorna os minutos, de 0 a 59.
  • getSeconds(): Retorna os segundos, de 0 a 59.
  • getMilliseconds(): Retorna os milissegundos, de 0 a 999.
  • getTime(): Retorna o timestamp, ou seja, o valor numérico em milissegundos desde 01/01/1970 (Epoch).
  • getTimezoneOffset(): Retorna o deslocamento do fuso horário, em minutos, em relação ao UTC.
    ➝ Ex.: Se você está no horário de Brasília (UTC-3), ele retorna 180.
let data = new Date('2025-02-03T10:11:12.123-03:00');

console.log(data.getFullYear()); // 2025
console.log(data.getMonth()); // 1 - lembre-se os meses começam em 0 então 1 é fevereiro aqui
console.log(data.getDate()); // 3
console.log(data.getHours()); // 10
console.log(data.getMinutes()); // 11
console.log(data.getSeconds()); // 12
console.log(data.getMilliseconds()); // 123
console.log(data.getDay()); // 1
console.log(data.getTime()); // 1738588272123
console.log(data.getTimezoneOffset()); // 180

Os métodos que vimos até aqui consideram sempre o fuso horário local, definido no ambiente onde o código está sendo executado ou na string da data. Porém, se precisarmos acessar os componentes da data no horário de referência UTC — equivalente ao fuso UTC+0 —, a classe Date oferece uma versão de cada método com o sufixo UTC.

Basta adicionar UTC ao nome do método, como por exemplo:

  • getUTCFullYear()
  • getUTCHours()
  • getUTCMinutes()

Esses métodos retornam os valores da data e hora sem considerar o fuso local, sempre com base no horário UTC.

let data = new Date('2025-02-03T10:11:12.123-03:00');

console.log(data.getHours()); // 10
console.log(data.getUTCHours()); // 13

Alterando as datas

Para alterar uma data, a classe Date disponibiliza diversos métodos sets, permitindo modificar individualmente os diferentes componentes da data, como ano, mês, dia, horas, minutos, segundos e milissegundos.

  • setFullYear(year, [month], [date])
  • setMonth(month, [date])
  • setDate(date)
  • setHours(hour, [min], [sec], [ms])
  • setMinutes(min, [sec], [ms])
  • setSeconds(sec, [ms])
  • setMilliseconds(ms)
  • setTime(milliseconds)

Alguns métodos de alteração permitem modificar mais de um componente da data ao mesmo tempo. Por exemplo, o método setMonth() altera o mês e, opcionalmente, também pode definir o dia do mês se um segundo parâmetro for informado.

let data = new Date('2025-02-03T10:11:12.123-03:00');

data.setFullYear(2026);
data.setMonth(0);
data.setDate(25);
data.setHours(16);
data.setMinutes(20);
data.setSeconds(5);
data.setMilliseconds(321);

console.log(data); // 2026-01-25T19:20:05.321Z

Assim como os métodos gets, os métodos sets também possuem uma verser UTC.

let data = new Date('2025-02-03T10:11:12.123-03:00');

data.setHours(16);
console.log(data); // 2025-02-03T19:11:12.123Z

data.setUTCHours(16);
console.log(data); // 2025-02-03T16:11:12.123Z

Como no construtor, os métodos set também aplicam a auto-correção de datas. Isso significa que, ao definir valores fora dos limites convencionais — como um dia 32 ou um mês 13 — o JavaScript ajusta automaticamente para a data correta. Esse comportamento nos permite somar ou subtrair meses, dias, horas e outros componentes de forma simples e prática.

let data = new Date('2025-02-03T10:11:12.123-03:00');

data.setDate( data.getDate() + 7); // adiciona 7 dias a data
console.log(data); // 2025-02-10T13:11:12.123Z

data.setMonth( data.getMonth() - 3); // subtrai 3 meses
console.log(data); // 2024-11-10T13:11:12.123Z

Importante: os métodos set são mutáveis, ou seja, eles alteram diretamente o objeto Date original. Se quisermos preservar a data inicial, é necessário criar uma cópia do objeto antes de realizar qualquer modificação.

let data = new Date('2025-02-03T10:11:12.123-03:00');

let data10Dias = new Date( data.getTime() );

data10Dias.setDate( data10Dias.getDate() + 10);

console.log(data); // 2025-02-03T13:11:12.123Z
console.log(data10Dias); // 2025-02-13T13:11:12.123Z

Comparando Datas

Como objetos Date podem ser convertidos para valores numéricos — mais especificamente, para o timestamp em milissegundos desde 01/01/1970 — comparar datas em JavaScript se torna uma tarefa bastante simples.

let data1 = new Date('2024-01-30T15:13:12.123-03:00');
let data2 = new Date('2025-02-03T10:11:12.123-03:00');

if( data1 < data2 ){
    console.log("data 1 é anterior")
}

Diferença entre datas

Assim como a comparação entre datas é simples graças à conversão dos objetos Date em valores numéricos, calcular a diferença entre duas datas também é bem fácil. Basta subtrair uma data da outra, e o resultado será a diferença em milissegundos. A partir disso, com alguns cálculos, podemos converter esse valor para segundos, minutos, horas, dias ou qualquer outra unidade de tempo.

let data1 = new Date('2024-01-30T15:13:12.123-03:00');
let data2 = new Date('2025-02-04T10:11:12.123-03:00');

let mili = data2 - data1;
let segundos = (data2 - data1) / 1000;
let minutos = (data2 - data1) / (60 * 1000);
let horas = (data2 - data1) / (60 * 60 * 1000);
let dias = (data2 - data1) / (24 * 60 * 60 * 1000);

console.log(mili); // 32036280000
console.log(segundos); // 32036280
console.log(minutos); // 533938
console.log(horas); // 8898.966666666667
console.log(dias); // 370.79027777777776

Formatando Datas

A classe Date oferece alguns métodos que permitem formatar datas de forma simples e direta.

toLocaleDateString(): retorna a data formatada conforme as convenções do locale (idioma e região) especificado.

let hoje = new Date();
console.log(hoje.toLocaleDateString("pt-BR")); // 03/06/2025
console.log(hoje.toLocaleDateString("en-US")); // 6/3/2025

toISOString(): toISOString(): retorna a data representada no padrão ISO 8601, no formato UTC.

let agora= new Date();
console.log( agora.toISOString() ); // 2025-06-03T13:45:08.018Z

Para criar uma formatação mais personalizada de datas, podemos utilizar o objeto Intl.DateTimeFormat. Ele permite formatar datas e horas levando em consideração a localidade, além de oferecer várias opções para customizar o formato de saída.

let agora = new Date();

const formater = new Intl.DateTimeFormat("pt-BR", {
    dateStyle: "short",
    timeStyle: "short",
  });

console.log( formater.format(agora) ); // 03/06/2025, 10:58

const formater2 = new Intl.DateTimeFormat("pt-BR", {
    month: 'long',
    day: '2-digit'
  });

console.log( formater2.format(agora)); // 03 de junho

Abaixo segue as principais opções de formatação disponíveis:

weekday: Exibe o dia da semana.

  • Valores possíveis: "narrow", "short", "long"
  • Exemplo: "segunda-feira"

year: Exibe o ano.

  • Valores possíveis: "numeric", "2-digit"
  • Exemplo: "2025" ou "25"

month: Exibe o mês.

  • Valores possíveis: "numeric", "2-digit", "narrow", "short", "long"
  • Exemplo: "6", "06", "jun", "junho"

day: Exibe o dia do mês.

  • Valores possíveis: "numeric", "2-digit"
  • Exemplo: "3" ou "03"

hour, minute, second: Exibem as respectivas partes do tempo.

  • Valores possíveis: "numeric", "2-digit"
  • Exemplo: "16" ou "04"

hour12: Define o uso de formato de 12 horas.

  • Valores possíveis: true, false
  • Exemplo: true para formato AM/PM

dayPeriod: Exibe o período do dia.

  • Valores possíveis: "narrow", "short", "long"
  • Exemplo: "AM", "PM"

fractionalSecondDigits: Define o número de dígitos para frações de segundo.

  • Valores possíveis: 1, 2, 3

dateStyle e timeStyle: Atalhos para definir estilos de data e hora.

  • Valores possíveis: "full", "long", "medium", "short"

Conclusão

A classe Date do JavaScript é uma ferramenta robusta e essencial para o trabalho com datas e horários. Apesar de algumas peculiaridades e métodos que podem gerar confusão, com prática e cuidado é perfeitamente possível dominá-la e utilizá-la de forma eficiente em seus projetos.

T++