Сигнатуры функций

Базовой точкой входа Flatpickr является функция инициализации, через которую создаётся экземпляр календаря и связывается с DOM-элементом.

Сигнатура инициализатора

flatpickr(element: Node | string, config?: Object): Instance

Параметры:

  • element: Node | string — DOM-элемент input-поля либо CSS-селектор, к которому привязывается календарь
  • config?: Object — объект конфигурации с параметрами поведения, отображения и логики

Возвращаемое значение:

  • Instance — объект экземпляра Flatpickr с набором методов управления календарём

Варианты вызова

flatpickr("#dateInput");

flatpickr(document.querySelector("#dateInput"));

flatpickr(".date-field", {
  dateFormat: "Y-m-d"
});

Поведение перегрузки

Сигнатура допускает несколько режимов работы:

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

Сигнатура конфигурационного объекта

Конфигурация Flatpickr не имеет жёстко фиксированной структуры на уровне JS-типов, но логически представляет собой набор строго ожидаемых ключей.

config: {
  dateFormat?: string,
  enableTime?: boolean,
  minDate?: Date | string,
  maxDate?: Date | string,
  defaultDate?: Date | string | Array,
  mode?: "single" | "multiple" | "range",
  locale?: Object,
  onChange?: Function,
  onOpen?: Function,
  onClose?: Function,
  parseDate?: Function,
  formatDate?: Function
}

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

Сигнатуры callback-хуков

Flatpickr использует событийную модель через набор callback-функций. Все они имеют предсказуемую сигнатуру с одинаковой базовой структурой аргументов.

onChange

onChange: function(selectedDates, dateStr, instance)
  • selectedDates: Date[] — массив выбранных дат
  • dateStr: string — строковое представление даты согласно dateFormat
  • instance: Instance — текущий экземпляр Flatpickr

Поведение зависит от режима:

  • single → массив из одного элемента
  • multiple → массив всех выбранных дат
  • range → массив из двух значений (start/end)

onOpen

onOpen: function(selectedDates, dateStr, instance)

Вызывается при открытии календаря. Несмотря на одинаковую сигнатуру с onChange, selectedDates в этом контексте отражает текущее состояние, а не новое значение.

onClose

onClose: function(selectedDates, dateStr, instance)

Срабатывает при закрытии календаря. Часто используется для валидации или синхронизации с внешними состояниями.

onReady

onReady: function(selectedDates, dateStr, instance)

Вызывается один раз после полной инициализации. На этом этапе DOM календаря уже построен.

onMonthChange

onMonthChange: function(selectedDates, dateStr, instance)

Сигнатура совпадает с базовой, но контекст события связан с навигацией по месяцам.

onYearChange

onYearChange: function(selectedDates, dateStr, instance)

Используется при изменении года через UI или API.

Сигнатуры методов экземпляра

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

setDate

setDate: function(
  date: Date | string | number | Array,
  triggerChange?: boolean,
  format?: string
)

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

  • date — дата или массив дат
  • triggerChange — флаг, вызывающий onChange
  • format — формат входной строки

Используется для программного изменения значения.

clear

clear: function(triggerChange?: boolean)

Очищает выбранные даты.

  • triggerChange = true → вызывает onChange с пустым значением

open

open: function()

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

close

close: function()

Без параметров. Закрывает интерфейс календаря.

destroy

destroy: function()

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

jumpToDate

jumpToDate: function(date: Date | string, triggerChange?: boolean)
  • date — целевая дата для навигации
  • triggerChange — влияет на вызов событий

Сигнатуры функций форматирования дат

Flatpickr предоставляет две ключевые функции для трансформации данных: parseDate и formatDate.

formatDate

formatDate: function(date: Date, format: string, locale?: Object): string

Аргументы:

  • date: Date — объект даты JavaScript
  • format: string — строка формата (например "Y-m-d")
  • locale?: Object — локализация (названия месяцев, дней и т.д.)

Возвращаемое значение:

  • строка, соответствующая формату

parseDate

parseDate: function(dateStr: string, format: string, timeless?: boolean, locale?: Object): Date

Аргументы:

  • dateStr — входная строка
  • format — формат, по которому выполняется разбор
  • timeless — если true, обнуляет временную часть
  • locale — локализация

Возвращаемое значение:

  • объект Date

Сигнатуры внутренних утилит и вспомогательных API

Хотя они не всегда документированы как публичные, их сигнатуры важны для расширений.

l10n (локализация)

l10n: {
  weekdays: {
    shorthand: string[],
    longhand: string[]
  },
  months: {
    shorthand: string[],
    longhand: string[]
  }
}

Используется всеми функциями форматирования и отображения.

форматтер даты внутри движка

Внутренняя сигнатура:

formatDateInternal(date, format, locale, isUTC)
  • isUTC влияет на вычисление времени и смещение таймзоны

Сигнатуры кастомных плагинов

Flatpickr поддерживает расширения через плагины, которые имеют строго определённую сигнатуру.

Плагин

function plugin(instance) {
  return function(fp) {
    return {
      onParseConfig: function(),
      onReady: function(),
      onDestroy: function()
    }
  }
}

Структура:

  • внешний вызов получает instance
  • внутренний возвращаемый объект привязывается к жизненному циклу Flatpickr

Сигнатуры событий DOM-уровня

Flatpickr также генерирует DOM-события, которые можно перехватывать через стандартный addEventListener.

Общая форма события

event.detail: {
  fp: Instance,
  ...additionalData
}

Пример сигнатуры обработчика:

element.addEventListener("change", function(event: CustomEvent) {
  const instance = event.detail.fp;
});

Сигнатуры работы с диапазонами дат

Режим range влияет на типизацию аргументов во всех ключевых сигнатурах.

onChange в range-режиме

onChange: function(
  selectedDates: [Date?, Date?],
  dateStr: string,
  instance: Instance
)
  • индекс 0 → начало диапазона
  • индекс 1 → конец диапазона (может быть undefined)

Сигнатуры локалей

Объект локали имеет предсказуемую структуру:

locale: {
  firstDayOfWeek: number,
  weekdays: {
    shorthand: string[],
    longhand: string[]
  },
  months: {
    shorthand: string[],
    longhand: string[]
  }
}

Сигнатуры пользовательских форматов

Формат строк dateFormat не является функцией, но определяет контракт входа/выхода всех форматирующих сигнатур.

Пример допустимых форматов:

  • "Y-m-d"
  • "d.m.Y"
  • "H:i"
  • "Y-m-d H:i"

Каждый символ формата соответствует внутреннему токену парсинга, который интерпретируется функциями parseDate и formatDate.

Оглавление