Trabalhando com datas e horas em TypeScript: guia completo

Trabalhando com datas e horas em TypeScript: do básico às técnicas avançadas

Gerenciar datas e horas é uma das tarefas principais no desenvolvimento web. Seja para exibir o horário de publicação, calcular prazos ou sincronizar dados com o servidor, o TypeScript oferece ferramentas poderosas para trabalhar com timestamps. Neste artigo, abordaremos todos os aspectos do trabalho com datas: desde a criação do objeto Date até manipulações complexas com fusos horários e formatação.

1. Fundamentos do trabalho com o objeto Date em TypeScript

No TypeScript, assim como no JavaScript, o objeto embutido Date é responsável pelo trabalho com datas. Graças à tipagem forte, o TypeScript ajuda a evitar erros ao passar dados incorretos.

Criando um objeto Date

Existem várias maneiras de criar uma instância de data:

// Data e hora atuaisconst now: Date = new Date();console.log(now); // Tue Oct 24 2023 14:30:00 GMT+0300

// Por milissegundos (Unix timestamp)const fromTimestamp: Date = new Date(1698153000000);

// A partir de uma string (ISO 8601)const fromString: Date = new Date("2023-10-24T12:00:00Z");

// A partir de componentes (ano, mês, dia, horas, minutos, segundos)const customDate: Date = new Date(2023, 9, 24, 14, 30, 0); // Meses são de 0 a 11!

Importante: Os meses em JavaScript/TypeScript são numerados de 0 (janeiro é 0, dezembro é 11). Esta é uma causa frequente de bugs.

Obtendo componentes da data

Para extrair partes individuais da data, usamos os getters:

const date: Date = new Date();const year: number = date.getFullYear();      // 2023const month: number = date.getMonth();         // 9 (outubro)const day: number = date.getDate();            // 24const hours: number = date.getHours();         // 14const minutes: number = date.getMinutes();     // 30const seconds: number = date.getSeconds();     // 0const dayOfWeek: number = date.getDay();       // 2 (terça-feira, 0 - domingo)

2. Formatação e exibição de datas

A saída padrão Date.toString() muitas vezes não é adequada para interfaces de usuário. Vamos considerar os principais métodos de formatação.

Métodos de formatação embutidos

• toDateString() — "Tue Oct 24 2023"
• toLocaleDateString() — data localizada (ex.: "24/10/2023" para o Brasil)
• toISOString() — string no formato ISO ("2023-10-24T11:30:00.000Z")

const date: Date = new Date();console.log(date.toLocaleDateString('pt-BR')); // 24/10/2023console.log(date.toLocaleTimeString('pt-BR')); // 14:30:00

Formatação personalizada com Intl.DateTimeFormat

Para um controle mais flexível, use Intl.DateTimeFormat:

const date: Date = new Date();const formatter = new Intl.DateTimeFormat('pt-BR', {    year: 'numeric',    month: 'long',    day: 'numeric',    weekday: 'long',    hour: '2-digit',    minute: '2-digit'});console.log(formatter.format(date)); // "terça-feira, 24 de outubro de 2023, 14:30"

Biblioteca date-fns

Para tarefas complexas, recomenda-se usar a biblioteca date-fns. Ela é leve e possui excelente suporte ao TypeScript:

import { format, addDays, isWeekend } from 'date-fns';import { ptBR } from 'date-fns/locale';

const date: Date = new Date();console.log(format(date, 'dd/MM/yyyy', { locale: ptBR })); // "24/10/2023"console.log(format(date, 'HH:mm:ss')); // "14:30:00"console.log(isWeekend(date)); // false

3. Manipulações com datas: adição, subtração e comparação

Alterando a data

A maneira mais simples é usar os setters:

const date: Date = new Date();date.setFullYear(2024);date.setMonth(11); // dezembrodate.setDate(31);console.log(date); // "Tue Dec 31 2024 14:30