Первое знакомство с API

Moment.js — популярная библиотека для работы с датой и временем в JavaScript. Она предоставляет удобный API для:

создания дат;
форматирования;
парсинга строк;
вычисления разницы между датами;
изменения временных значений;
локализации;
работы с часовыми поясами.

До появления современного API Intl и библиотеки Temporal Moment.js был фактическим стандартом работы с датами в экосистеме JavaScript.

Пример создания объекта даты:

const moment = require('moment');

const now = moment();

console.log(now);

Объект moment представляет дату со множеством встроенных методов.

Подключение библиотеки

Установка через npm

npm install moment

Импорт в проекте:

const moment = require('moment');

или:

import moment from 'moment';

Создание объектов Moment

Текущая дата и время

const now = moment();

console.log(now.format());

Метод format() преобразует объект в строку.

Создание из строки

const date = moment('2025-10-15');

console.log(date.format());

Создание из массива

Формат массива:

[год, месяц, день, часы, минуты, секунды]

Пример:

const date = moment([2025, 9, 15, 12, 30]);

console.log(date.format());

Важно помнить:

месяцы начинаются с 0;
октябрь — это 9.

Создание из объекта Date

const jsDate = new Date();

const date = moment(jsDate);

console.log(date.format());

Форматирование дат

Одна из главных возможностей Moment.js — удобное форматирование.

Метод format()

const now = moment();

console.log(now.format('DD.MM.YYYY'));

Результат:

21.05.2026

Основные токены форматирования

День

Токен	Описание
`D`	День
`DD`	День с ведущим нулём
`ddd`	Короткое название дня недели
`dddd`	Полное название дня недели

Пример:

console.log(moment().format('dddd'));

Месяц

Токен	Описание
`M`	Номер месяца
`MM`	Месяц с нулём
`MMM`	Краткое название
`MMMM`	Полное название

Год

Токен	Описание
`YY`	Две цифры года
`YYYY`	Полный год

Время

Токен	Описание
`H`	Часы
`HH`	Часы с нулём
`m`	Минуты
`mm`	Минуты с нулём
`s`	Секунды
`ss`	Секунды с нулём

Примеры форматирования

Полная дата

console.log(
    moment().format('DD.MM.YYYY')
);

Дата и время

console.log(
    moment().format('DD.MM.YYYY HH:mm:ss')
);

Красивый текстовый формат

console.log(
    moment().format('D MMMM YYYY')
);

Парсинг дат

Moment.js умеет преобразовывать строки в даты.

Автоматический парсинг

const date = moment('2025-12-31');

console.log(date.format());

Парсинг с указанием формата

const date = moment(
    '31-12-2025',
    'DD-MM-YYYY'
);

console.log(date.format());

Это особенно важно при нестандартных форматах.

Проверка корректности даты

Метод isValid()

const date = moment('2025-15-99');

console.log(date.isValid());

Результат:

false

Получение отдельных частей даты

Moment.js позволяет получать отдельные компоненты.

Год

console.log(moment().year());

Месяц

console.log(moment().month());

Месяцы начинаются с нуля.

День месяца

console.log(moment().date());

День недели

console.log(moment().day());

Часы

console.log(moment().hour());

Минуты

console.log(moment().minute());

Изменение даты

API Moment.js поддерживает мутацию объекта.

Изменение года

const date = moment();

date.year(2030);

console.log(date.format());

Изменение месяца

date.month(0);

Январь имеет индекс 0.

Изменение дня

date.date(15);

Изменение времени

date.hour(10);
date.minute(45);
date.second(20);

Цепочки методов

Moment.js активно использует chain API.

const date = moment()
    .year(2026)
    .month(5)
    .date(10)
    .hour(14)
    .minute(30);

console.log(date.format());

Такой подход делает код компактным и читаемым.

Добавление времени

Метод add()

const now = moment();

now.add(5, 'days');

console.log(now.format());

Поддерживаемые единицы времени

Значение	Описание
`seconds`	Секунды
`minutes`	Минуты
`hours`	Часы
`days`	Дни
`weeks`	Недели
`months`	Месяцы
`years`	Годы

Примеры add()

Добавление часов

moment().add(3, 'hours');

Добавление месяцев

moment().add(2, 'months');

Добавление нескольких значений

moment()
    .add(1, 'year')
    .add(2, 'months')
    .add(10, 'days');

Вычитание времени

Метод subtract()

const date = moment();

date.subtract(7, 'days');

console.log(date.format());

Сравнение дат

Moment.js предоставляет удобные методы сравнения.

isBefore()

const d1 = moment('2025-01-01');
const d2 = moment('2026-01-01');

console.log(d1.isBefore(d2));

isAfter()

console.log(d2.isAfter(d1));

isSame()

console.log(
    d1.isSame(d2)
);

Разница между датами

Метод diff()

const start = moment('2025-01-01');
const end = moment('2025-01-10');

console.log(
    end.diff(start, 'days')
);

Результат:

Разница в разных единицах

В часах

end.diff(start, 'hours');

В месяцах

end.diff(start, 'months');

В годах

end.diff(start, 'years');

Работа с Unix timestamp

Получение timestamp

console.log(
    moment().unix()
);

Создание из timestamp

const date = moment.unix(1700000000);

console.log(date.format());

Локализация

Moment.js поддерживает множество языков.

Подключение русской локали

import 'moment/locale/ru';

Установка локали

moment.locale('ru');

Пример локализации

moment.locale('ru');

console.log(
    moment().format('D MMMM YYYY')
);

Результат:

21 мая 2026

Относительное время

Moment.js умеет выводить время в человекочитаемом виде.

fromNow()

console.log(
    moment().subtract(3, 'days').fromNow()
);

Результат:

3 дня назад

Через некоторое время

console.log(
    moment().add(5, 'days').fromNow()
);

Результат:

через 5 дней

Начало и конец периода

startOf()

const date = moment();

console.log(
    date.startOf('month').format()
);

endOf()

console.log(
    moment().endOf('day').format()
);

Клонирование объекта

Объекты Moment изменяемы.

Это важная особенность библиотеки.

Проблема мутации

const d1 = moment();

const d2 = d1;

d2.add(1, 'day');

console.log(d1.format());

d1 тоже изменится.

Метод clone()

const d1 = moment();

const d2 = d1.clone();

d2.add(1, 'day');

console.log(d1.format());
console.log(d2.format());

Теперь объекты независимы.

Преобразование в объект Date

const jsDate = moment().toDate();

console.log(jsDate);

Преобразование в строку

console.log(
    moment().toString()
);

Преобразование в JSON

console.log(
    moment().toJSON()
);

Работа с UTC

Создание UTC-даты

const utcDate = moment.utc();

console.log(utcDate.format());

Конвертация в локальное время

utcDate.local();

Проверка диапазона

isBetween()

const date = moment('2025-06-15');

const start = moment('2025-06-01');
const end = moment('2025-06-30');

console.log(
    date.isBetween(start, end)
);

Практический пример

Проверка просрочки задачи

const deadline = moment('2025-12-31');
const now = moment();

if (now.isAfter(deadline)) {
    console.log('Срок истёк');
} else {
    console.log('Срок ещё действует');
}

Практический пример вычисления возраста

const birthday = moment('1995-05-10');

const age = moment().diff(
    birthday,
    'years'
);

console.log(age);

Практический пример таймера

const start = moment();

setTimeout(() => {
    const end = moment();

    console.log(
        end.diff(start, 'seconds')
    );
}, 5000);

Особенности API Moment.js

Изменяемость объектов

Большинство методов изменяет исходный объект:

const date = moment();

date.add(1, 'day');

Это одна из главных особенностей библиотеки.

Гибкий парсинг

Moment.js автоматически распознаёт многие форматы:

moment('2025/12/31');
moment('31.12.2025');
moment('December 31 2025');

Однако для надёжности рекомендуется явно указывать формат.

Удобный chain API

moment()
    .add(1, 'week')
    .startOf('day')
    .format('YYYY-MM-DD');

Ограничения библиотеки

Moment.js считается legacy-проектом.

Основные причины:

изменяемые объекты;
большой размер;
низкая эффективность по сравнению с современными библиотеками;
развитие JavaScript API для дат.

Несмотря на это, Moment.js остаётся важной частью множества существующих проектов.

Совместимость с JavaScript Date

Moment.js построен поверх стандартного объекта Date.

Это позволяет:

конвертировать объекты между API;
использовать Moment.js вместе с обычным JavaScript;
интегрировать библиотеку со сторонними решениями.

Пример:

const jsDate = new Date();

const m = moment(jsDate);

console.log(m.format());

Краткая схема работы API

Действие	Метод
Создание даты	`moment()`
Форматирование	`format()`
Добавление времени	`add()`
Вычитание времени	`subtract()`
Сравнение	`isBefore()`
Разница	`diff()`
Локализация	`locale()`
UTC	`utc()`
Клонирование	`clone()`
Timestamp	`unix()`