Обработчик onValueChanged

В Cleave.js обработчик onValueChanged представляет собой один из ключевых механизмов реакции на изменение значения поля ввода, позволяющий синхронизировать форматированное отображение с внутренним состоянием данных и внешними системами управления формой.

Функционально этот обработчик вызывается каждый раз, когда библиотека выполняет преобразование значения input-элемента. Это включает ввод символов пользователем, программное изменение значения через API Cleave.js, а также любые операции автоформатирования, такие как вставка разделителей, преобразование даты, группировка чисел или маскирование.

Внутри жизненного цикла Cleave.js изменение значения проходит несколько этапов:

  • получение «сырого» значения из input
  • нормализация входного потока (удаление неподходящих символов)
  • применение правил форматирования
  • обновление DOM-значения
  • вызов onValueChanged

Таким образом, onValueChanged всегда срабатывает уже после того, как библиотека сформировала итоговое отображаемое значение и обновила поле ввода.

Ключевая особенность заключается в том, что обработчик фиксирует не сам факт ввода, а именно результат работы форматтера.

Сигнатура обработчика

Типичная форма объявления:

new Cleave(inputElement, {
    onValueChanged: function (event) {
        // обработка изменений
    }
});

В большинстве реализаций Cleave.js в объект event передаётся структурированная информация о состоянии поля.

Структура объекта события

Объект, поступающий в onValueChanged, содержит данные, отражающие одновременно три слоя представления значения:

  • value — текущее отображаемое значение в input после форматирования
  • rawValue — «чистое» значение без маски и разделителей
  • target — ссылка на DOM-элемент input
  • дополнительные служебные поля (в зависимости от конфигурации типа форматирования)

Особое значение имеет различие между value и rawValue. Это различие лежит в основе архитектуры Cleave.js.

Форматированное значение (value)

value всегда соответствует тому, что пользователь видит в поле. Например:

1234567890 → 1 234 567 890

или

20260101 → 2026-01-01

Это значение используется для отображения и взаимодействия с UI.

Сырое значение (rawValue)

rawValue представляет собой данные без форматирования:

1 234 567 890 → 1234567890

Именно это значение обычно применяется для:

  • отправки на сервер
  • валидации
  • бизнес-логики
  • хранения в состоянии приложения

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

onValueChanged выступает связующим звеном между внутренней логикой Cleave.js и внешними системами управления состоянием.

Наиболее типичные сценарии использования:

Синхронизация с состоянием приложения

В архитектуре, где input является частью управляемого состояния, обработчик используется для обновления store:

onValueChanged: function (event) {
    state.value = event.target.value;
    state.raw = event.rawValue;
}

При этом важно учитывать, что event.target.value уже содержит форматированное значение, тогда как rawValue — пригоден для вычислений.

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

При работе с формами обработчик часто используется для разделения отображаемого и отправляемого значений:

  • отображение: value
  • отправка: rawValue

Это позволяет избегать дополнительных преобразований перед submit-операцией.

Реакция на изменение данных в реальном времени

Обработчик позволяет реализовать мгновенную реакцию интерфейса:

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

Особенности вызова

Частота срабатывания

onValueChanged может вызываться:

  • при каждом символе ввода
  • при удалении символов
  • при вставке текста
  • при программном вызове setRawValue или аналогичных методов

Это делает обработчик высокочастотным и потенциально чувствительным к производительности.

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

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

  • задержки при вводе
  • «дёргание» интерфейса
  • блокировка основного потока

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

Взаимодействие с программными методами Cleave.js

Обработчик срабатывает не только на пользовательский ввод, но и при вызове API:

  • setRawValue
  • программное обновление input
  • пересоздание экземпляра Cleave.js

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

Особенности работы с React и Vue

При интеграции с реактивными фреймворками возникает риск двойного обновления состояния:

  1. Cleave.js изменяет DOM
  2. фреймворк синхронизирует состояние
  3. снова инициируется обновление Cleave.js

Чтобы избежать конфликтов, onValueChanged обычно используется как единственная точка синхронизации:

onValueChanged: (event) => {
    setState({
        formatted: event.target.value,
        raw: event.rawValue
    });
}

При этом важно избегать обратного перезаписывания значения input без необходимости.

Отличие от стандартных DOM-событий

В отличие от input или change, onValueChanged:

  • срабатывает после форматирования
  • предоставляет доступ к raw-данным
  • учитывает внутренние правила Cleave.js
  • не отражает «сырое» состояние ввода пользователя до обработки

Таким образом, стандартные DOM-события и onValueChanged решают разные задачи и не являются взаимозаменяемыми.

Типичные ошибки использования

Игнорирование rawValue

Использование только event.target.value приводит к ошибкам при работе с числами и датами, так как форматирование может искажать данные.

Перезапись значения внутри обработчика

Изменение input внутри onValueChanged может вызвать рекурсивные обновления:

  • Cleave.js обновляет значение
  • обработчик изменяет значение
  • Cleave.js снова форматирует

Это приводит к нестабильному поведению.

Тяжёлая логика внутри callback

Выполнение сетевых запросов или сложных вычислений внутри обработчика приводит к деградации UX.

Роль в архитектуре Cleave.js

onValueChanged фактически выполняет роль наблюдателя состояния (observer), предоставляя точку контроля над всеми изменениями значения input. Он связывает:

  • DOM-слой
  • слой форматирования
  • прикладную бизнес-логику

за счёт единого события, содержащего уже нормализованные данные.

Оглавление