Полный список событий

В библиотеке Flatpickr события реализованы через систему callback-хуков, которые позволяют перехватывать ключевые моменты жизненного цикла календаря: инициализацию, открытие, закрытие, изменение даты, смену месяца и года, а также рендеринг отдельных дней. Все события передаются через конфигурационный объект при инициализации и получают единый контекст выполнения — экземпляр календаря и связанные с ним данные.

onReady

Срабатывает один раз после полной инициализации календаря и построения DOM-структуры.

Сигнатура:

onReady: function(selectedDates, dateStr, instance) {}

Параметры:

  • selectedDates — массив выбранных дат в формате Date
  • dateStr — строковое представление текущего значения
  • instance — экземпляр Flatpickr

Особенности:

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

onChange

Основное событие изменения значения даты.

Сигнатура:

onChange: function(selectedDates, dateStr, instance) {}

Параметры:

  • selectedDates — массив выбранных дат
  • dateStr — строка в формате, заданном в dateFormat
  • instance — текущий экземпляр календаря

Поведение:

  • вызывается при выборе даты пользователем
  • срабатывает при очистке значения
  • не вызывается при программном изменении через setDate, если не указан флаг triggerChange

Типичное применение:

  • синхронизация с формами
  • валидация даты
  • динамическое изменение интерфейса

onOpen

Срабатывает при открытии календаря.

Сигнатура:

onOpen: function(selectedDates, dateStr, instance) {}

Особенности:

  • вызывается перед отображением календаря
  • полезен для подготовки данных или интерфейса
  • может использоваться для lazy-load логики

Контекст: DOM календаря уже создан, но пользовательский фокус только устанавливается

onClose

Срабатывает при закрытии календаря.

Сигнатура:

onClose: function(selectedDates, dateStr, instance) {}

Применение:

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

Особенности:

  • вызывается как при выборе даты, так и при ручном закрытии
  • не вызывается при уничтожении экземпляра

onMonthChange

Срабатывает при смене месяца (включая навигацию стрелками или программное изменение).

Сигнатура:

onMonthChange: function(selectedDates, dateStr, instance) {}

Когда вызывается:

  • при переключении на следующий/предыдущий месяц
  • при установке месяца через API

Использование:

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

onYearChange

Срабатывает при изменении года.

Сигнатура:

onYearChange: function(selectedDates, dateStr, instance) {}

Поведение:

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

Типовые сценарии:

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

onValueUpdate

Срабатывает при любом обновлении значения, включая программные изменения.

Сигнатура:

onValueUpdate: function(selectedDates, dateStr, instance) {}

Отличие от onChange:

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

Сценарии использования:

  • синхронизация UI вне зависимости от источника изменения
  • реактивные интерфейсы
  • интеграция с фреймворками

onDayCreate

Срабатывает при создании каждого элемента дня в календарной сетке.

Сигнатура:

onDayCreate: function(dObj, dStr, fp, dayElem) {}

Параметры:

  • dObj — дата объекта Date
  • dStr — строковое представление даты
  • fp — экземпляр Flatpickr
  • dayElem — DOM-элемент конкретного дня

Особенности:

  • вызывается для каждого дня при рендере календаря
  • позволяет модифицировать DOM элемента дня

Применение:

  • кастомная подсветка дат (например, события, праздники)
  • добавление tooltip
  • визуальная маркировка диапазонов

onPreCalendarPosition

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

Сигнатура:

onPreCalendarPosition: function(selectedDates, dateStr, instance) {}

Назначение:

  • корректировка позиционирования
  • адаптация под кастомные контейнеры

Использование:

  • работа с модальными окнами
  • предотвращение выхода календаря за границы viewport
  • интеграция с нестандартными layout-системами

Взаимодействие событий между собой

События Flatpickr не изолированы и часто образуют цепочки:

  • onReady → первичная инициализация
  • onOpen → подготовка UI
  • onMonthChange / onYearChange → обновление сетки
  • onDayCreate → пост-обработка каждого дня
  • onChange → пользовательский выбор
  • onValueUpdate → финальная синхронизация состояния
  • onClose → завершение взаимодействия

Порядок выполнения может варьироваться в зависимости от способа изменения состояния (пользовательский ввод или API-вызовы).

Контекст выполнения событий

Все события получают общий контекст через instance, который содержит:

  • текущее значение календаря
  • DOM-узлы
  • методы управления (setDate, open, close, jumpToDate)
  • конфигурацию

Через этот объект осуществляется полное управление состоянием компонента, что делает систему событий Flatpickr централизованной и предсказуемой при корректной архитектуре обработки.

Оглавление