Moment.js: Explicação completa e exemplos práticos da biblioteca de datas

Informatec Digital » Expressões idiomáticas » Moment.js: Explicação completa e exemplos práticos da biblioteca de datas

Trabalhar com datas e horas em JavaScript pode ser um verdadeiro desafio para desenvolvedores web . Felizmente, ferramentas como o Moment.js simplificam significativamente esse processo, tornando tudo, desde a formatação básica de datas até operações complexas de manipulação e validação, muito mais fácil. Se você já se sentiu frustrado tentando converter, comparar ou exibir datas corretamente em seus projetos, o Moment.js provavelmente foi um dos seus melhores aliados, ou pelo menos você deveria considerar usá-lo.

Neste artigo, vou te contar tudo o que você precisa saber sobre o Moment.js : desde suas funções principais e truques menos conhecidos, até exemplos práticos e sua integração com outras bibliotecas, incluindo uma explicação clara de sua sintaxe e das tarefas que você pode realizar com ele. Também veremos suas limitações, atualizações recentes e quais alternativas você tem se estiver procurando por algo mais moderno.

O que é Moment.js e por que ele se tornou tão popular?

Moment.js é uma biblioteca JavaScript projetada para facilitar o trabalho com datas e horas . Ela permite criar, analisar, manipular e exibir datas em praticamente qualquer formato imaginável com uma sintaxe simples, porém poderosa. Por anos, essa biblioteca tem sido a principal solução da comunidade para superar as limitações do objeto Date() nativo do JavaScript.

O núcleo do Moment.js gira em torno do objeto `moment()` , que pode construir datas a partir de praticamente qualquer entrada válida: strings de texto, objetos Date, timestamps ou diretamente com argumentos numéricos. Isso o torna extremamente flexível e útil em todos os tipos de projetos, desde pequenos scripts até aplicações corporativas que gerenciam fusos horários internacionais ou registros históricos.

O que o tornou tão bem-sucedido? Sua confiabilidade, facilidade de uso e a variedade de ferramentas e plugins que o acompanham . Mesmo quando o projeto entrou em modo de manutenção, o Moment.js mantém uma grande base de usuários e uma extensa documentação , reforçando sua posição como uma das principais soluções de data em JavaScript e Node.js.

Principais recursos e benefícios do Moment.js

• API simples e intuitivaUm dos maiores pontos fortes do Moment.js é sua sintaxe clara. Você pode realizar operações simples, como obter a data atual ou converter uma string para um formato específico, ou cálculos e validações complexas em apenas algumas linhas.
• Análise e formatação flexíveisAnalisar sequências de datas de quase qualquer formato e convertê-las para a saída desejada nunca foi tão fácil. O Moment.js torna rápido e fácil formatar datas em apresentações personalizadas..
• Manipulação de data: Adicionar ou subtrair dias, meses, anos, semanas ou qualquer outra unidade de tempo é tão simples quanto usar os métodos adicionar() y subtrair()Isso é muito útil quando você precisa trabalhar com datas relativas, datas de vencimento ou prazos que variam dinamicamente.
• Validação robusta: Se você precisa verificar se uma data é válida ou existe (por exemplo, 30 de fevereiro), o Moment.js facilita para você. O método é válido() Ele é capaz de detectar erros sutis no formato ou na lógica das datas.
• Suporte para fusos horários e localização:Obrigado ao seu plugin fuso horárioÉ muito fácil converter datas entre diferentes fusos horários. Você também pode exibir datas adaptadas ao idioma do usuário e às convenções regionais, o que é fundamental em aplicativos globais.
• Ecossistema de plugins:Além da biblioteca principal, há um ecossistema de plugins para estender sua funcionalidade (calendário, compatibilidade com outros frameworks, formatos exóticos...).

Como começar a usar Moment.js em seu projeto

A instalação é muito simples . Você pode incluir o Moment.js no seu HTML com uma única linha:

<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.29.1/moment.min.js"></script>

Se você estiver trabalhando com Node.js ou um ambiente de desenvolvimento moderno, é comum instalá-lo usando npm ou yarn:

npm install moment

Feito isso, você pode importar o Moment.js de acordo com a sintaxe que você usa:

// Versión CommonJS
var moment = require('moment');
moment().format();

// ES6
import moment from 'moment';
moment().format();

Criação de datas: diferentes maneiras e exemplos práticos

Crie datas facilmente

Para obter a data e hora atuais, simplesmente use moment():

console.log(moment()); // Devuelve la fecha actual en formato ISO8601

Você pode construir uma data específica passando argumentos:

moment("2022-10-14"); // Crea el 14 de octubre de 2022

Você também pode começar a partir de uma determinada string e formato, mesmo no modo estrito:

moment("25/12/1995", "DD/MM/YYYY", true); // Analiza y comprueba el formato

Você tem um objeto Date nativo?

const fechaJS = new Date();
const miFecha = moment(fechaJS);

Formatação e exibição de datas

O Moment.js permite exibir datas em qualquer formato imaginável . Por exemplo, para exibir a data atual como dia/mês/ano:

moment().format('DD/MM/YYYY');

Se você quiser uma corrente mais humanizada, você pode usar:

moment().format('MMMM Do YYYY, h:mm:ss a'); // Ejemplo: "marzo 8º 2024, 3:21:10 pm"

Alguns tokens úteis para formatação :

• YYYY: Ano de 4 dígitos
• MM: meu
• DD: dia do mês
• hh o HH: hora (formato 12h ou 24h)
• mm: minutos
• ss: segundos
• a: manhã/tarde

Por exemplo, para exibir apenas a hora:

moment().format('HH:mm:ss');

Formatação avançada com tokens e suporte regional

O Moment.js suporta vários formatos e traduções localizados . É possível alternar entre idiomas instantaneamente para exibir os nomes do mês e do dia em outro idioma.

moment.locale('es'); // Cambia a español
document.write(moment().format('LLLL'));
// Ejemplo: martes, 8 de marzo de 2024 15:21

Manipulação de data: adição, subtração e comparação

Trabalhar com datas relativas é um dos pontos fortes do Moment.js.

• Adicione dias, meses ou anos:

  moment().add(3, 'days').format('DD/MM/YYYY');

• Subtrair unidades:

  moment().subtract(2, 'months').format('DD/MM/YYYY');

• Início e fim dos períodos:

  moment().startOf('month').format('DD/MM/YYYY'); // Primer día del mes
  moment().endOf('month').format('DD/MM/YYYY');   // Último día del mes

Validar datas e detectar erros

Antes de operar com datas é vital validar se elas estão corretas:

moment('2024-02-30', 'YYYY-MM-DD').isValid(); // false, el 30 de febrero no existe

Isso evita erros inesperados em aplicativos que recebem datas do usuário.

Comparação de datas: verifique se uma data está entre outras

O Moment.js inclui vários métodos para comparar datas:

• éAntes(): Verifica se uma data é anterior a outra.
• éDepois(): Verifica se uma data é posterior.
• estáEntre(): Indica se uma data está entre duas datas fornecidas.

let hoy = moment();
let ayer = moment().subtract(1, 'days');
console.log(hoy.isAfter(ayer)); // true

Manipulando fusos horários e datas internacionais

Ao trabalhar com usuários em diferentes partes do mundo, os fusos horários podem ser um verdadeiro problema . Com o plugin moment-timezone , você pode converter datas entre regiões com facilidade.

const moment = require('moment-timezone');
const fechaUTC = moment('2024-05-25');
const fechaNY = fechaUTC.tz('America/New_York').format('YYYY-MM-DD HH:mm:ss');
console.log(fechaNY);
// Ejemplo: "2024-05-24 20:00:00"

Além disso, o Moment.js consegue exibir datas adaptadas às configurações regionais do usuário , mostrando os nomes dos meses e dias traduzidos corretamente.

Exemplos de uso principal e dicas avançadas

Obtenha diferenças entre datas

Você pode calcular o tempo decorrido entre duas datas em unidades diferentes:

let inicio = moment('2024-01-01');
let fin = moment('2024-03-08');
let dias = fin.diff(inicio, 'days'); // Devuelve el número de días entre ambas

Datas relativas e tempos humanos

Moment.js é ótimo para exibir mensagens como "3 dias atrás" ou "em 5 horas":

moment().subtract(3, 'days').fromNow(); // "hace 3 días"
moment().add(2, 'hours').fromNow();    // "en 2 horas"

Calendário humano

A função calendar() exibe datas relativas, como "ontem às 17h" e "amanhã às 9h", tornando-a muito útil para aplicativos de calendário.

moment().subtract(1, 'days').calendar(); // "Ayer a las..."
moment().add(3, 'days').calendar();     // "Próximo martes a las..."

Suporte para saltos anuais e dias especiais

Você quer saber se um ano é bissexto?

moment([2024]).isLeapYear(); // true

O método isLeapYear() fornece a resposta diretamente.

Personalização avançada: formatos, tokens e análise estrita

O Moment.js permite que você trabalhe com strings e tokens personalizados para criar ou ler datas em inúmeros formatos . Além disso, o modo estrito exige correspondências exatas, evitando erros sutis e surpresas indesejadas.

Por exemplo, para analisar uma data no formato "dia/mês/ano":

moment('12/03/2023', 'DD/MM/YYYY', true);

Lista de tokens comuns e exemplos

• Ano: AAAA (2024), AA (24), A (-500)
• mês: MM (01 – 12), MMM (janeiro), MMMM (janeiro)
• Dia: DD (01 – 31), C (1º – 31º)
• Tempo: HH (00 – 23), hh (01 – 12), mm (minutos), ss (segundos)
• Fuso horário: Z, ZZ

Esses tokens podem ser combinados para criar saídas totalmente personalizadas. Consulte a documentação para a lista completa e casos especiais.