Подключение плагинов

Механизм расширения в Flatpickr построен вокруг идеи модульной надстройки над базовым календарём. Плагин в этой системе представляет собой функцию, которая получает ссылку на экземпляр календаря и возвращает объект с хуками жизненного цикла. Такой подход позволяет внедряться в ключевые этапы работы компонента: инициализацию, рендер, обработку выбора дат, обновление состояния и уничтожение инстанса.

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

Способ подключения и базовая структура

Подключение плагина осуществляется через параметр plugins при инициализации Flatpickr. В этот массив передаются функции-плагины, каждая из которых вызывается с текущим экземпляром календаря.

import flatpickr from "flatpickr";
import "flatpickr/dist/flatpickr.min.css";

import confirmDatePlugin from "flatpickr/dist/plugins/confirmDate/confirmDate";

flatpickr("#input", {
  plugins: [confirmDatePlugin()]
});

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

function myPlugin(fp) {
  return {
    onReady() {},
    onChange() {},
    onDestroy() {}
  };
}

Жизненный цикл плагинов

Flatpickr вызывает методы плагинов строго в рамках своего жизненного цикла:

  • onParseConfig — обработка конфигурации до инициализации
  • onReady — календарь создан и вставлен в DOM
  • onMonthChange — смена месяца
  • onYearChange — смена года
  • onValueUpdate — обновление значения
  • onOpen / onClose — открытие и закрытие календаря
  • onDestroy — уничтожение экземпляра

Использование этих хуков позволяет плагину вмешиваться в работу UI без прямого доступа к внутренним методам библиотеки.

Встроенные плагины Flatpickr

Подтверждение выбора даты (confirmDatePlugin)

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

import confirmDatePlugin from "flatpickr/dist/plugins/confirmDate/confirmDate";

flatpickr("#input", {
  enableTime: true,
  plugins: [
    confirmDatePlugin({
      confirmText: "OK",
      showAlways: true
    })
  ]
});

Основные возможности:

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

Диапазоны дат (rangePlugin)

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

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

flatpickr("#start", {
  plugins: [rangePlugin({ input: "#end" })]
});

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

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

Логика работы строится на перехвате событий изменения значения и перераспределении массива дат внутри экземпляра Flatpickr.

Выбор месяца (monthSelectPlugin)

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

import monthSelectPlugin from "flatpickr/dist/plugins/monthSelect";

flatpickr("#month", {
  plugins: [
    monthSelectPlugin({
      shorthand: true,
      dateFormat: "F Y"
    })
  ]
});

Основные параметры:

  • shorthand — отображение сокращённых названий месяцев
  • dateFormat — формат вывода значения
  • отключение календарной сетки дней

Этот плагин фактически заменяет стандартный view на упрощённый селектор.

Выбор недели (weekSelectPlugin)

Плагин добавляет возможность выбора целой недели вместо конкретной даты.

import weekSelectPlugin from "flatpickr/dist/plugins/weekSelect/weekSelect";

flatpickr("#week", {
  plugins: [weekSelectPlugin()]
});

Функциональность:

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

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

Порядок инициализации плагинов

Плагины выполняются в том порядке, в котором они указаны в массиве plugins. Это влияет на итоговое состояние конфигурации.

flatpickr("#input", {
  plugins: [
    pluginA(),
    pluginB(),
    pluginC()
  ]
});

Критически важно учитывать:

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

Создание собственного плагина

Flatpickr предоставляет простой контракт для разработки расширений. Плагин — это функция, принимающая экземпляр fp и возвращающая объект с методами.

function highlightTodayPlugin(fp) {
  return {
    onReady() {
      const today = fp.calendarContainer.querySelector(".today");
      if (today) {
        today.classList.add("highlight-today");
      }
    }
  };
}

Структура API:

  • доступ к fp.selectedDates
  • доступ к DOM через fp.calendarContainer
  • доступ к конфигурации через fp.config
  • возможность модификации значений через fp.setDate

Работа с событиями внутри плагинов

Плагины могут подписываться на события Flatpickr через внутренний механизм callback-хуков.

Пример обработки изменения даты:

function loggerPlugin(fp) {
  return {
    onChange(selectedDates) {
      console.log("Выбранные даты:", selectedDates);
    }
  };
}

При необходимости можно комбинировать несколько событий:

  • onOpen для инициализации UI
  • onMonthChange для кастомной логики отображения
  • onValueUpdate для синхронизации с внешними системами

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

Плагины могут изменять поведение календаря до его инициализации через onParseConfig.

function limitPlugin(fp) {
  return {
    onParseConfig() {
      fp.config.minDate = new Date();
    }
  };
}

Такой подход используется для:

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

Расширение DOM через плагины

Плагины часто используются для добавления собственных элементов интерфейса в календарь.

function footerPlugin(fp) {
  return {
    onReady() {
      const footer = document.createElement("div");
      footer.className = "fp-footer";
      footer.textContent = "Custom footer";

      fp.calendarContainer.appendChild(footer);
    }
  };
}

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

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

Ограничения и конфликтные ситуации

При использовании нескольких плагинов одновременно возникают типичные ограничения:

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

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

Для минимизации проблем применяется:

  • строгий порядок подключения
  • изоляция DOM-логики
  • проверка существующих значений перед изменением состояния
Оглавление