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

Moment.js предоставляет два основных подхода к работе с неделями года: локальные (зависящие от настроек языка и региона) и ISO-недели (строго стандартизированные по ISO-8601). Понимание различий между ними критично при расчётах календарных интервалов, построении отчётности и работе с временными рядами.

Неделя года — это порядковый номер недели в пределах календарного года. Однако «неделя» не является универсальным понятием:

  • В разных локалях неделя может начинаться с воскресенья или понедельника
  • Первая неделя года может определяться по-разному
  • ISO-стандарт фиксирует строгие правила

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

Локальные недели (locale week)

Локальная неделя зависит от текущей локали Moment.js.

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

moment().week();

Метод week() возвращает номер недели года согласно локальным настройкам.

Пример:

const m = moment("2026-01-10");
console.log(m.week());

Значение будет зависеть от того, какой день считается началом недели в текущей локали.

Установка номера недели

moment().week(12);

Изменяет дату так, чтобы она соответствовала указанной неделе в рамках текущего года.

ISO-недели

ISO-недели строго определены стандартом ISO-8601:

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

Получение ISO-недели

moment().isoWeek();

Пример:

const m = moment("2026-01-10");
console.log(m.isoWeek());

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

moment().isoWeek(5);

Это изменяет дату в соответствии с ISO-календарём.

Ключевые различия week() и isoWeek()

Метод Основа расчёта Начало недели Первая неделя года
week() Локаль Зависит от локали Локальное правило
isoWeek() ISO-8601 Понедельник Неделя с первым четвергом

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

Год недели: weekYear и isoWeekYear

При работе с неделями важно учитывать, что неделя может принадлежать «другому» году.

Локальный год недели

moment().weekYear();

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

ISO год недели

moment().isoWeekYear();

Используется вместе с ISO-неделями:

const m = moment("2026-01-01");
console.log(m.isoWeek());
console.log(m.isoWeekYear());

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

Форматирование недели через строки

Moment.js поддерживает токены форматирования для недель:

  • w — номер недели (локальный)
  • ww — номер недели с ведущим нулём
  • W — ISO-неделя
  • WW — ISO-неделя с ведущим нулём

Примеры:

moment("2026-01-10").format("w");
moment("2026-01-10").format("ww");
moment("2026-01-10").format("W");
moment("2026-01-10").format("WW");

Эти токены позволяют формировать отчётные строки без прямого вызова методов week() или isoWeek().

Начало недели и локали

Начало недели определяется локалью:

moment.locale('en'); // воскресенье — начало недели
moment.locale('ru'); // понедельник — начало недели

Проверка текущего начала недели:

moment.localeData().firstDayOfWeek();

Это значение напрямую влияет на результат week().

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

Особое внимание требуется при работе с датами в конце года.

Пример:

moment("2025-12-31").week();
moment("2025-12-31").isoWeek();

В одном случае дата может относиться к 1-й неделе следующего года, в другом — к последней неделе текущего.

Такие расхождения критичны при:

  • построении недельной аналитики
  • агрегации данных по периодам
  • финансовых отчётах

Изменение недели и побочные эффекты

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

moment().week(1);

Это может привести к смещению месяца и года, поскольку Moment.js пересчитывает дату целиком.

Аналогично:

moment().isoWeek(1);

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

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

Смешивание ISO и локальных методов

moment().week();
moment().isoWeek();

Использование разных систем в одном проекте приводит к несоответствиям отчётных данных.

Игнорирование локали

Без явного задания локали результат week() может отличаться в разных окружениях.

moment.locale('en');

Ошибки на границе года

Даты 29–31 декабря и 1–3 января часто относятся к разным неделям и даже годам в ISO-логике.

Использование недель в форматировании отчётов

Пример построения ключа «год-неделя»:

const m = moment();

const keyISO = `${m.isoWeekYear()}-W${m.isoWeek()}`;
const keyLocal = `${m.weekYear()}-W${m.week()}`;

Такие ключи применяются для:

  • группировки статистики
  • построения временных рядов
  • кэширования данных по периодам

Работа с диапазонами недель

Для вычисления начала и конца недели используются комбинации startOf и endOf:

moment().startOf('week');
moment().endOf('week');

Для ISO-недель:

moment().startOf('isoWeek');
moment().endOf('isoWeek');

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

Влияние временных зон

Moment.js учитывает временную зону при вычислении недели. При изменении зоны возможны сдвиги границ недели, особенно при переходе через полночь в UTC.

moment().utc().isoWeek();

Использование UTC снижает риск расхождений в распределённых системах.

Оглавление