Единицы измерения

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

Базовый набор единиц включает:

  • year — год
  • month — месяц
  • week — неделя
  • day — день
  • hour — час
  • minute — минута
  • second — секунда
  • millisecond — миллисекунда

Каждая единица имеет строковый идентификатор, используемый в API. Допускаются как формы в единственном числе, так и во множественном (years, months, days и т.д.), однако внутренняя интерпретация унифицирована.

Строковые идентификаторы и их интерпретация

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

Пример использования:

dayjs().add(1, 'day')
dayjs().subtract(2, 'months')
dayjs().add(3, 'year')

Строки интерпретируются без учёта регистра, однако стандартной практикой считается использование lowercase.

Допустимые алиасы:

  • y → year
  • M → month
  • w → week
  • d → day
  • h → hour
  • m → minute
  • s → second
  • ms → millisecond

Короткие формы применяются реже, поскольку снижают читаемость кода.

Арифметика дат: add и subtract

Методы add и subtract формируют основу работы с единицами измерения времени. Оба метода принимают числовое значение и единицу измерения.

dayjs().add(10, 'minute')
dayjs().subtract(5, 'day')

Особенности поведения

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

Например:

  • добавление 1 месяца к 31 января приводит к корректировке даты в зависимости от длины следующего месяца
  • добавление года учитывает високосные периоды

Пример:

dayjs('2024-01-31').add(1, 'month') // 2024-02-29

Для единиц меньше дня (час, минута, секунда, миллисекунда) используется линейная модель времени, основанная на фиксированных интервалах.

Вычисление разницы: diff

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

dayjs('2024-01-01').diff('2023-01-01', 'year')
dayjs('2024-01-10').diff('2024-01-01', 'day')

Сигнатура:

dayjs().diff(date, unit, float)
  • unit определяет масштаб результата
  • float (boolean) включает дробные значения

Пример с дробным результатом:

dayjs('2024-01-10').diff('2024-01-01', 'day', true) // 9.0

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

dayjs().diff('2024-01-01') // миллисекунды

Округление времени: startOf и endOf

Методы startOf и endOf позволяют приводить дату к началу или концу выбранной единицы измерения.

dayjs().startOf('day')
dayjs().endOf('month')

Поведение по единицам

  • year — начало/конец года (1 января 00:00:00 / 31 декабря 23:59:59.999)
  • month — первый/последний день месяца
  • week — зависит от локали (начало недели может быть понедельник или воскресенье)
  • day — 00:00:00 / 23:59:59.999
  • hour, minute, second — обнуление младших единиц

Пример:

dayjs('2024-05-23 15:45:12').startOf('hour')
// 2024-05-23 15:00:00

Особенности работы с месяцами и годами

Месяцы и годы не имеют фиксированной длительности в миллисекундах, что влияет на арифметику.

Месяцы

  • февраль имеет 28 или 29 дней
  • 30-дневные и 31-дневные месяцы различаются
  • при переполнении даты происходит автоматическая нормализация

Пример:

dayjs('2024-03-31').add(1, 'month')
// 2024-04-30

Годы

  • учитываются високосные циклы
  • добавление года сохраняет день и месяц при возможности
dayjs('2023-02-28').add(1, 'year')
// 2024-02-28

Недели как единица измерения

Неделя (week) обрабатывается как календарная единица, состоящая из 7 дней. Начало недели зависит от локали и может быть изменено через локализационные настройки.

dayjs().add(2, 'week')
dayjs().startOf('week')

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

Миллисекунды и Unix-время

Миллисекунды (millisecond) представляют минимальную единицу в Day.js. Вся внутренняя модель времени базируется на Unix timestamp в миллисекундах.

dayjs().valueOf() // текущее время в ms
dayjs().unix()    // секунды Unix-времени

Сравнение:

  • valueOf() → миллисекунды
  • unix() → секунды

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

dayjs().add(500, 'millisecond')

Пограничные случаи интерпретации единиц

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

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

dayjs().add(90, 'second')

90 секунд преобразуются в 1 минуту 30 секунд.

Взаимодействие единиц

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

dayjs()
  .add(1, 'day')
  .add(2, 'hour')
  .add(30, 'minute')

Каждая операция изменяет базовый объект, формируя новую дату.

Использование единиц в плагинах

Некоторые плагины расширяют систему единиц:

relativeTime

Позволяет отображать относительное время:

dayjs().from(dayjs().add(1, 'day'))

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

duration

Подключаемый модуль длительностей:

dayjs.duration(2, 'hour')
dayjs.duration(90, 'minute')

Поддерживаются те же ключи единиц, что и в основной API.

Ошибки интерпретации единиц

Несоответствие строковых значений

Неверные значения игнорируются или приводят к некорректному результату:

dayjs().add(1, 'dayss') // ошибка логики или игнорирование

Ожидание фиксированной длительности месяца

Месяц не эквивалентен 30 дням, что приводит к различиям при вычислениях:

dayjs().add(1, 'month') // ≠ 30 дней

Смешение календарных и линейных единиц

  • day, hour, minute, second — линейные
  • month, year, week — календарные

Неправильное предположение о линейности приводит к расхождениям в вычислениях.

Роль единиц в архитектуре Day.js

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

Оглавление