Событие onValueUpdate

Событие onValueUpdate относится к внутреннему циклу обновления значения календаря и вызывается в момент, когда строковое представление выбранной даты или дат пересчитывается и синхронизируется с состоянием экземпляра. В отличие от более очевидных событий выбора (onChange) или открытия календаря (onOpen), onValueUpdate ориентировано на уровень синхронизации данных, а не на пользовательское действие.

Место onValueUpdate в жизненном цикле Flatpickr

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

  1. Пользователь взаимодействует с календарём или значение меняется программно.
  2. Flatpickr обновляет внутренний массив выбранных дат.
  3. Пересчитывается строковое значение (altInput, input.value, форматы dateFormat).
  4. Срабатывает onValueUpdate.
  5. При необходимости вызываются более высокоуровневые события, такие как onChange.

Таким образом, onValueUpdate фиксирует момент, когда значение уже пересчитано, но ещё не обязательно интерпретируется как «изменение выбора пользователем».

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

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

flatpickr("#date", {
  onValueUpdate: function(selectedDates, dateStr, instance) {
    // логика обработки
  }
});

Параметры:

  • selectedDates — массив объектов Date, отражающий текущее состояние выбора.
  • dateStr — строка, сформированная согласно dateFormat или altFormat.
  • instance — ссылка на текущий экземпляр Flatpickr.

Отличие от onChange

Ключевая разница между onValueUpdate и onChange заключается в уровне семантики:

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

Это различие особенно заметно в сценариях:

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

Поведение при программном изменении значения

При вызове методов API, например:

instance.setDate("2026-05-01");

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

  • обновление внутреннего состояния;
  • пересчёт строки dateStr;
  • вызов onValueUpdate;
  • затем возможный вызов onChange (в зависимости от параметров setDate).

Это делает onValueUpdate полезным для отслеживания промежуточных состояний, когда onChange ещё не гарантирован.

Типичные сценарии использования

Событие применяется в задачах, где важно реагировать на любое изменение представления даты, а не только на финальный выбор:

  • синхронизация UI-компонентов, зависящих от строкового значения даты;
  • динамическое форматирование отображения вне самого input;
  • интеграция с кастомными валидаторами, работающими со строкой;
  • отслеживание промежуточных состояний при вводе вручную.

Особенности работы с вводом с клавиатуры

При ручном вводе даты в поле поведение становится более «потоковым»:

  • каждое изменение символов может инициировать перерасчёт;
  • строка dateStr обновляется чаще, чем фактический выбор даты;
  • onValueUpdate может срабатывать чаще, чем onChange.

Это важно учитывать при обработке событий, чтобы избежать избыточных вычислений.

Работа с диапазонами дат

В режиме mode: "range" событие приобретает дополнительную значимость:

flatpickr("#range", {
  mode: "range",
  onValueUpdate: function(selectedDates, dateStr, instance) {
    console.log(dateStr);
  }
});

В этом режиме:

  • каждый шаг выбора диапазона обновляет строку;
  • промежуточные состояния (только startDate или частично выбранный диапазон) также вызывают событие;
  • dateStr может содержать неполные данные.

Взаимодействие с форматами отображения

onValueUpdate тесно связан с форматированием:

  • dateFormat — основной формат строки значения;
  • altInput и altFormat — альтернативное отображение;
  • локализация (locale) влияет на итоговую строку.

Любое изменение этих параметров приводит к пересчёту dateStr, что может активировать событие даже без изменения выбранных дат.

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

На частоту срабатывания влияют параметры:

  • enableTime — добавляет пересчёт времени;
  • time_24hr — влияет на форматирование строки;
  • defaultDate — может инициировать первичный вызов;
  • allowInput — усиливает поток обновлений при ручном вводе;
  • mode — single, multiple, range изменяют структуру данных.

Потенциальные проблемы при использовании

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

  • избыточные вызовы тяжёлой логики;
  • дублирование вычислений между onValueUpdate и onChange;
  • рассинхронизация UI при асинхронной обработке;
  • трудности в дебаге из-за высокой частоты событий.

Для минимизации нагрузки обычно выделяют лёгкий слой обработки именно в onValueUpdate, оставляя тяжёлые операции для onChange.

Поведение при reset и очистке

При вызове:

instance.clear();

происходит:

  • очистка массива дат;
  • пересчёт строки в пустое значение;
  • вызов onValueUpdate с пустыми данными;
  • возможный вызов onChange, если состояние изменилось.

Это делает событие полезным для отслеживания момента «визуального обнуления» поля.

Роль в архитектуре Flatpickr

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

Оглавление