Номер недели ISO

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

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

Для работы с ISO-нумерацией недель используется плагин isoWeek. Его необходимо подключить и расширить базовый объект Day.js.

import dayjs from 'dayjs'
import isoWeek from 'dayjs/plugin/isoWeek'

dayjs.extend(isoWeek)

После подключения становятся доступными методы, основанные на ISO-стандарте: вычисление номера недели, года ISO-недели, а также установка даты по ISO-неделе.

Получение номера ISO-недели

Метод isoWeek() возвращает номер недели в соответствии с ISO 8601.

dayjs('2026-01-22').isoWeek()

Результатом будет число от 1 до 53, в зависимости от положения даты в ISO-календаре.

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

ISO-неделя и начало недели

В ISO-стандарте неделя всегда начинается с понедельника. Day.js с подключённым плагином интерпретирует границы недели именно таким образом.

Получение начала недели:

dayjs('2026-01-22').startOf('isoWeek')

Результат будет возвращён с временем, установленным на 00:00 понедельника текущей ISO-недели.

Получение конца недели:

dayjs('2026-01-22').endOf('isoWeek')

Результат соответствует воскресенью 23:59:59.999 той же ISO-недели.

ISO-год недели

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

Для получения ISO-года используется метод isoWeekYear():

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

Это значение определяет год, к которому принадлежит ISO-неделя даты.

Установка даты по ISO-неделе

Day.js позволяет формировать дату на основе ISO-недели через комбинацию методов isoWeekYear, isoWeek и day.

dayjs()
  .isoWeekYear(2026)
  .isoWeek(3)
  .startOf('isoWeek')

Такой подход позволяет переходить к конкретной неделе заданного ISO-года и получать её начальную дату.

Отличие isoWeek от week

Day.js предоставляет два разных механизма работы с неделями:

  • week() — зависит от локальной настройки начала недели
  • isoWeek() — строго соответствует ISO 8601 (понедельник — первый день недели)

Пример различий:

dayjs('2026-01-22').week()
dayjs('2026-01-22').isoWeek()

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

Границы года и пересечение недель

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

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

Такая модель позволяет стандартизировать недельную разметку в системах планирования, логирования и аналитики.

Особенности вычислений ISO-недель

При работе с ISO-неделями в Day.js важно учитывать следующие особенности:

  • первая ISO-неделя всегда содержит 4 января
  • неделя начинается строго с понедельника
  • год ISO-недели может не совпадать с календарным годом
  • возможны недели с номером 52 или 53 в зависимости от структуры года

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

Преобразование дат через ISO-недели

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

const start = dayjs()
  .isoWeekYear(2026)
  .isoWeek(10)
  .startOf('isoWeek')

const end = dayjs()
  .isoWeekYear(2026)
  .isoWeek(10)
  .endOf('isoWeek')

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

Сравнение с календарными неделями

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

В Day.js различие выражается через выбор метода week() или isoWeek(), что критично при работе с международными данными и синхронизацией временных систем.

Оглавление