Получение дня года

Работа с датами в JavaScript без специализированных инструментов быстро приводит к усложнению кода: вычисление порядкового номера дня в году требует учета високосных лет, различной длины месяцев и особенностей календаря. Библиотека Day.js решает эту задачу через расширяемый набор плагинов, среди которых предусмотрена поддержка получения дня года.

День года (day of year, DOY) — это число от 1 до 365 (или 366 в високосный год), показывающее порядковый номер даты в рамках текущего календарного года. Например, 1 января — это 1-й день года, 31 декабря — 365-й или 366-й.

Подключение функционала дня года

В базовой поставке Day.js отсутствует метод для работы с порядковым номером дня года. Для этого используется плагин dayOfYear.

Подключение выполняется в несколько шагов:

import dayjs from 'dayjs'
import dayOfYear from 'dayjs/plugin/dayOfYear'

dayjs.extend(dayOfYear)

После расширения экземпляра становится доступен метод dayOfYear().

Получение дня года

Основной метод работы с порядковым номером дня:

dayjs().dayOfYear()

Возвращаемое значение — целое число.

Пример:

import dayjs from 'dayjs'
import dayOfYear from 'dayjs/plugin/dayOfYear'

dayjs.extend(dayOfYear)

const today = dayjs()
console.log(today.dayOfYear())

Результат зависит от текущей даты. Например, если сегодня 10 марта в невисокосный год, результат будет 69.

Получение дня года для конкретной даты

Метод применяется не только к текущей дате, но и к любому объекту Day.js:

const date = dayjs('2026-05-23')
console.log(date.dayOfYear())

Это позволяет вычислять позицию даты в рамках года для аналитики, календарных вычислений и построения временных шкал.

Установка дня года

Метод dayOfYear также поддерживает запись значения, изменяя дату:

const date = dayjs('2026-01-01')

const updated = date.dayOfYear(100)
console.log(updated.format('YYYY-MM-DD'))

В этом случае дата изменится так, чтобы соответствовать 100-му дню года.

Внутренние особенности вычисления

При работе с порядковым номером дня года учитываются:

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

Високосный год определяется по стандартному правилу:

  • год делится на 4 → високосный;
  • но если делится на 100 → не високосный;
  • если делится на 400 → високосный.

Это влияет на диапазон значений: 366 возможен только в високосные годы.

Примеры вычислений

Начало года

dayjs('2026-01-01').dayOfYear() // 1

Середина года

dayjs('2026-07-01').dayOfYear() // 182 (в невисокосный год)

Конец года

dayjs('2026-12-31').dayOfYear() // 365

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

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

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

Пример группировки данных:

const data = [
  { date: '2026-01-01', value: 10 },
  { date: '2026-01-02', value: 15 },
  { date: '2026-02-01', value: 7 }
]

const grouped = data.reduce((acc, item) => {
  const doy = dayjs(item.date).dayOfYear()
  acc[doy] = (acc[doy] || 0) + item.value
  return acc
}, {})

console.log(grouped)

Сравнение дат через день года

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

const a = dayjs('2026-03-10').dayOfYear()
const b = dayjs('2026-05-01').dayOfYear()

console.log(a < b)

Такой подход упрощает сортировку дат в рамках одного календарного года.

Особенности при смене года

Метод dayOfYear() работает строго в рамках конкретного года объекта. При переходе между годами логика не переносится автоматически.

dayjs('2025-12-31').dayOfYear() // 365
dayjs('2026-01-01').dayOfYear() // 1

Это важно при вычислении разницы между датами, охватывающими границу года. В таких случаях требуется дополнительная обработка через diff():

dayjs('2026-01-01').diff(dayjs('2025-12-31'), 'day') // 1

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

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

const date = dayjs('2026-01-01').dayOfYear(256)
console.log(date.format('YYYY-MM-DD'))

Это удобно при работе с порядковыми календарями, где дата представлена только числом дня в году.

Ограничения метода

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

  • отсутствие учета часовых поясов при логических расчетах (если не нормализованы даты);
  • зависимость от календарного года;
  • возможные ошибки при смешении с абсолютными временными метками.

Для точных временных вычислений рекомендуется комбинировать dayOfYear() с другими методами Day.js:

  • startOf('year')
  • diff()
  • format()

Сочетание с другими функциями

const start = dayjs().startOf('year')
const current = dayjs()

const diff = current.diff(start, 'day') + 1

console.log(diff === current.dayOfYear())

Это демонстрирует эквивалентность двух подходов к вычислению дня года.

Практическое применение в системах учета времени

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

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

Пример временной шкалы:

const events = [
  { name: 'start', date: '2026-01-10' },
  { name: 'checkpoint', date: '2026-06-15' },
  { name: 'end', date: '2026-12-20' }
]

events.forEach(e => {
  const d = dayjs(e.date)
  console.log(e.name, d.dayOfYear())
})

Работа с массивами дат

const dates = [
  '2026-02-01',
  '2026-02-15',
  '2026-03-01'
]

const sorted = dates
  .map(d => dayjs(d))
  .sort((a, b) => a.dayOfYear() - b.dayOfYear())

console.log(sorted.map(d => d.format('YYYY-MM-DD')))

Контроль високосных лет при анализе

const year = dayjs('2024-01-01')

const maxDay = year.isLeapYear ? 366 : 365
console.log(maxDay)

В сочетании с dayOfYear() это позволяет валидировать диапазоны значений при пользовательском вводе или импорте данных.

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

Метод dayOfYear() в Day.js представляет собой компактный инструмент для перехода от календарной даты к линейной временной шкале внутри года и обратно. Он интегрируется в более широкую систему работы с датами, сохраняя предсказуемость и согласованность вычислений при условии корректной обработки границ года и календарных особенностей.

Оглавление