Номер недели в году

Номер недели в году — это способ разбиения календарного времени на последовательные семидневные интервалы, начиная с фиксированной точки отсчёта. В разных стандартах эта точка отличается: неделя может начинаться с воскресенья или понедельника, а первая неделя года может определяться по-разному.

В практических задачах, связанных с аналитикой, логированием, планированием и отчётами, чаще всего используется ISO-8601 стандарт, где неделя начинается с понедельника, а первая неделя года — та, которая содержит первый четверг января.

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

Базовая модель недели в Day.js

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

Основной принцип работы:

  • ядро Day.js отвечает за даты и время
  • плагины добавляют специализированные методы
  • номер недели реализуется через отдельные расширения

Плагин weekOfYear: нумерация недель года

Для получения номера недели по простому календарному принципу используется плагин weekOfYear.

Подключение:

import dayjs from 'dayjs'
import weekOfYear from 'dayjs/plugin/weekOfYear'

dayjs.extend(weekOfYear)

После подключения появляется метод:

dayjs().week()

Логика weekOfYear

Плагин weekOfYear использует локально-зависимую модель недели:

  • неделя может начинаться с воскресенья или понедельника (зависит от локали)
  • первая неделя — это та, где находится 1 января
  • возможны значения недели 0 (для дней до первой полной недели)

Пример:

dayjs('2026-01-01').week()
dayjs('2026-06-15').week()

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

ISO-недели и плагин isoWeek

Для строгих календарных вычислений используется ISO-8601. В Day.js это реализуется через плагин isoWeek.

Подключение:

import isoWeek from 'dayjs/plugin/isoWeek'

dayjs.extend(isoWeek)

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

dayjs().isoWeek()
dayjs().isoWeekYear()
dayjs().startOf('isoWeek')
dayjs().endOf('isoWeek')

Правила ISO-нумерации недель

ISO-нумерация имеет жёсткие правила:

  • неделя начинается в понедельник
  • неделя 1 — первая неделя, содержащая четверг января
  • год может содержать 52 или 53 недели
  • первые дни января могут относиться к последней неделе предыдущего года

Это приводит к важным отличиям от обычной календарной логики.

Сравнение weekOfYear и isoWeek

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

weekOfYear

  • зависит от локали
  • более «интуитивный» календарь
  • используется в интерфейсах и UI

isoWeek

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

Получение номера недели в реальных сценариях

Текущая неделя

dayjs().isoWeek()

Неделя конкретной даты

dayjs('2026-03-10').isoWeek()

Определение начала недели

dayjs('2026-03-10').startOf('isoWeek')

Результатом будет понедельник соответствующей ISO-недели.

Год недели и пограничные даты

ISO-недели тесно связаны с понятием «года недели»:

dayjs('2026-01-01').isoWeekYear()

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

Пример пограничной логики:

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

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

Номер недели используется для:

  • группировки статистики по неделям
  • построения графиков активности
  • отчётов продаж
  • логирования событий

Пример группировки:

const week = dayjs(date).isoWeek()
const year = dayjs(date).isoWeekYear()

const key = `${year}-W${week}`

Такой ключ позволяет корректно агрегировать данные без ошибок при переходе года.

Особенности локализации

При использовании weekOfYear важную роль играет локаль:

import 'dayjs/locale/ru'
dayjs.locale('ru')

В разных локалях:

  • первый день недели может меняться
  • смещается вычисление недель
  • изменяется поведение границ года

ISO-стандарт при этом остаётся неизменным независимо от локали.

Ошибки при работе с неделями

Типичные проблемы:

  • смешивание weekOfYear и isoWeek
  • отсутствие подключения плагина
  • неправильная локаль
  • использование week() без понимания контекста

Особенно критична ошибка смешивания стандартов в аналитических системах, где это приводит к некорректным отчётам за периоды.

Взаимодействие с другими методами Day.js

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

  • startOf('day') — нормализация дат
  • add() и subtract() — переход по неделям
  • format() — вывод в отчётах
  • diff() — вычисление разницы между датами

Пример перехода между неделями:

dayjs().add(1, 'week').isoWeek()

Структурирование данных по неделям

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

const grouped = {}

data.forEach(item => {
  const d = dayjs(item.date)
  const key = `${d.isoWeekYear()}-${d.isoWeek()}`

  if (!grouped[key]) grouped[key] = []
  grouped[key].push(item)
})

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

Оглавление