Событие onReady

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

onReady выполняется один раз на каждый экземпляр и служит точкой, где календарь гарантированно находится в стабильном состоянии: структура DOM существует, внутренние вычисления завершены, события навешены, а начальные даты уже интерпретированы библиотекой.

Момент вызова и жизненный цикл

Инициализация Flatpickr проходит несколько этапов:

  1. Создание экземпляра и парсинг конфигурации
  2. Построение DOM-структуры календаря
  3. Применение локализации и форматов
  4. Установка начальных значений
  5. Привязка событий
  6. Вызов onReady

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

Важно, что к моменту вызова:

  • календарь уже добавлен в DOM (если inline: true)
  • popup уже создан (если используется всплывающий режим)
  • вычислены ограничения (minDate, maxDate)
  • обработаны режимы single, multiple, range

Сигнатура и параметры

Событие onReady принимает стандартный набор аргументов, идентичный другим хукам Flatpickr:

onReady: function(selectedDates, dateStr, instance) {
    // логика
}

selectedDates

Массив объектов Date, содержащий уже выбранные даты на момент инициализации.

  • В режиме single — массив из одного элемента или пустой
  • В режиме multiple — набор выбранных дат
  • В режиме range — две даты (начало и конец диапазона)

dateStr

Строковое представление выбранной даты в формате, заданном через dateFormat.

Пример:

"2026-05-31"

instance

Ссылка на текущий экземпляр Flatpickr. Через него доступна вся внутренняя API:

  • instance.calendarContainer
  • instance.input
  • instance.config
  • instance.jumpToDate()
  • instance.open() / close()

Практическое назначение onReady

Событие используется для задач, которые требуют гарантированного наличия DOM и полностью инициализированного состояния календаря.

Модификация DOM после построения

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

flatpickr("#date", {
    onReady: function(selectedDates, dateStr, instance) {
        const calendar = instance.calendarContainer;

        const footer = document.createElement("div");
        footer.className = "fp-footer";
        footer.textContent = "Выбор даты активен";

        calendar.appendChild(footer);
    }
});

Программная настройка интерфейса

На этапе onReady можно изменять поведение календаря, не опасаясь перезаписи внутренними процессами Flatpickr:

onReady: function(_, __, instance) {
    instance.set("weekNumbers", true);
    instance.set("altInputClass", "custom-input");
}

Хотя часть конфигурации лучше задавать до инициализации, onReady полезен для динамических условий, зависящих от окружения.

Синхронизация с внешним UI

Частый сценарий — синхронизация состояния календаря с внешними компонентами интерфейса. Поскольку onReady гарантирует завершение инициализации, он используется как точка старта взаимодействия:

onReady: function(selectedDates, dateStr, instance) {
    document.querySelector("#status").textContent = "Календарь готов";

    if (selectedDates.length === 0) {
        document.querySelector("#hint").style.display = "block";
    }
}

Отличие от onOpen и onChange

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

onReady

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

onOpen

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

onChange

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

Работа с асинхронной логикой

Несмотря на синхронную природу вызова, onReady часто используется как триггер для запуска асинхронных процессов, связанных с календарём.

Например, загрузка ограничений дат с сервера:

onReady: function(_, __, instance) {
    fetch("/api/unavailable-dates")
        .then(res => res.json())
        .then(data => {
            instance.set("disable", data);
        });
}

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

Взаимодействие с режимами multiple и range

multiple

При множественном выборе onReady позволяет обработать уже существующие значения:

onReady: function(selectedDates, dateStr, instance) {
    selectedDates.forEach(date => {
        console.log("Выбрана дата:", date);
    });
}

range

В режиме диапазона onReady особенно полезен для валидации уже установленного диапазона:

onReady: function(selectedDates, dateStr, instance) {
    if (selectedDates.length === 2) {
        const [start, end] = selectedDates;

        if (start > end) {
            instance.clear();
        }
    }
}

Доступ к DOM-структуре календаря

Ключевое преимущество onReady — полный доступ к DOM после генерации интерфейса.

Основные узлы:

  • instance.calendarContainer — основной контейнер календаря
  • instance.daysContainer — сетка дней
  • instance.monthNav — навигация по месяцам
  • instance.currentMonthElement — текущий месяц
  • instance.currentYearElement — текущий год

Пример модификации навигации:

onReady: function(_, __, instance) {
    const nav = instance.monthNav;
    nav.classList.add("custom-nav");
}

Влияние конфигурации на поведение onReady

Некоторые параметры конфигурации напрямую влияют на состояние, доступное в onReady:

  • defaultDate — определяет initial selectedDates
  • inline — влияет на момент и способ рендеринга
  • mode — изменяет структуру выбранных дат
  • enableTime — добавляет временные элементы в DOM

Пример:

flatpickr("#date", {
    defaultDate: "2026-05-31",
    enableTime: true,
    onReady: function(selectedDates, dateStr, instance) {
        console.log(selectedDates); // уже содержит дату
    }
});

Ограничения использования

Несмотря на широкие возможности, onReady имеет ряд ограничений:

  • не предназначен для повторяющихся операций
  • не должен использоваться для логики, зависящей от каждого изменения даты
  • DOM может быть переинициализирован при destroy/re-init
  • не гарантирует окончательное состояние при внешних асинхронных модификациях

Типичные ошибки

Часто встречающиеся проблемы:

1. Попытка доступа к DOM до готовности

const calendar = document.querySelector(".flatpickr-calendar");
// может быть null

Решение — использовать onReady.

2. Дублирование логики с onOpen

Перенос тяжёлых операций в onOpen вместо onReady приводит к лишним вычислениям при каждом открытии.

3. Изменение конфигурации до инициализации

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

Итоговое поведение в реальных сценариях

В производственных интерфейсах onReady часто выступает как точка синхронизации:

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

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

Оглавление