Создание объектов длительности

Библиотека Moment.js предоставляет отдельный тип данных для работы с временными промежутками — Duration. В отличие от объекта даты (Moment), который хранит конкретную точку времени, объект длительности описывает интервал: количество секунд, минут, часов, дней, месяцев или лет.

Объекты длительности используются для:

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

Создание длительности через moment.duration()

Основной способ создания объекта длительности:

moment.duration()

Метод возвращает экземпляр Duration.

Создание пустой длительности

const duration = moment.duration();

console.log(duration.asSeconds());

Результат:

0

Пустая длительность содержит нулевое значение всех единиц времени.

Создание длительности из миллисекунд

Наиболее простой вариант — передача числа миллисекунд.

const duration = moment.duration(5000);

console.log(duration.asSeconds());

Результат:

5

Значение 5000 интерпретируется как 5000 миллисекунд.

Создание длительности с указанием единицы измерения

Второй аргумент определяет единицу времени.

Секунды

const duration = moment.duration(30, 'seconds');

console.log(duration.asMinutes());

Минуты

const duration = moment.duration(15, 'minutes');

console.log(duration.asSeconds());

Часы

const duration = moment.duration(2, 'hours');

console.log(duration.asMinutes());

Дни

const duration = moment.duration(7, 'days');

console.log(duration.asHours());

Недели

const duration = moment.duration(3, 'weeks');

console.log(duration.asDays());

Месяцы

const duration = moment.duration(6, 'months');

console.log(duration.asDays());

Годы

const duration = moment.duration(1, 'year');

console.log(duration.asMonths());

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

Moment.js поддерживает как полные, так и сокращённые формы.

Полная форма Сокращение
years y
quarters Q
months M
weeks w
days d
hours h
minutes m
seconds s
milliseconds ms

Пример:

moment.duration(5, 'd');
moment.duration(5, 'days');

Оба варианта эквивалентны.

Создание длительности через объект

Для сложных интервалов удобнее использовать объект.

const duration = moment.duration({
    days: 2,
    hours: 5,
    minutes: 30
});

Комбинирование единиц времени

const duration = moment.duration({
    years: 1,
    months: 3,
    days: 10,
    hours: 12
});

Такой подход особенно удобен при работе с расписаниями, таймерами и вычислениями периодов.

Получение отдельных компонентов длительности

После создания длительности можно извлекать отдельные части.

const duration = moment.duration({
    hours: 2,
    minutes: 45
});

console.log(duration.hours());
console.log(duration.minutes());

Разница между hours() и asHours()

Это одна из самых важных особенностей работы с Duration.

Метод hours()

Возвращает только часовую часть.

const duration = moment.duration({
    days: 1,
    hours: 5
});

console.log(duration.hours());

Результат:

5

Метод asHours()

Возвращает полное количество часов.

console.log(duration.asHours());

Результат:

29

Поскольку:

  • 1 день = 24 часа
  • 24 + 5 = 29

Создание длительности из ISO 8601

Moment.js поддерживает международный формат временных интервалов ISO 8601.

const duration = moment.duration('PT2H30M');

console.log(duration.asMinutes());

Структура ISO-строки

P[n]Y[n]M[n]DT[n]H[n]M[n]S

Обозначения:

Символ Значение
P начало периода
Y годы
M месяцы
D дни
T разделитель даты и времени
H часы
M минуты
S секунды

Примеры

2 часа 30 минут

moment.duration('PT2H30M');

5 дней

moment.duration('P5D');

1 год 2 месяца

moment.duration('P1Y2M');

3 дня 4 часа 15 минут

moment.duration('P3DT4H15M');

Создание длительности из объекта разницы дат

Moment.js позволяет получить длительность между двумя датами.

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

const duration = moment.duration(end.diff(start));

console.log(duration.asDays());

Использование diff() вместе с duration()

Метод diff() возвращает разницу между датами в миллисекундах.

const date1 = moment('2025-05-01');
const date2 = moment('2025-05-15');

const diff = date2.diff(date1);

console.log(diff);

Эта разница может быть преобразована в объект длительности.

const duration = moment.duration(diff);

console.log(duration.days());

Создание отрицательной длительности

Moment.js поддерживает отрицательные интервалы.

const duration = moment.duration(-3, 'days');

console.log(duration.asDays());

Использование отрицательных интервалов

Отрицательные длительности применяются:

  • при обратном отсчёте;
  • вычислении просрочек;
  • отображении времени до события;
  • сравнении временных диапазонов.

Создание длительности через JSON-объект

const duration = moment.duration({
    hours: 4,
    minutes: 20,
    seconds: 10
});

Такой формат удобен при получении данных от API или формы ввода.

Нормализация значений

Moment.js автоматически преобразует превышающие значения.

const duration = moment.duration({
    minutes: 90
});

console.log(duration.hours());
console.log(duration.minutes());

Результат:

1
30

Работа с дробными значениями

Duration поддерживает дробные числа.

const duration = moment.duration(1.5, 'hours');

console.log(duration.asMinutes());

Результат:

90

Создание длительности из строки времени

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

const duration = moment.duration('02:30:00');

Однако такой способ считается менее надёжным по сравнению с ISO 8601.

Проверка объекта длительности

Для проверки используется метод:

moment.isDuration()

Пример:

const duration = moment.duration(5, 'days');

console.log(moment.isDuration(duration));

Клонирование длительности

const duration1 = moment.duration(2, 'hours');

const duration2 = moment.duration(duration1);

Создаётся независимая копия объекта.

Использование длительности с датами

Duration часто применяется вместе с объектами Moment.

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

const now = moment();

const result = now.add(
    moment.duration(3, 'days')
);

console.log(result.format());

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

const result = moment().subtract(
    moment.duration(2, 'weeks')
);

Преобразование длительности в разные единицы

В секунды

duration.asSeconds();

В минуты

duration.asMinutes();

В часы

duration.asHours();

В дни

duration.asDays();

В недели

duration.asWeeks();

В месяцы

duration.asMonths();

В годы

duration.asYears();

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

Метод Описание
milliseconds() миллисекунды
seconds() секунды
minutes() минуты
hours() часы
days() дни
months() месяцы
years() годы

Пример:

const duration = moment.duration({
    days: 2,
    hours: 10
});

console.log(duration.days());
console.log(duration.hours());

Особенности месяцев и лет

Месяцы и годы не имеют фиксированной продолжительности.

Например:

  • февраль содержит 28 или 29 дней;
  • месяц может содержать 30 или 31 день;
  • год может быть високосным.

Поэтому:

moment.duration(1, 'month').asDays();

может давать результаты, основанные на внутренних вычислениях Moment.js, а не на конкретном календарном месяце.

Внутреннее хранение длительности

Moment.js хранит длительность в нескольких категориях:

  • миллисекунды;
  • дни;
  • месяцы.

Это необходимо из-за различий календарных единиц.

Например:

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

Частые ошибки

Путаница между days() и asDays()

const duration = moment.duration(48, 'hours');

console.log(duration.days());
console.log(duration.asDays());

Результат:

2
2

Но:

const duration = moment.duration(50, 'hours');

console.log(duration.days());
console.log(duration.asDays());

Результат:

2
2.0833333333333335

Использование месяцев как фиксированных дней

moment.duration(1, 'month').asDays();

Не следует считать эквивалентом строго 30 дней.

Использование строк без стандарта ISO

moment.duration('5 hours');

Подобные конструкции могут работать нестабильно в разных версиях библиотеки.

Предпочтительный вариант:

moment.duration(5, 'hours');

или:

moment.duration('PT5H');

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

Таймер обратного отсчёта

const duration = moment.duration(90, 'seconds');

console.log(duration.minutes());
console.log(duration.seconds());

Длительность рабочего дня

const workDay = moment.duration({
    hours: 8,
    minutes: 30
});

console.log(workDay.asMinutes());

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

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

const duration = moment.duration(
    end.diff(start)
);

console.log(duration.asDays());

Прибавление времени к дате

const meeting = moment();

meeting.add({
    hours: 2,
    minutes: 15
});

console.log(meeting.format());

Совместимость и статус библиотеки

Moment.js находится в режиме поддержки legacy-проектов. Команда разработчиков рекомендует использовать современные альтернативы:

  • Luxon;
  • Day.js;
  • date-fns;
  • Temporal API.

Тем не менее, Moment.js продолжает активно использоваться в существующих проектах, поэтому понимание работы Duration остаётся важным навыком при сопровождении и модернизации JavaScript-приложений.

Оглавление