Плагин monthSelect

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

Основная особенность заключается в том, что Flatpickr перестает работать с полноценными датами и переключается на уровень абстракции Month-Year. Внутренне библиотека по-прежнему оперирует объектами Date, однако отображение и ввод ограничиваются выбором месяца.

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

Для использования monthSelect требуется подключение соответствующего модуля из пакета Flatpickr. В современных сборщиках модуль импортируется отдельно:

import flatpickr from "flatpickr";
import monthSelectPlugin from "flatpickr/dist/plugins/monthSelect";
import "flatpickr/dist/plugins/monthSelect/style.css";

После подключения плагин активируется через параметр plugins при инициализации календаря:

flatpickr("#monthPicker", {
  plugins: [
    monthSelectPlugin({
      shorthand: true,
      dateFormat: "Y-m",
      altFormat: "F Y"
    })
  ]
});

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

Конфигурационные параметры monthSelect

Плагин предоставляет набор параметров, влияющих на форматирование и поведение интерфейса.

shorthand

Определяет формат отображения месяца:

  • true — сокращённые названия месяцев (Jan, Feb, Mar)
  • false — полные названия месяцев
monthSelectPlugin({
  shorthand: false
});

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

dateFormat

Определяет формат значения, которое будет сохраняться в input.

Чаще всего используется один из вариантов:

  • "Y-m" — год и месяц в числовом формате
  • "m/Y" — альтернативный формат с разделением слэшем
monthSelectPlugin({
  dateFormat: "Y-m"
});

Формат влияет на значение, которое будет отправлено в формы или API.

altFormat

Отвечает за визуальное представление выбранного значения в поле ввода при использовании альтернативного отображения Flatpickr.

monthSelectPlugin({
  altFormat: "F Y"
});

В этом случае пользователь видит «March 2026», тогда как фактическое значение может быть 2026-03.

theme integration

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

Внутренняя модель данных

Несмотря на ограничение выбора до месяца, Flatpickr продолжает использовать объект Date. При выборе месяца создается дата, где:

  • день фиксируется на 1
  • время устанавливается в 00:00:00
  • месяц соответствует выбранному значению

Пример внутреннего представления:

new Date(2026, 2, 1) // март 2026

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

Режим отображения интерфейса

monthSelect заменяет стандартную сетку календаря на компактную панель, содержащую:

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

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

Ограничение диапазонов (min/max)

Плагин корректно работает с ограничениями minDate и maxDate. Однако ограничения применяются на уровне месяцев.

flatpickr("#monthPicker", {
  minDate: "2023-01",
  maxDate: "2026-12",
  plugins: [
    monthSelectPlugin({
      dateFormat: "Y-m"
    })
  ]
});

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

Локализация и языковые настройки

monthSelect поддерживает локализацию через стандартный механизм Flatpickr locale. Это влияет на:

  • названия месяцев
  • формат отображения
  • навигационные элементы
import { Russian } from "flatpickr/dist/l10n/ru.js";

flatpickr("#monthPicker", {
  locale: Russian,
  plugins: [
    monthSelectPlugin({
      shorthand: false
    })
  ]
});

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

Интеграция с формами

Значение, получаемое из monthSelect, может использоваться в стандартных HTML-формах. При сабмите отправляется строка, заданная в dateFormat.

Типичный сценарий:

<form>
  <input id="monthPicker" name="period" />
  <button type="submit">Отправить</button>
</form>
flatpickr("#monthPicker", {
  plugins: [
    monthSelectPlugin({
      dateFormat: "Y-m"
    })
  ]
});

На сервер будет отправлено значение вида:

2026-03

Программное управление значением

Flatpickr с monthSelect поддерживает программную установку значения через setDate.

const picker = flatpickr("#monthPicker", {
  plugins: [
    monthSelectPlugin({
      dateFormat: "Y-m"
    })
  ]
});

picker.setDate("2025-11");

При установке значения автоматически обновляется UI и подсвечивается соответствующий месяц.

Очистка значения

Очистка выполняется стандартным методом Flatpickr:

picker.clear();

После вызова значение input сбрасывается, а активный месяц снимается.

Поведение при альтернативном вводе

При ручном вводе значения в input Flatpickr пытается интерпретировать строку в соответствии с dateFormat. Если формат не соответствует ожидаемому, значение считается некорректным и не применяется.

Для повышения устойчивости рекомендуется ограничивать ввод через allowInput: false:

flatpickr("#monthPicker", {
  allowInput: false,
  plugins: [
    monthSelectPlugin({
      dateFormat: "Y-m"
    })
  ]
});

Особенности рендера и производительности

monthSelect имеет упрощённый DOM по сравнению с обычным календарем Flatpickr. Это снижает нагрузку при инициализации и делает его предпочтительным для:

  • массовых фильтров в таблицах
  • аналитических панелей
  • dashboard-интерфейсов

Количество DOM-узлов уменьшается за счёт отсутствия ежедневной сетки.

Кастомизация внешнего вида

Стилизация выполняется через стандартные классы Flatpickr с добавлением контейнерных модификаторов плагина. Основные направления кастомизации:

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

Пример переопределения:

.flatpickr-monthSelect-month {
  padding: 10px;
  border-radius: 6px;
}

.flatpickr-monthSelect-month.selected {
  background: #3b82f6;
  color: #fff;
}

Использование в фильтрах диапазонов

monthSelect часто применяется для формирования диапазонов аналитики:

const start = flatpickr("#startMonth", {
  plugins: [monthSelectPlugin({ dateFormat: "Y-m" })]
});

const end = flatpickr("#endMonth", {
  plugins: [monthSelectPlugin({ dateFormat: "Y-m" })]
});

Полученные значения удобно использовать для SQL-запросов или фильтрации API:

WHERE period >= '2025-01' AND period <= '2026-03'

Совместимость с другими плагинами Flatpickr

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

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

Основной принцип интеграции — отсутствие пересечения ответственности между плагинами.

Обработка событий

monthSelect использует стандартные события Flatpickr:

  • onChange — при выборе месяца
  • onOpen — при открытии интерфейса
  • onYearChange — при переключении года
flatpickr("#monthPicker", {
  plugins: [monthSelectPlugin()],
  onChange: (selectedDates, dateStr) => {
    console.log(dateStr);
  }
});

События позволяют синхронизировать компонент с внешними состояниями, например store или URL-параметрами.

Оглавление