Плагин scrollPlugin

scrollPlugin представляет собой расширение для Flatpickr, добавляющее поддержку прокрутки (wheel/scroll interaction) для изменения значений в инпуте календаря и связанных полях. Основная задача плагина — обеспечить более естественное и быстрое управление датой и временем с помощью колесика мыши или жестов прокрутки, имитируя поведение «спиннеров» в нативных UI-компонентах.

Архитектурная роль scrollPlugin в Flatpickr

Flatpickr построен как модульная система, где ядро отвечает за:

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

Плагины расширяют поведение без модификации ядра. scrollPlugin относится к категории interaction-плагинов и работает на уровне DOM-событий, перехватывая:

  • wheel (прокрутка мыши)
  • touchpad gestures (частично через wheel)
  • keyboard fallback (в связке с другими плагинами)

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

Механика работы scrollPlugin

scrollPlugin привязывается к элементам ввода Flatpickr и отслеживает направление прокрутки:

  • прокрутка вверх → увеличение значения
  • прокрутка вниз → уменьшение значения

Дальнейшая логика зависит от контекста:

  • поле дня → изменение дня
  • поле месяца → изменение месяца
  • поле года → изменение года
  • поле времени → изменение часов/минут

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

  • setDate()
  • changeMonth()
  • changeYear()
  • setHours()/setMinutes()

Это важно: плагин не изменяет DOM напрямую, а работает через state-слой Flatpickr.

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

Плагин поставляется как отдельный модуль:

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

И подключается через конфигурацию:

flatpickr("#dateInput", {
  plugins: [scrollPlugin()]
});

Базовая инициализация не требует дополнительных параметров.

Поведение при разных типах input

Обычный календарь (date)

При использовании стандартного режима date:

  • прокрутка над инпутом изменяет выбранную дату
  • учитывается step логика календаря (дни/месяцы/годы)
  • переход между месяцами происходит автоматически при переполнении дней

Режим времени (enableTime)

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

  • прокрутка над часами изменяет часы
  • прокрутка над минутами изменяет минуты
  • при наличии seconds поддерживается третий уровень
flatpickr("#timeInput", {
  enableTime: true,
  noCalendar: true,
  dateFormat: "H:i",
  plugins: [scrollPlugin()]
});

Комбинированный режим (datetime)

В режиме datetime scrollPlugin разделяет контекст:

  • календарная часть реагирует на дату
  • time picker реагирует на время

При этом плагин определяет активный сегмент UI по DOM-структуре Flatpickr.

Внутренняя обработка событий

scrollPlugin регистрирует wheel handler с учётом следующих особенностей:

  • event.deltaY используется как основной источник направления
  • применяется throttling для предотвращения слишком быстрых изменений
  • блокируется native scroll при активном взаимодействии

Упрощённая логика:

  1. Перехват wheel события
  2. Определение направления
  3. Определение активного поля
  4. Вызов соответствующего метода Flatpickr
  5. Обновление UI

Ограничения и защита от некорректных значений

Flatpickr накладывает ограничения на scrollPlugin через внутренние правила:

  • нельзя выйти за пределы minDate/maxDate
  • учитываются disabledDates
  • учитываются enabled ranges
  • корректируется overflow (например, 31 → 1 число следующего месяца)

Это предотвращает неконсистентное состояние даты.

Интеграция с форматированием дат

scrollPlugin не влияет напрямую на формат отображения, но работает совместно с:

  • dateFormat
  • altInput
  • altFormat

Изменения через scrollPlugin всегда проходят через setDate, что автоматически триггерит перерасчёт форматирования.

Поведение с другими плагинами Flatpickr

monthSelectPlugin

При использовании плагина выбора месяца scrollPlugin усиливает UX:

  • прокрутка изменяет месяц без открытия календаря
  • учитывается ограничение year bounds

timePlugin / enableTime

  • прокрутка становится аналогом input spinner
  • ускоряет выбор времени без кликов

rangePlugin

  • scrollPlugin работает только на активной стороне диапазона
  • левая/правая дата обрабатываются отдельно

Производительность

scrollPlugin оптимизирован под минимальную нагрузку:

  • не использует polling
  • работает только на событиях wheel
  • не создаёт дополнительных DOM-нода
  • использует существующий state Flatpickr

Основная нагрузка возникает только при частых scroll-событиях, что контролируется через debounce/throttle.

Edge cases и особенности поведения

Touchpad прокрутка

На тачпадах deltaY может быть малым, поэтому:

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

MacOS inertia scrolling

Из-за инерции возможны:

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

Flatpickr частично компенсирует это ограничением скорости обновления.

Негативные значения deltaY

  • положительное значение → движение вниз → уменьшение даты
  • отрицательное значение → движение вверх → увеличение даты

CSS-влияние и область захвата

scrollPlugin не требует специальных CSS классов, но поведение зависит от:

  • области hover над input
  • focus состояния поля
  • z-index календаря (при открытом popover)

Если календарь открыт, приоритет может переходить к календарному UI вместо инпута.

Пример комплексной конфигурации

flatpickr("#datetime", {
  enableTime: true,
  time_24hr: true,
  minuteIncrement: 5,
  plugins: [scrollPlugin()],
  minDate: "2024-01-01",
  maxDate: "2027-12-31"
});

В такой конфигурации scrollPlugin управляет:

  • днями
  • месяцами
  • годами
  • часами
  • минутами с шагом 5

Взаимодействие с пользовательским вводом

scrollPlugin работает параллельно с ручным вводом:

  • ввод текста приоритетнее scroll
  • после blur значение нормализуется Flatpickr
  • scroll не перезаписывает активный ввод в момент печати

Типичные сценарии использования

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

Поведенческая модель в системе Flatpickr

scrollPlugin вписывается в общую модель Flatpickr как слой взаимодействия:

  • Input Layer → DOM события
  • Plugin Layer → scrollPlugin трансформация
  • Core Layer → обработка даты
  • Render Layer → обновление UI

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

Оглавление