Flatpickr исторически развивалась как библиотека с минимальным числом критических изменений API. Основная стратегия поддержания обратной совместимости заключается в сохранении поведения публичных методов и конфигураций при расширении функциональности. Это означает, что большинство опций, введённых в ранних версиях, продолжают работать в актуальных релизах без изменений, даже если внутри они были переработаны.
Ключевая особенность подхода — разделение публичного API и внутренней реализации. Внутренние модули могут полностью переписываться, однако контракт для разработчика остаётся стабильным. Это особенно важно для проектов, где Flatpickr используется в десятках форм и компонентов.
Большинство параметров инициализации сохраняют поведение между версиями, однако некоторые подвергались эволюционным изменениям.
Стабильные параметры:
dateFormatdefaultDateenabledisableminDate и maxDateinlinemodetime_24hrЭти опции считаются ядром API и практически не менялись с ранних версий.
Изменявшиеся параметры:
Некоторые параметры получили расширение поведения без удаления старой логики:
locale — ранее принимал ограниченный набор строковых
идентификаторов, позже был расширен до объектов локализации.wrap — поведение стало более строгим в отношении
структуры DOM.altInput — добавлены дополнительные правила
синхронизации значений.С точки зрения обратной совместимости важно учитывать, что старые строковые формы конфигурации продолжают работать, но новые версии рекомендуют использовать объектные расширения.
Одной из наиболее чувствительных зон совместимости является обработка дат.
Flatpickr использует собственный парсер, который сохраняет поддержку исторических форматов, но при этом расширяет возможности:
"Y-m-d",
"d/m/Y" и т.д.) сохраняется полностью.altInput сохраняется обратная совместимость
отображения и внутреннего значения.Изменения касались в основном обработки краевых случаев:
2020-13-01)Старые приложения, зависящие от «гибкого» парсинга, могут столкнуться с более строгой валидацией в новых версиях.
Flatpickr предоставляет программный API через объект инстанса. Обратная совместимость здесь критична, так как методы часто используются вне конфигурации.
Стабильные методы:
setDate()getDate()clear()destroy()open() и close()jumpToDate()Эти методы сохраняют сигнатуры и поведение.
Система событий (hooks) эволюционировала, но сохранила базовую структуру:
onChangeonOpenonCloseonReadyonMonthChangeonYearChangeВ ранних версиях callback-функции могли получать ограниченный набор аргументов. В новых версиях добавлены дополнительные параметры, но старые обработчики продолжают работать, игнорируя новые аргументы.
Пример эволюции сигнатуры:
onChange(selectedDates, dateStr)onChange(selectedDates, dateStr, instance)Старый код остаётся валидным, так как лишние параметры не нарушают выполнение функций.
Ранние версии Flatpickr допускали более свободную структуру DOM при
использовании wrap: true. В новых версиях структура стала
строго определённой:
data-input и data-toggle должны
быть явно размеченыСтарые реализации, где DOM был менее формализован, могут работать с предупреждениями или частичной деградацией функциональности.
Flatpickr не зависит от jQuery, однако исторически существовали обёртки вида:
$(element).flatpickr(options);Современные версии сохраняют возможность вызова через jQuery-обёртку, если она подключена отдельно. При этом:
Механизм локалей был расширен от простых объектов до полноценных конфигураций с функциями форматирования.
Ранее локали представляли собой:
flatpickr.localize(flatpickr.l10ns.ru);В новых версиях локали могут включать:
Обратная совместимость сохраняется через fallback-механизм: если поле отсутствует в новой локали, используется английская версия.
При переходе между мажорными версиями Flatpickr основная стратегия совместимости строится на следующих принципах:
Добавление вместо удаления Старые опции не удаляются сразу, а помечаются как deprecated.
Двойная поддержка форматов Новые форматы принимают старые входные данные.
Fallback-логика При отсутствии новых параметров используется поведение предыдущей версии.
Стабильность инстанса Объект fp
сохраняет структуру, даже если внутренние поля изменяются.
Некоторые параметры со временем теряют актуальность, но продолжают работать:
clickOpens — поведение может отличаться в зависимости
от версии браузераprevArrow / nextArrow — заменяются на
более гибкие шаблоныstatic — частично заменён логикой позиционирования
через CSSВажно, что deprecated-опции не вызывают ошибок, но могут игнорировать часть настроек или вести себя не так, как в ранних версиях.
Flatpickr поддерживает плагины, подключаемые через конфигурацию
plugins. В старых версиях плагины имели доступ к внутренним
структурам объекта инстанса, что делало их уязвимыми к изменениям.
В новых версиях:
Старые плагины могут требовать адаптации, особенно если они
использовали внутренние свойства вида _currentMonth или
_days.
Ранние версии допускали использование внутренних полей:
_input_wrap_currentMonth_selectedDateElemЭти поля не являются частью публичного API и могут меняться между релизами без уведомления. Несмотря на это, многие старые проекты продолжают их использовать, что создаёт потенциальные проблемы совместимости.
Современные версии рекомендуют замену на:
getDate, setDate)onChange, onReady)HTML-разметка календаря также претерпевала изменения, однако классы сохраняются в большинстве случаев:
.flatpickr-calendar.flatpickr-month.flatpickr-day.selected, .today,
.disabledИзменения касались внутренней иерархии и дополнительных контейнеров, но базовая CSS-модель остаётся совместимой, что позволяет старым стилям работать без переписывания.
Flatpickr сохраняет обратную совместимость за счёт:
Эта модель делает библиотеку устойчивой к обновлениям в долгоживущих проектах, где изменение зависимостей требует предсказуемого поведения интерфейса выбора даты.