Momentjs é uma excelente biblioteca para manipular datas. Com ela você pode ler, alterar, validar e exibir datas e horários em JavaScript ou Node.js.
Neste artigo eu apresento um tutorial rápido de como usar o momentjs para datas no formato brasileiro. Para o formato pt-br, você vai precisar do arquivo com as configurações de locale.
Instalação
A instalação da biblioteca momentjs pode ser feita de diversas formas.
Você pode incluir diretamente do CDNJS usando uma tag <script>, ou copiar o conteúdo da URL abaixo e hospedar no seu próprio projeto. Lembre-se que você vai precisar da versão com os moment-with-locales.min.js.
<script src="https://cdnjs.cloudflare.com/ajax/libs/moment.js/2.27.0/moment-with-locales.min.js"></script>
Você pode também usar npm:
npm install moment --save
E depois fazer a inclusão do momentjs em seu projeto:
import moment from 'moment'
Essa é a melhor opção se você está usando Node.js.
Usando o formato brasileiro
Se você deseja formatar as datas em português, precisa setar o locale na configuração do momentjs. Para isso, basta usar a seguinte linha antes de começar a usar o momentjs:
moment.locale('pt-br');
Obtendo a data e horário atual
Depois de setado o locale para pt-br, você pode chamar a função moment(), para pegar a data atual.
const now = moment(); // Data atual
Parse de datas
Existem várias formas de se ler uma data no momentjs, você pode obter a data atual como mostrado acima, chamando a função moment() em branco. Você pode também ler uma String, um objeto, um UNIX timestamp, entre outras formas. Confira abaixo:
String
Para fazer o parse de uma data em string, você precisa que esta string esteja de acordo com a norma ISO 8601. E também seja uma data válida, de acordo com o formato RFC 2822.
Apesar de não ser obrigatório passar o formato como o segundo parâmetro, é ideal passar esse parâmetro, pois nem todos os navegadores seguem o mesmo padrão quanto ao formato da data.
moment('22-09-2020', 'DD-MM-YYYY');
moment('22/09/2020', 'DD-MM-YYYY');
moment('22/09/2020 10:45:00', 'DD-MM-YYYY HH:mm:ss');
No exemplo acima, tanto faz usar "-", ou "/" na data que você quer ler, pois o moment vai ignorar caracteres não alfanuméricos.
Objeto
Você pode fazer a leitura de uma data através de um objeto, como especificado abaixo.
- Se omitir alguma chave, o padrão é zero, ou a data atual.
- Os meses começam em 0.
moment({ year: 2020, month: 8, day: 5, hour: 12, minute: 10, second: 32, millisecond: 123 });
moment({ years: 2020, months: 8, days: 5, hours: 12, minutes: 10, seconds: 32, milliseconds: 123 });
moment({ y: 2020, M: 8, d: 5, h: 12, m: 10, s: 32, ms: 123 });
Unix Timestamp em milisegundos
Você pode também passar um valor inteiro para moment() e criar uma data baseada em um Unix Timestamp. Ex:
moment(1599836345898)
Formatar uma data
Lembre-se de incluir moment.locale('pt-br') no início do seu código para que os formatos abaixo funcionem para o padrão do Brasil:
Formatos localizados
A forma mais simples de exibir uma data no formato pt-br no momentjs é usando os formatos localizados.
moment().format('LT'); // 12:21 - Horário
moment().format('LTS'); // 12:21 - Horário + segundos
moment().format('L'); // 11/09/2020 - Dia/mês/ano (pt-br)
moment().format('l'); // 11/9/2020 - Dia/mês/ano sem zero na frente
moment().format('LL'); // 11 de setembro de 2020
moment().format('ll'); // 11 de set de 2020
moment().format('LLL'); // 11 de setembro de 2020 às 12:21
moment().format('lll'); // 11 de set de 2020 às 12:21
moment().format('LLLL'); // sexta-feira, 11 de setembro de 2020 às 12:21
moment().format('llll'); // sex, 11 de set de 2020 às 12:21
Formatos com string
moment().format(); // 2020-09-11T12:33:14-03:00
moment().format('DD/MM/YYYY'); // 11/09/2020
moment().format('DD/MM/YYYY HH:mm:ss'); // 11/09/2020 12:34:03
moment().format("[Hoje é] dddd"); // Hoje é sexta-feira
Veja uma referência abaixo dos valores mais comuns no padrão ISO 8601 para formatação e leitura de datas.
| Formato | Descrição | Exemplo |
|---|---|---|
| YYYY | Ano de 4 dígitos | 2020 |
| YY | Ano de 2 dígitos | 20 |
| MMM | Mês com 3 letras | Jan |
| MM | Mês com 2 dígitos | 01 |
| M | Mês sem o zero na frente | 1 |
| DDD | Dia do ano, de 1 até 365 | 254 |
| DD | Dia do mês | 05 |
| D | Dia do mês sem o zero na frente | 5 |
| Do | Dia do mês em número ordinal | 5º |
| HH | Horas de 2 dígitos (formato 24h) | 22 |
| H | Horas sem o zero na frente (formato 24h) | 22 |
| hh | Horas de 2 dígitos (formato 12h) | 10 |
| h | Horas sem o zero na frente (formato 12h) | 10 |
| mm | Minutos | 05 |
| ss | Segundos | 04 |
| s | Segundos sem o zero na frente | 4 |
| A | AM / PM | AM |
| a | am / pm | am |
| SSS | Milisegundos de 3 dígitos | 123 |
| SS | Milisegundos de 2 dígitos | 12 |
| S | Milisegundos de 1 dígito | 1 |
| Z | Fuso horário | -03:00 |
| X | UNIX timestamp | 1599836345 |
| x | UNIX timestamp em milisegundos | 1599836345898 |
Exibindo comparações de tempo
Essa biblioteca também permite que você exiba comparações de tempo.
Para mostrar tempo desde agora ou até agora:
moment.locale('pt-br');
const date = moment({ year: 2019 });
date.fromNow(); // há 2 anos
date.fromNow(true); // 2 anos
date.toNow(); // em 2 anos
date.toNow(true); // 2 anos
Para mostrar tempo de uma data até outra:
moment.locale('pt-br');
const date = moment({ year: 2019 });
const date2 = moment({ year: 2020 });
date.from(date2); // há um ano
date.from(date2, true); // um ano
date.to(date2); // em um ano
date.to(date2, true); // um ano
Diferença entre datas
Se você quer mostrar a diferença entre duas datas, pode usar o método diff(), e passar um destes argumentos: years, months, weeks, days, hours, minutes e seconds.
const date1 = moment({ day: 10, month: 9, year: 1994 });
const date2 = moment({ day: 11, month: 10, year: 1994 });
date2.diff(date1, 'days'); // 32
date2.diff(date1, 'months'); // 1
date2.diff(date1, 'months', true); // 1.033333
Manipulando datas
Você pode adicionar ou subtrair tempo em datas da seguinte forma:
moment().add(7, 'days');
moment().subtract(2, 'months');
Você pode adicionar ou subtrair os seguintes valores: years, quarters, months, weeks, days, hours, minutes, seconds, milliseconds.
Validando datas
Você pode verificar se uma data é válida da seguinte forma:
moment('2020-12-14').isValid(); // true
moment('2020-14-14').isValid(); // false
Você pode também fazer consultas para saber se uma data vem antes, depois, se é igual outra data, etc.
// Verificando se uma data vem antes de outra data
moment('2020-01-01').isBefore('2020-02-02'); // true
moment('2020-01-01').isBefore(moment('2020-02-02')); // true
// Você pode usar um segundo parâmetro para diminuir a precisão da comparação
moment('2020-01-01').isBefore('2020-05-01', 'year'); // false
// Verificando se uma data vem depois de outra data
moment('2020-01-01').isAfter('2020-02-02'); // false
// Verificando se vem antes, depois ou é igual
moment('2020-01-01').isSameOrBefore('2020-01-01'); // true
moment('2020-01-01').isSameOrAfter('2020-01-01'); // true
// Verificando se a data é igual
moment('2020-01-01').isSame('2020-01-01'); // true
// Verificando se está entre outras datas
moment('2020-05-01').isBetween('2020-01-01', '2020-12-31'); // true
