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

Работа с длительностями в Day.js строится вокруг отдельного плагина duration, который добавляет поддержку промежутков времени, отличных от конкретных дат и моментов. В отличие от объектов dayjs, представляющих фиксированную точку на временной шкале, длительность описывает относительный интервал: часы, минуты, дни и их комбинации.

Для включения функциональности используется подключение плагина:

import dayjs from 'dayjs'
import duration from 'dayjs/plugin/duration'

dayjs.extend(duration)

После расширения библиотеки становится доступен конструктор длительностей dayjs.duration, который принимает несколько форм входных данных и возвращает объект длительности.

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

const d = dayjs.duration(5000)

В этом случае создаётся интервал, равный 5000 миллисекунд (5 секунд). Внутренне значение нормализуется, но хранится как единая длительность.

Для преобразования используются методы, возвращающие разные единицы измерения:

d.asSeconds()   // 5
d.asMinutes()   // 0.0833...
d.asHours()     // 0.00138...

Методы asXxx всегда возвращают полное значение длительности в выбранной единице без разбиения на составные части.

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

Более выразительный способ задания интервала — использование объектной формы, где каждая единица времени задаётся явно.

const d = dayjs.duration({
  hours: 2,
  minutes: 30,
  seconds: 10
})

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

Объект нормализуется: например, 90 минут автоматически преобразуются в 1 час 30 минут при необходимости внутренней обработки.

const d = dayjs.duration({
  minutes: 90
})

d.hours()   // 1
d.minutes() // 30

ISO 8601 формат длительности

Day.js поддерживает создание длительности из строки формата ISO 8601. Это стандартный способ описания временных интервалов, используемый в API и базах данных.

const d = dayjs.duration('PT2H30M')

Здесь:

  • P обозначает период
  • T отделяет дату от времени
  • H, M, S — часы, минуты, секунды

Также возможны более сложные варианты:

dayjs.duration('P1DT12H')   // 1 день и 12 часов
dayjs.duration('PT45M30S')  // 45 минут 30 секунд

Такой формат особенно важен при взаимодействии с внешними сервисами, где данные приходят строго стандартизированными строками.

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

При создании длительности Day.js автоматически приводит значения к корректному виду, перераспределяя избыточные единицы.

const d = dayjs.duration({
  hours: 1,
  minutes: 120
})

Внутренне это преобразуется в:

  • 3 часа
  • 0 минут
d.hours()   // 3
d.minutes() // 0

Подобное поведение упрощает работу с арифметикой времени, исключая необходимость ручного переноса значений.

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

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

const d = dayjs.duration({
  days: 2,
  hours: 5,
  minutes: 40
})

Доступ к компонентам:

d.days()      // 2
d.hours()     // 5
d.minutes()   // 40

Эти методы возвращают остаточные значения соответствующих единиц, а не полное количество в пересчёте.

Для получения полного значения используются специальные методы:

d.asDays()
d.asHours()
d.asMinutes()

Различие между ними принципиально:

  • days() — только компонент дней
  • asDays() — полная длительность в днях

Работа с отрицательными длительностями

Длительности могут быть отрицательными, что используется при вычислении разницы между моментами времени.

const d = dayjs.duration(-3600000)

Это соответствует отрицательному часу.

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

d.asHours() // -1

Такие значения применяются в расчётах обратного отсчёта и сравнении временных интервалов.

Преобразование и точность

При конвертации длительности в различные единицы следует учитывать, что некоторые значения являются приближенными.

const d = dayjs.duration({
  days: 1
})

d.asHours() // 24

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

dayjs.duration({ months: 1 }).asDays()

Такое преобразование не всегда соответствует календарной точности, поскольку длина месяца варьируется.

Клонирование и неизменяемость

Объекты длительности в Day.js ведут себя как неизменяемые структуры: операции не изменяют исходный объект, а создают новый результат.

const d1 = dayjs.duration({ minutes: 30 })
const d2 = dayjs.duration(d1.asMilliseconds())

Это упрощает управление состоянием, особенно в функциональных сценариях, где важно избегать побочных эффектов.

Практика комбинирования входных форм

В реальных задачах часто используются разные способы создания длительности в зависимости от источника данных.

dayjs.duration(1500)

dayjs.duration({
  minutes: 25,
  seconds: 10
})

dayjs.duration('PT1H5M')

Все три варианта приводят к одному типу объекта, что позволяет унифицировать дальнейшую обработку.

Особенности интерпретации значений

При создании длительности важно учитывать следующие особенности:

  • числа интерпретируются как миллисекунды
  • объектные значения автоматически нормализуются
  • строки должны соответствовать ISO 8601
  • превышающие значения перераспределяются в старшие единицы
dayjs.duration({
  seconds: 120
}).minutes() // 2

Использование длительности как промежуточного слоя вычислений

Длительность часто выступает как промежуточный формат между датами и числовыми вычислениями. Она позволяет:

  • хранить результат разницы между датами
  • выполнять арифметику времени
  • преобразовывать интервалы между единицами измерения
const start = dayjs('2026-01-01')
const end = dayjs('2026-01-10')

const diff = dayjs.duration(end.diff(start))

diff.asDays() // 9

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

Оглавление