Hora da consulta

O JavaScript tem um objeto incorporado, Date, que armazena a data e a hora e fornece métodos para as gerir.

Criação

Um objeto Date é uma instância da classe Date. Pode ser criado sem passar quaisquer argumentos à função construtora. Isto resulta num objeto Date que representa a data e a hora atuais:

const now = new Date();
// => Thu Apr 14 2022 11:46:08 GMT+0530 (India Standard Time)
// Shows current day, date and time (in your time zone).

Timestamp Unix (número)

Se for passado um número, este será interpretado como um timestamp. Um timestamp é um número inteiro que representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC+0.

const epoch = new Date(0);
// Thu Jan 01 1970 01:00:00 GMT+0100 (Central European Standard Time)

const another = new Date(1749508766627);
// Tue Jun 10 2025 00:39:26 GMT+0200 (Central European Summer Time)

Podes esperar que new Date(0) gere o objeto de data "mais antigo", mas o JavaScript converte a data para o teu fuso horário local, o que significa que só quem está num fuso horário GMT / UTC+0 é que obtém realmente o valor do Unix epoch.

Timestamp ISO 8601 (string)

Podes passar um valor do tipo string que representa uma data à função construtora Date. O único formato consistente entre implementações é a versão simplificada das chamadas strings de timestamp ISO 8601, reconhecidas e normalizadas internacionalmente.

Um momento no tempo em UTC tem este aspeto:

YYYY-MM-DDTHH:mm:ss.mssZ
YYYYMMDDTHHmmss.mssZ

Em que ocorrem as seguintes substituições:

A letra Z literal indica UTC (sem fuso horário, sem horário de verão).

Como existem valores predefinidos para a maioria dos componentes, é válido omitir partes no fim:

YYYY-MM-DD

Por predefinição, assume a hora 00:00:00.000.

Se o timestamp não terminar em Z nem terminar com +HH:mm ou -HH:mm (que indicam um desvio de fuso horário), por razões históricas aplica-se o seguinte:

Quando o desvio de fuso horário está ausente, as formas apenas com data são interpretadas como uma hora UTC e as formas com data e hora são interpretadas como uma hora local. A interpretação como hora UTC deve-se a um erro histórico da especificação, que não era coerente com a ISO 8601, mas que não pôde ser alterado devido à compatibilidade com a web. Vê Broken Parser: um problema de realidade da web.

Objeto Date

Também podes usar um objeto de data já existente como argumento da função construtora. Isto cria uma cópia do objeto Date existente, com a mesma data e a mesma hora.

const t1 = new Date();
const t2 = new Date(t1);
// Values of t1 and t2 will be the same.

Fornecer valores individuais dos componentes de data e hora

Podes criar um objeto de data que representa apenas uma data passando três números. Podes criar um objeto de data que representa uma data e uma hora passando 6 números.

const date1 = new Date(95, 11, 17);
// Creates Date for Dec 17 1995 00:00 if your local timezone is equivalent to UTC.

const date2 = new Date(2013, 12, 5, 13, 24, 0);
// Creates Date for Jan 5 2014 13:24 if your local timezone is equivalent to UTC.

O segundo valor é o month, que começa em 0 para janeiro e vai até 11 para dezembro.

Date.parse()

Podes encontrar menções ou referências a uma função de análise de datas, Date.parse. Como esta função tem apenas alguns invariantes (verdades) e como o resto da implementação não está especificado (e, por isso, não é padrão), não deves usá-la.

Acesso aos componentes de Date

Existem vários métodos nos objetos de data que devolvem os componentes da data:

getFullYear(); // Get the year (4 digits)
getMonth(); // Get the month, from 0 to 11.
getDate(); // Get the day of month, from 1 to 31.
getHours(); // Get the hour in a 24 clock, from 0 to 23
getMinutes(); // Get the minutes, from 0 to 59
getSeconds(); // Get the seconds, from 0 to 59
getMilliseconds(); // Get the milliseconds, from 0 and 999
getDay(); // Get the day of week, from 0 (Sunday) to 6 (Saturday).

Cada um destes tem uma variante set correspondente (por exemplo, setFullYear) para atualizar o valor. Qualquer valor que transborde passa para o componente seguinte:

const date = new Date('2025-02-28T12:42:00Z');
// => Fri Feb 28 2025 13:42:00 GMT+0100 (Central European Standard Time)

date.setDate(29);
// there was no February 29th in 2025.

date.getDate();
// => 1

date.toString();
// => Sat Mar 01 2025 13:42:00 GMT+0100 (Central European Standard Time)

Existem variantes UTC de todos os métodos, que ignoram o fuso horário local.

Converter a partir de uma data

Os objetos de data têm um método getTime() que devolve o timestamp UNIX em milissegundos, ou seja, o número de milissegundos desde a meia-noite do início de 1 de janeiro de 1970, UTC. Além disso, existe o método toISOString(), que converte um objeto de data numa string de timestamp ISO 8601.

Comparar datas

Os operadores maior que (>), maior ou igual (>=), menor que (<) e menor ou igual (<=) podem ser usados diretamente entre duas datas, ou entre uma data e um número. Isto funciona porque o JavaScript tenta converter a data num valor primitivo.

Não é possível comparar datas com os operadores de igualdade (== e ===), mas podes comparar o resultado de .getTime().