Converta uma string em uma data em JavaScript

Strings de data vindas de um banco de dados ou de uma API continuam sendo strings, então um seletor de data ou um cálculo pode precisar de um objeto JavaScript Date. A conversão adequada depende do formato de entrada e de o fuso horário estar explícito. Passe a string como argumento para new Date(dateString) para analisar uma string padrão compatível; a chamada sem argumentos new Date() cria uma data com a hora atual. Use Date.parse() quando precisar de milissegundos ou analise os componentes manualmente quando conhecer o formato personalizado.

Este guia apresenta três opções práticas:

• Passe uma string de data compatível para new Date(dateString) para criar um objeto Date.
• Chame Date.parse() quando um valor numérico em milissegundos for útil.
• Divida uma string em componentes antes de criar um Date, quando conhecer o formato personalizado.

Use new Date() para converter uma string em uma data no JavaScript

O construtor new Date(dateString) aceita uma string de data compatível e retorna um objeto Date. Este carimbo de data e hora ISO 8601 inclui Z, que indica UTC. A chamada de toISOString() retorna esse horário em UTC, independentemente do fuso horário local da máquina.

const dateString = '2024-05-23T14:30:00Z';
const date = new Date(dateString);

console.log(date instanceof Date);
console.log(date.toISOString());

Uma string que contém apenas uma data, como 2024-05-23, é interpretada como UTC, enquanto uma string de data e hora sem deslocamento de fuso horário é interpretada como horário local. Quando a origem representa um instante específico, use uma string padrão com um deslocamento explícito para que a interpretação não dependa do fuso horário local da máquina.

Os formatos fora do padrão de data e hora não são definidos de maneira consistente entre as implementações de JavaScript. Uma string aceita por um navegador ou ambiente de execução pode ser interpretada de outra forma em outro lugar. Antes de usar o objeto resultante, verifique-o com Number.isNaN(date.getTime()). Uma análise bem-sucedida também não garante que a string siga o formato ou as regras de calendário exigidos pela sua aplicação; valide esses requisitos separadamente. As legendas visíveis nos exemplos mantidos sem alterações permanecem em inglês.

Use Date.parse() para analisar uma string de data no JavaScript

Date.parse() retorna o número de milissegundos desde a época Unix para uma string de data que pôde ser analisada, ou NaN quando não consegue analisar a entrada. O resultado é um número, não um objeto Date. Para um valor recebido de uma API, analise-o e crie uma data a partir do resultado numérico quando precisar de um objeto:

const apiValue = '2019-01-01T12:30:00.000Z';
const milliseconds = Date.parse(apiValue);

console.log(typeof milliseconds);
console.log(Number.isNaN(milliseconds) ? 'not parsed' : new Date(milliseconds).toISOString());

Number.isNaN() detecta o sinal de falha na análise, mas não valida completamente um formato específico da aplicação. Um ambiente de execução pode aceitar um valor que a sua aplicação deveria rejeitar. Se a entrada precisar seguir um padrão específico, verifique esse padrão e os valores de calendário antes de usar o resultado da análise.

Divida uma string e converta-a em uma data no JavaScript

Quando a entrada usa um formato personalizado conhecido, divida-a de acordo com esse formato e passe os componentes ao construtor Date com vários argumentos. Este exemplo espera DD-MM-YYYYTHH:mm:ss; o construtor interpreta os componentes como horário local. Ele retorna null a menos que os componentes formem uma data válida no calendário.

function parseKnownDate(value) {
  if (typeof value !== 'string') {
    return null;
  }

  const dateTimeParts = value.split('T');
  if (dateTimeParts.length !== 2) {
    return null;
  }

  const [datePart, timePart] = dateTimeParts;
  if (
    !/^\d{2}-\d{2}-\d{4}$/.test(datePart) ||
    !/^\d{2}:\d{2}:\d{2}$/.test(timePart)
  ) {
    return null;
  }

  const dateParts = datePart.split('-');
  const timeParts = timePart.split(':');
  if (dateParts.length !== 3 || timeParts.length !== 3) {
    return null;
  }

  const [day, month, year] = dateParts.map(Number);
  const [hours, minutes, seconds] = timeParts.map(Number);

  if (![day, month, year, hours, minutes, seconds].every(Number.isInteger)) {
    return null;
  }

  // The multi-argument constructor treats years 0–99 as 1900–1999.
  // setFullYear preserves the supplied year, including values in that range.
  const date = new Date(0);
  date.setFullYear(year, month - 1, day);
  date.setHours(hours, minutes, seconds, 0);

  if (
    date.getFullYear() !== year ||
    date.getMonth() !== month - 1 ||
    date.getDate() !== day ||
    date.getHours() !== hours ||
    date.getMinutes() !== minutes ||
    date.getSeconds() !== seconds
  ) {
    return null;
  }

  return date;
}

const date = parseKnownDate('21-03-2020T11:20:30');
console.log(date === null ? 'not a valid date' : date.toString());

As divisões dependem da ordem de componentes indicada; ajuste-as quando a origem usar outra ordem ou separador. O argumento do mês começa em zero, por isso o código subtrai um do número do mês usado normalmente. Os métodos de definição usam o horário local e podem normalizar valores fora dos limites; comparar os componentes resultantes com os valores analisados detecta essa normalização. A data inicial se baseia no fuso horário local, portanto esse método cria um valor em horário local, não um carimbo de data e hora UTC. Se puder haver anos de 0 a 99, setFullYear() evita o tratamento especial desses anos pelo construtor com vários argumentos. Este exemplo verifica componentes inteiros e a normalização de datas inválidas; aplicações com regras de entrada mais rigorosas também devem verificar o padrão exato da string e os intervalos permitidos para cada campo.

Conclusão

Passe uma string de data compatível para new Date(dateString) para criar um objeto Date; de preferência, use um deslocamento explícito quando ela representar um instante específico. A chamada sem argumentos new Date() cria uma data com a hora atual; ela não analisa uma string. Use Date.parse() quando precisar de milissegundos desde a época Unix ou do sinal de falha NaN; quando precisar de um objeto Date, passe um número analisado com sucesso para new Date(milliseconds). Para um formato personalizado conhecido, analise e valide os componentes antes de criar uma data em horário local. A visão geral do ISO 8601 descreve a representação de data e hora usada por muitas APIs.