Параметр showWeekNumber

showWeekNumber

Параметр showWeekNumber в Pikaday управляет отображением дополнительной колонки с номером календарной недели. Эта колонка добавляется слева от сетки дней месяца и вычисляется по правилам недельной нумерации (обычно ISO 8601). При включении параметра календарь расширяет свою структуру: каждая строка месяца получает соответствующий номер недели, что влияет как на визуальную компоновку, так и на логику восприятия дат.

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

Опция задаётся при инициализации экземпляра Pikaday через конфигурационный объект:

const picker = new Pikaday({
    field: document.getElementById('date'),
    showWeekNumber: true
});

После активации параметра календарная сетка приобретает дополнительную колонку слева, где каждая строка соответствует номеру недели.

Если параметр не задан или установлен в false, интерфейс остаётся классическим: отображаются только дни месяца без дополнительной структурной информации.

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

В основе расчёта обычно используется стандарт ISO 8601, где:

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

Внутренний алгоритм Pikaday рассчитывает номер недели для каждой строки календаря на основе даты, соответствующей первому дню этой строки.

Обобщённо вычисление можно представить следующим образом:

weekNumber = ISOWeek(date)

где ISOWeek — функция, возвращающая порядковый номер недели для конкретной даты.

Визуально это означает, что каждая строка календаря «привязана» не только к диапазону дат, но и к недельному идентификатору.

Визуальная структура календаря при включённом showWeekNumber

При активированном параметре таблица календаря приобретает следующую структуру:

  • левая колонка: номер недели
  • основная область: дни месяца (7 колонок)

Пример логики отображения:

W | Пн Вт Ср Чт Пт Сб Вс
------------------------
1 |  1  2  3  4  5  6  7
2 |  8  9 10 11 12 13 14
3 | 15 16 17 18 19 20 21

Колонка «W» не является интерактивной в стандартной реализации Pikaday, но может быть использована как визуальный ориентир или расширена кастомной логикой через модификацию рендера.

Влияние на разметку и DOM

Включение showWeekNumber изменяет структуру генерируемой таблицы календаря. Добавляется дополнительная ячейка в каждую строку недельного ряда.

Это приводит к следующим изменениям:

  • увеличивается количество <td> в каждой строке;
  • добавляется отдельный класс для ячеек недели (в зависимости от версии реализации);
  • смещается индексация колонок дней.

Пример упрощённой структуры:

<tr>
    <td class="pika-week">12</td>
    <td>1</td>
    <td>2</td>
    ...
    <td>7</td>
</tr>

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

Стилизация week number

Внешний вид колонки недели обычно контролируется через CSS-класс, связанный с ячейками недели. В стандартной разметке Pikaday используется класс вида:

  • .pika-week

Базовая стилизация может включать:

.pika-week {
    color: #999;
    font-size: 12px;
    text-align: center;
    padding: 4px 6px;
}

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

.pika-week {
    border-right: 1px solid #e5e5e5;
    font-weight: 500;
}

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

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

Параметр firstDay, задающий начальный день недели (0 — воскресенье, 1 — понедельник и т.д.), влияет на визуальную сетку, но не меняет сам принцип вычисления номера недели.

const picker = new Pikaday({
    field: document.getElementById('date'),
    showWeekNumber: true,
    firstDay: 1
});

В этом случае:

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

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

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

При отображении недельного номера возникает характерный эффект на границах месяцев:

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

Это нормальное поведение ISO-нумерации и не является ошибкой.

Пример:

  • 30–31 декабря могут относиться к неделе 1 следующего года;
  • 1–3 января могут относиться к последней неделе предыдущего года.

Pikaday не корректирует эти значения под «календарное удобство», а сохраняет строгую недельную систему.

Использование в пользовательских интерфейсах

Колонка недель становится особенно полезной в следующих сценариях:

  • планирование задач по неделям;
  • корпоративные графики;
  • отчётные периоды (week-based reporting);
  • логистика и производственные циклы.

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

Возможные ограничения и нюансы

При использовании showWeekNumber возникают специфические особенности:

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

Также важно учитывать, что стандартный Pikaday не предоставляет встроенной интерактивности для этой колонки: она не предназначена для выбора, фильтрации или событий по клику без дополнительного кода.

Кастомизация через расширение логики

При необходимости поведение колонки недели может быть расширено. Например, можно изменить отображение, добавив префиксы или кастомный формат:

const picker = new Pikaday({
    field: document.getElementById('date'),
    showWeekNumber: true,
    toString(date, format) {
        return moment(date).format('YYYY-MM-DD');
    }
});

Хотя toString не влияет напрямую на номер недели, он часто используется в связке с календарями, где week number отображается рядом с форматированной датой.

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

Поведение при разных локалях

Несмотря на наличие локализации в Pikaday, showWeekNumber чаще всего опирается на универсальную модель расчёта недель. Это означает:

  • локаль влияет на названия месяцев и дней;
  • номер недели остаётся стабильным и предсказуемым;
  • различия между регионами (например, США и Европа) не всегда учитываются автоматически.

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

Итоговая роль параметра в архитектуре календаря

showWeekNumber изменяет Pikaday не только визуально, но и концептуально: календарь перестаёт быть исключительно дневной сеткой и приобретает недельную структуру представления времени. Это влияет на способ восприятия данных и часто становится основой для более сложных календарных интерфейсов, где неделя выступает базовой единицей планирования.

Оглавление