Событие onMonthChange

Назначение события

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

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

Сигнатура и параметры обработчика

Событие задаётся через опцию onMonthChange при инициализации Flatpickr:

flatpickr(element, {
    onMonthChange: function(selectedDates, dateStr, instance) {
        // логика обработки
    }
});

Параметры:

  • selectedDates — массив выбранных дат (Date[]). В контексте onMonthChange может быть пустым, если пользователь ещё ничего не выбрал.
  • dateStr — строковое представление текущего значения инпута согласно формату dateFormat.
  • instance — экземпляр Flatpickr, предоставляющий доступ к внутреннему состоянию календаря.

Механизм срабатывания

Событие инициируется при изменении внутреннего состояния currentMonth и currentYear экземпляра Flatpickr. Это происходит в следующих случаях:

  • нажатие кнопки «следующий месяц»;
  • нажатие кнопки «предыдущий месяц»;
  • выбор месяца через UI (если подключены соответствующие плагины);
  • программное изменение даты через setDate, приводящее к смене месяца отображения;
  • вызов методов навигации API, таких как changeMonth.

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

Доступ к текущему состоянию календаря

Через объект instance можно получить актуальные данные о текущем отображаемом месяце:

onMonthChange: function(selectedDates, dateStr, instance) {
    const month = instance.currentMonth;
    const year = instance.currentYear;

    console.log(`Текущий месяц: ${month}, год: ${year}`);
}

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

  • currentMonth возвращает индекс месяца (0–11);
  • currentYear возвращает полный год;
  • состояние обновляется до вызова обработчика.

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

1. Динамическая подгрузка данных

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

onMonthChange: function(selectedDates, dateStr, instance) {
    fetch(`/api/events?month=${instance.currentMonth + 1}&year=${instance.currentYear}`)
        .then(response => response.json())
        .then(data => {
            console.log(data);
        });
}

2. Ограничение доступности дат

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

onMonthChange: function(selectedDates, dateStr, instance) {
    updateDisabledDates(instance.currentMonth, instance.currentYear);
}

Функция updateDisabledDates может обновлять disable или enable конфигурацию через set.

3. Синхронизация с внешним календарём

При наличии кастомного UI или стороннего календаря требуется синхронизация текущего месяца.

onMonthChange: function(selectedDates, dateStr, instance) {
    externalCalendar.setMonth(instance.currentMonth);
    externalCalendar.setYear(instance.currentYear);
}

Отличие от похожих событий

Flatpickr предоставляет несколько событий, связанных с изменением состояния, и важно различать их:

  • onMonthChange — смена месяца отображения;
  • onYearChange — смена года;
  • onValueUpdate — обновление значения инпута;
  • onChange — выбор даты пользователем.

onMonthChange не гарантирует изменение выбранной даты, а лишь изменение визуального контекста календаря.

Особенности поведения при mode: "range"

В режиме диапазона (range) смена месяца может происходить чаще из-за навигации между начальной и конечной датой диапазона. При этом:

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

Взаимодействие с программным API

Событие вызывается и при программном управлении календарём:

instance.changeMonth(1);

или:

instance.setDate("2026-06-15");

Если в результате этих операций меняется отображаемый месяц, onMonthChange будет вызван автоматически.

Частота вызовов и производительность

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

Рекомендуемые подходы оптимизации:

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

Работа с индексами месяцев

Flatpickr использует нумерацию месяцев с нуля:

  • 0 — январь;
  • 1 — февраль;
  • …
  • 11 — декабрь.

Это необходимо учитывать при взаимодействии с API, которые используют стандартную нумерацию (1–12).

const apiMonth = instance.currentMonth + 1;

Влияние локализации

Локализация (locale) влияет на отображение названий месяцев, но не влияет на значение currentMonth. В обработчике всегда возвращается числовой индекс, независимый от языка интерфейса.

Сочетание с minDate и maxDate

При достижении ограничений:

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

Использование для календарей событий

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

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

Типичный шаблон:

onMonthChange: function(_, __, instance) {
    const { currentMonth, currentYear } = instance;

    loadCalendarEvents(currentYear, currentMonth)
        .then(events => renderEvents(events));
}

Поведение при инициализации

При создании Flatpickr событие onMonthChange не вызывается автоматически, если пользователь не совершает навигацию. Исключение составляют случаи, когда:

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

Связь с внутренним рендерингом

Каждое изменение месяца приводит к полному пересчёту сетки календаря:

  • перерасчёт дней недели;
  • обновление пустых ячеек до начала месяца;
  • применение ограничений disable и enable;
  • перерисовка DOM-контейнера календаря.

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

Оглавление