Событие onChange

Событие onChange в Flatpickr является одним из ключевых механизмов реактивного отслеживания изменений выбранной даты. Оно срабатывает каждый раз, когда пользователь изменяет значение календаря: выбирает новую дату, добавляет элемент в режиме multiple, завершает выбор диапазона или очищает поле.

Событие onChange вызывается после того, как внутреннее состояние выбора даты уже обновлено. Это важный аспект: обработчик получает уже финальные данные, а не промежуточное состояние UI.

Событие активируется в следующих сценариях:

  • выбор одиночной даты в режиме single
  • выбор начальной и конечной даты в режиме range
  • добавление или удаление элементов в режиме multiple
  • очистка значения (если разрешена опция allowInput и выполняется сброс)
  • программное изменение значения через setDate (если явно разрешено триггерить события)

Сигнатура обработчика

Базовая форма события выглядит следующим образом:

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

Параметры:

  • selectedDates — массив объектов Date, отражающий текущее состояние выбора
  • dateStr — строковое представление выбранной даты согласно dateFormat
  • instance — текущий экземпляр календаря Flatpickr

Структура данных selectedDates

selectedDates всегда возвращается как массив, даже в режиме single.

Примеры:

single

selectedDates = [Date]

multiple

selectedDates = [Date, Date, Date]

range

selectedDates = [startDate, endDate]

Если диапазон выбран частично, массив содержит один элемент.

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

Параметр dateStr формируется на основе конфигурации:

  • dateFormat
  • altInput
  • altFormat
  • локализация (locale)

Пример:

dateStr = "2026-05-31"

или в кастомном формате:

dateStr = "31 May 2026"

В режиме range строка формируется с разделителем:

"2026-05-01 to 2026-05-10"

Разделитель зависит от настройки rangeSeparator.

Базовый пример использования

flatpickr("#date", {
  onChange: function(selectedDates, dateStr, instance) {
    console.log(selectedDates);
    console.log(dateStr);
  }
});

Работа в режиме single

В режиме одиночного выбора событие отражает единственное значение массива:

flatpickr("#date", {
  mode: "single",
  onChange: function(selectedDates) {
    const date = selectedDates[0];
    console.log(date);
  }
});

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

Работа в режиме multiple

В режиме множественного выбора событие фиксирует каждое добавление или удаление даты.

flatpickr("#date", {
  mode: "multiple",
  onChange: function(selectedDates, dateStr) {
    console.log(selectedDates.length);
    console.log(dateStr);
  }
});

Поведение:

  • повторный выбор уже выбранной даты приводит к её удалению
  • массив selectedDates всегда отражает актуальный набор

Работа в режиме range

В режиме диапазона событие вызывается дважды:

  1. после выбора стартовой даты
  2. после выбора конечной даты
flatpickr("#date", {
  mode: "range",
  onChange: function(selectedDates) {
    if (selectedDates.length === 1) {
      console.log("Start:", selectedDates[0]);
    } else {
      console.log("Range:", selectedDates);
    }
  }
});

Особенность поведения:

  • первый клик фиксирует начало диапазона
  • второй клик завершает диапазон
  • повторный выбор сбрасывает диапазон

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

Событие onChange также связано с методами API:

setDate

instance.setDate("2026-06-01", true);

Второй аргумент (true) определяет, будет ли вызван onChange.

clear

instance.clear();

Очистка также инициирует onChange при активной конфигурации.

Использование instance внутри onChange

Объект instance предоставляет доступ к состоянию календаря:

onChange: function(selectedDates, dateStr, instance) {
  console.log(instance.currentMonth);
  console.log(instance.config.mode);
}

Доступные данные:

  • текущий месяц и год
  • конфигурация
  • DOM-элементы
  • локальные методы управления

Частые сценарии применения

Валидация значения

onChange: function(selectedDates) {
  if (selectedDates.length === 0) return;

  const date = selectedDates[0];
  if (date.getDay() === 0) {
    console.log("Воскресенье");
  }
}

Связка с формой

onChange: function(selectedDates, dateStr) {
  document.querySelector("#hidden").value = dateStr;
}

Динамическое обновление интерфейса

onChange: function(selectedDates) {
  const output = document.querySelector("#output");
  output.textContent = selectedDates.length;
}

Особенности повторных вызовов

Событие может вызываться несколько раз подряд в следующих ситуациях:

  • переключение месяцев при выборе диапазона
  • автокоррекция некорректного ввода
  • работа с time_enable и изменением времени
  • включённый clickOpens и повторные открытия

Отличие от onSelect

Внутри Flatpickr существует также событие onSelect, однако:

  • onChange ориентирован на изменение значения в целом
  • onSelect может срабатывать на промежуточные клики в UI

onChange считается более стабильным источником финального значения.

Работа с time picker

При включённом времени:

flatpickr("#date", {
  enableTime: true,
  onChange: function(selectedDates, dateStr) {
    console.log(dateStr);
  }
});

Событие учитывает изменения:

  • часов
  • минут
  • секунд (если включено enableSeconds)

Любое изменение времени вызывает повторный onChange.

Оптимизация обработки

При частых вызовах события важна минимизация тяжёлых операций:

  • избегание DOM-рендеринга внутри обработчика
  • кэширование ссылок на элементы
  • разделение логики вычислений и отображения
const output = document.querySelector("#output");

flatpickr("#date", {
  onChange: function(selectedDates) {
    requestAnimationFrame(() => {
      output.textContent = selectedDates.length;
    });
  }
});

Работа с форматом строки

При необходимости можно игнорировать selectedDates и использовать только dateStr, если форматирование уже соответствует бизнес-логике:

onChange: function(_, dateStr) {
  console.log(dateStr);
}

Поведение при очистке значения

Если поле очищается вручную или через API:

  • selectedDates становится пустым массивом
  • dateStr становится пустой строкой
onChange: function(selectedDates, dateStr) {
  if (!dateStr) {
    console.log("очищено");
  }
}

Влияние конфигурации allowInput

При allowInput: true пользователь может вводить значения вручную, и onChange срабатывает после валидации введённой строки и её преобразования в дату.

Ключевые особенности поведения

  • всегда возвращается массив дат
  • срабатывает после обновления состояния
  • зависит от режима работы календаря
  • тесно связан с API setDate, clear
  • используется как основной механизм синхронизации UI и данных
Оглавление