Метод jumpToDate

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

Внутренне метод воздействует на навигационный слой календаря, не затрагивая массив выбранных дат (selectedDates) и не вызывая логики подтверждения выбора, если это не задано явно через параметры.

Сигнатура метода

fp.jumpToDate(date, triggerChange)

Параметры:

date

  • Тип: Date | string | number

  • Определяет целевую дату, к которой должен быть перемещён календарь.

  • Допускаются форматы:

    • объект Date
    • строка в формате, поддерживаемом Flatpickr
    • timestamp (число миллисекунд)

triggerChange

  • Тип: boolean
  • Опциональный параметр.
  • Определяет, будет ли вызвано событие onMonthChange и связанные колбэки при переходе.
  • По умолчанию: false

Поведение метода

При вызове jumpToDate происходит пересчёт внутреннего состояния отображения календаря:

  • обновляется текущий отображаемый месяц (currentMonth)
  • обновляется текущий отображаемый год (currentYear)
  • пересчитывается диапазон дней в сетке календаря
  • перерисовывается DOM календаря

При этом:

  • значение инпута (input.value) не изменяется
  • selectedDates остаётся без изменений
  • выделение даты сохраняется, но может оказаться вне видимой области

Отличие от setDate

Ключевое различие заключается в уровне воздействия на состояние:

  • setDate:

    • изменяет выбранную дату
    • обновляет input
    • может вызывать события onChange
    • влияет на selectedDates

  • jumpToDate:

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

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

Переход к конкретной дате

flatpickrInstance.jumpToDate(new Date(2026, 0, 15));

Календарь отобразит январь 2026 года, но выбранная дата останется прежней.

Переход по строковому значению

flatpickrInstance.jumpToDate("2025-12-01");

Flatpickr преобразует строку в дату, после чего откроет декабрь 2025 года.

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

flatpickrInstance.jumpToDate(1767225600000);

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

Поведение при открытом и закрытом календаре

Метод корректно работает в обоих состояниях:

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

Влияние на события

При вызове метода события зависят от второго параметра:

fp.jumpToDate(date, true);

При true могут сработать:

  • onMonthChange
  • onYearChange

При false (или отсутствии параметра):

  • события навигации не вызываются
  • переход считается программным и «тихим»

Работа с множественным выбором дат

В режиме mode: "multiple" или mode: "range" метод ведёт себя одинаково:

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

Использование в связке с API Flatpickr

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

fp.clear();
fp.jumpToDate("2027-03-01");
fp.open();

В этом сценарии:

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

Типичные сценарии применения

Синхронизация с внешними контролами

При наличии собственного UI навигации (например, кнопки «следующий месяц» вне календаря) используется jumpToDate для управления отображением:

nextButton.addEventListener("click", () => {
  const current = fp.currentYear * 12 + fp.currentMonth;
  const next = new Date(fp.currentYear, fp.currentMonth + 1, 1);
  fp.jumpToDate(next);
});

Программная прокрутка к выбранному значению

При загрузке данных из API:

fetch("/api/event")
  .then(res => res.json())
  .then(data => {
    fp.jumpToDate(data.eventDate);
  });

Фокус на диапазоне дат

В режиме диапазона часто используется переход к началу периода:

fp.jumpToDate(rangeStartDate);

Это позволяет визуально «подтянуть» календарь к началу интервала.

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

  • метод не валидирует логически выбранные даты
  • не изменяет состояние формы
  • не влияет на minDate/maxDate, кроме ограничения отображения
  • может визуально перейти к месяцу, где нет доступных дат, если ограничения не запрещают это

Внутренняя логика обновления

При вызове выполняется цепочка действий:

  1. Парсинг входной даты
  2. Определение целевого месяца и года
  3. Обновление currentMonth и currentYear
  4. Пересборка календарной сетки
  5. Обновление DOM-структуры дней
  6. При необходимости вызов колбэков

Частые ошибки при использовании

Передача некорректного значения

fp.jumpToDate("invalid-date");

Результат зависит от парсера Flatpickr и может привести к переходу на текущую дату или игнорированию вызова.

Ожидание изменения выбранной даты

fp.jumpToDate("2026-01-01");

Ошибочно ожидать, что дата будет выбрана. Метод не меняет selection.

Попытка использовать как setDate

Неправильная модель использования приводит к рассинхронизации UI и состояния.

Взаимодействие с локализацией и форматами

Метод не зависит от locale напрямую, но входные строки даты интерпретируются с учётом глобальных настроек парсинга Flatpickr. При нестандартных форматах рекомендуется использовать объект Date для предсказуемости.

Итоговое поведение в системе Flatpickr

jumpToDate представляет собой навигационный инструмент уровня UI, отделённый от логики выбора. Он управляет исключительно видимой частью календаря, обеспечивая гибкую программную навигацию без вмешательства в состояние формы и без триггера пользовательского выбора.

Оглавление