JavaScript: Datas e Horas
No desenvolvimento web, entender e manipular datas e horas é essencial para criar aplicações dinâmicas e centradas no utilizador com JavaScript.
Introdução ao Objeto Date do JavaScript
Compreender e manipular datas e horas é fundamental para criar aplicações web dinâmicas. O JavaScript disponibiliza um objeto Date integrado para lidar com essas tarefas. Este guia explica como criar datas, ler e alterar os seus componentes, formatá-las e realizar aritmética de datas — com exemplos executáveis ao longo do texto.
Internamente, um Date é apenas um número: a contagem de milissegundos desde o Unix epoch (00:00:00 UTC em 1 de janeiro de 1970). Todos os outros recursos são construídos sobre esse único número, portanto boa parte da lógica de datas se resume a matemática de números comum.
Criando Objetos Date
Existem quatro formas comuns de instanciar um Date, cada uma para um tipo de entrada diferente.
// 1. Current date and time (no arguments)
const now = new Date();
// 2. From a millisecond timestamp (epoch = 0)
const epoch = new Date(0); // 1970-01-01T00:00:00.000Z
// 3. From a date string (ISO 8601 is the only reliably portable format)
const parsed = new Date("2024-01-01T00:00:00");
// 4. From individual components: year, monthIndex, day, hours, minutes, seconds
const detailed = new Date(2024, 0, 1, 15, 30, 0); // Jan 1, 2024, 15:30:00O mês é indexado a partir de 0. Na forma de componentes, janeiro é 0, fevereiro é 1, … dezembro é 11. O dia do mês, por sua vez, é baseado em 1. Esse desvio de índice é o erro mais comum com Date. A mesma indexação em 0 se aplica a getMonth() e setMonth().
Análise de strings ISO vs. outros formatos
Apenas o formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) tem garantia de ser interpretado da mesma forma em todos os motores JavaScript. Uma string de data simples como "2024-01-01" é tratada como meia-noite UTC, enquanto "2024-01-01T00:00:00" (sem Z) é tratada como hora local. Outros formatos (por ex., "01/02/2024") dependem da implementação — evite-os.
Obtendo Componentes de Data e Hora
Com um Date em mãos, você pode ler cada parte com um método get*. Esses métodos retornam valores em hora local (veja Trabalhando com Fusos Horários para as variantes UTC).
Definindo Componentes de Data e Hora
Cada método get* possui um método set* correspondente que modifica a data no lugar. Os objetos Date são mutáveis — o set* altera o original em vez de retornar uma nova data.
Autocorreção (transbordamento com roll over)
Se você definir um valor fora do intervalo, o Date o normaliza silenciosamente — sem lançar erro. Definir o dia 32 de janeiro avança para fevereiro. Isso é bastante útil para aritmética: para somar 5 dias, basta adicionar 5 a getDate() e deixar a data transbordar.
Timestamps: getTime e Date.now
getTime() retorna a data como um timestamp em milissegundos, e o método estático Date.now() retorna o timestamp atual sem criar um objeto. Os timestamps são a maneira mais fácil de comparar datas ou medir o tempo decorrido.
Trabalhando com Fusos Horários
Um Date armazena um único instante UTC; os métodos get* leem esse valor no fuso horário local do ambiente. Use as variantes getUTC* para ler o valor UTC, e a API Intl (via toLocaleString) para renderizar em qualquer outro fuso.
Formatando Datas e Horas
Para produzir uma string legível por máquina, use toISOString(); para saída legível por humanos, toLocaleDateString() / toLocaleTimeString() respeitam o locale do utilizador. Para um layout totalmente personalizado, monte as partes manualmente (lembrando de getMonth() + 1).
toISOString() é exatamente o que JSON.stringify usa para datas, portanto um Date sobrevive a uma viagem de ida e volta para texto e de volta. Veja Trabalhando com JSON para saber como recriar strings ISO em objetos Date.
Explore Bibliotecas Modernas de Data: Embora o objeto Date nativo do JavaScript ofereça manipulação básica de datas, bibliotecas como date-fns e Luxon fornecem utilitários robustos para cálculos complexos, internacionalização e tratamento de fusos horários. O Moment.js foi oficialmente descontinuado; considere estas alternativas modernas para novos projetos.
Aritmética de Datas e Diferenças
Como um Date é essencialmente um número, subtrair uma data de outra fornece a diferença em milissegundos. O operador de subtração converte cada data via getTime(), portanto endDate - startDate funciona diretamente. Divida pelos milissegundos em um dia para obter a contagem de dias.
Para adicionar tempo, prefira a mutação com set* (que trata corretamente o transbordamento de mês/ano) em vez de somar milissegundos brutos, pois este ignora as mudanças de horário de verão.
Aproveitando Bibliotecas para Manipulações Avançadas
Para manipulações e formatações de datas mais complexas, diversas bibliotecas podem simplificar essas tarefas. Bibliotecas como date-fns e Luxon oferecem funcionalidades estendidas além do objeto Date nativo, facilitando tarefas como análise, internacionalização e tratamento avançado de fusos horários. Além disso, a Temporal API está atualmente em desenvolvimento para eventualmente substituir o objeto Date nativo por uma solução mais robusta, imutável e ciente de fusos horários.
Conclusão
Dominar o objeto Date em JavaScript é essencial para desenvolver aplicações web dinâmicas que interagem com datas e horas de forma eficaz. Por meio da criação, leitura, definição e formatação de datas, os desenvolvedores podem construir recursos sofisticados que respondem ao tempo real. Seja para agendar eventos, calcular durações ou exibir cronogramas, as capacidades oferecidas pelo objeto Date do JavaScript e pelas diversas bibliotecas de terceiros fazem da manipulação de datas e horas uma ferramenta poderosa no arsenal do desenvolvimento web.