Плагин weekSelect

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

Принцип работы и внутренняя модель выбора

Flatpickr по умолчанию оперирует единичными датами или диапазонами при включённом режиме range. weekSelect добавляет дополнительный слой абстракции:

  • визуально каждая строка календаря интерпретируется как неделя
  • при наведении подсвечивается весь ряд дат
  • при клике выбирается диапазон startOfWeek → endOfWeek
  • внутренне формируется массив из двух дат, совместимый с mode: “range”

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

Подключение плагина

Стандартная интеграция выполняется через массив plugins при инициализации календаря.

import flatpickr from "flatpickr";
import weekSelect from "flatpickr/dist/plugins/weekSelect/weekSelect";

flatpickr("#calendar", {
  plugins: [weekSelect({})]
});

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

Поведение выбора недели

При активации weekSelect меняется логика клика:

  • выбор даты в середине недели автоматически расширяется до всей недели
  • возвращаемое значение превращается в диапазон
  • отображение input поля становится строкой диапазона дат

Пример результата:

2026-06-01 to 2026-06-07

Фактически это эквивалент:

[
  "2026-06-01",
  "2026-06-07"
]

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

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

  • с воскресенья
  • с понедельника
  • с любого пользовательского дня

Flatpickr использует параметры locale для определения этого поведения:

flatpickr("#calendar", {
  locale: {
    firstDayOfWeek: 1
  },
  plugins: [weekSelect()]
});

Изменение firstDayOfWeek напрямую влияет на вычисление диапазона.

Визуальное представление недели

Плагин добавляет дополнительные CSS-классы к строкам календаря:

  • week — строка недели
  • selected — активная неделя
  • hover — подсветка при наведении

Структура DOM становится более семантической: каждая строка <tr> получает поведение интерактивного блока.

Пример стилизации:

.flatpickr-week {
  background: transparent;
}

.flatpickr-week.selected {
  background: rgba(0, 123, 255, 0.15);
}

.flatpickr-week:hover {
  background: rgba(0, 123, 255, 0.08);
}

Интеграция с режимом range

weekSelect фактически эмулирует поведение range-режима, поэтому возможны два подхода:

1. Без явного range режима

flatpickr("#calendar", {
  plugins: [weekSelect()]
});

В этом случае плагин самостоятельно формирует диапазон.

2. Совместно с range

flatpickr("#calendar", {
  mode: "range",
  plugins: [weekSelect()]
});

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

Обработка событий

Flatpickr сохраняет стандартные callback-и, но weekSelect влияет на входные данные.

onChange

flatpickr("#calendar", {
  plugins: [weekSelect()],
  onChange: function(selectedDates, dateStr, instance) {
    console.log(selectedDates);
  }
});

В selectedDates всегда приходит массив из двух дат: начало и конец недели.

Форматирование строки результата

Отображение строки в input формируется автоматически, но может быть переопределено через dateFormat:

flatpickr("#calendar", {
  dateFormat: "Y-m-d",
  plugins: [weekSelect()]
});

При этом диапазон будет выводиться как:

2026-06-01 - 2026-06-07

Локализация и недельные правила

Важный аспект работы плагина связан с локалями Flatpickr. В разных странах неделя интерпретируется по-разному:

  • Европа: понедельник — первый день недели
  • США: воскресенье — первый день недели

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

import { Russian } from "flatpickr/dist/l10n/ru.js";

flatpickr("#calendar", {
  locale: Russian,
  plugins: [weekSelect()]
});

Ограничения и особенности реализации

Механизм weekSelect имеет ряд технических особенностей:

  • не поддерживает частичный выбор дней внутри недели
  • всегда возвращает полный диапазон
  • может конфликтовать с custom disable-логикой дат
  • требует корректного вычисления startOfWeek при кастомных локалях

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

Сценарии применения

На практике weekSelect применяется в системах, где данные агрегируются по неделям:

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

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

Кастомизация поведения

Хотя плагин имеет минимальный набор настроек, его поведение можно расширять через комбинацию API Flatpickr:

flatpickr("#calendar", {
  plugins: [weekSelect()],
  onChange: (dates) => {
    const [start, end] = dates;
    // пользовательская логика обработки недели
  }
});

Дополнительная обработка позволяет:

  • нормализовать недели под ISO-стандарт
  • синхронизировать с backend API
  • пересчитывать финансовые периоды
  • блокировать определённые недели

Работа с ISO-неделями

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

Flatpickr не реализует ISO-нумерацию напрямую, но weekSelect можно адаптировать:

  • фиксировать firstDayOfWeek = 1
  • использовать внешнюю функцию расчёта номера недели
  • хранить метаданные отдельно от UI

Поведение при переключении месяцев

При переходе между месяцами weekSelect сохраняет логическую целостность недели:

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

Итоговая модель взаимодействия

weekSelect преобразует Flatpickr из календаря точечного выбора в инструмент недельной агрегации:

  • UI: строка недели вместо отдельных дней
  • input: диапазон дат
  • state: массив из двух дат
  • логика: вычисление границ недели на основе locale

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

Оглавление