onKeyUp

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

В отличие от низкоуровневых DOM-событий keyup, обработчик onKeyUp в контексте Inputmask работает поверх механизма синхронизации маски, учитывая текущее состояние буфера ввода, правила маскирования и позицию каретки.

Место onKeyUp в цепочке обработки ввода

При работе маски ввод проходит через несколько последовательных стадий:

  1. Перехват события клавиатуры (keydown)
  2. Модификация состояния маски (предварительное)
  3. Обновление буфера ввода
  4. Применение правил маскирования
  5. Обновление DOM-значения
  6. Событие keypress (в старых реализациях браузеров)
  7. Завершающая стадия keyup
  8. Вызов onKeyUp (Inputmask-level callback)

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

Сигнатура и контекст выполнения

Обработчик onKeyUp в Inputmask задаётся через конфигурацию:

Inputmask({
  mask: "(999) 999-9999",
  onKeyUp: function (event, buffer, caretPos, opts) {
    // логика обработки
  }
}).mask(input);

Параметры:

  • event — оригинальное DOM-событие keyup
  • buffer — массив текущих символов маски (внутреннее представление значения)
  • caretPos — текущая позиция каретки после обработки ввода
  • opts — объект конфигурации маски, содержащий активные правила и состояния

Особенности буфера ввода

Буфер (buffer) представляет собой не строку, а структурированную последовательность символов, где учитываются:

  • литералы маски (например, скобки, дефисы)
  • пользовательский ввод
  • placeholder-символы
  • пропуски и optional-элементы

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

Взаимодействие с кареткой

Параметр caretPos отражает положение курсора после завершения обработки нажатой клавиши. Важной особенностью является то, что Inputmask может изменять позицию каретки автоматически в зависимости от:

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

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

Поведение при различных типах клавиш

onKeyUp вызывается для всех клавиш, которые генерируют keyup, однако поведение внутри Inputmask различается:

Символьный ввод

При вводе символов происходит:

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

Backspace и Delete

Удаление символов приводит к:

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

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

Навигационные клавиши

Стрелки, Home, End:

  • не изменяют буфер
  • изменяют только caretPos
  • вызывают onKeyUp без модификации значения

Связь с другими callback Inputmask

onKeyUp является частью цепочки событий, в которую также входят:

  • onKeyDown — предварительная обработка ввода
  • onBeforeInput — фильтрация символов до вставки
  • onInput — реакция на изменение значения
  • onUnMask — извлечение “чистого” значения

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

Пример анализа состояния формы

Inputmask({
  mask: "9999-9999-9999-9999",
  onKeyUp: function (event, buffer, caretPos, opts) {
    const value = buffer.join("");

    const filled = value.replace(/[^0-9]/g, "").length;

    if (filled === 16) {
      opts.isComplete = true;
    }
  }
}).mask(document.querySelector("input"));

В данном сценарии onKeyUp используется для определения степени заполнения поля и установки пользовательского флага состояния.

Работа с динамическими масками

При использовании динамических масок (dynamic, regex, conditional masks) onKeyUp приобретает дополнительную значимость, поскольку:

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

В таких условиях onKeyUp отражает уже финальную версию состояния после всех внутренних перерасчётов.

Асинхронные эффекты и ограничения

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

  • программное обновление значения через API
  • внешние изменения DOM-значения
  • реактивные фреймворки, перезаписывающие input

По этой причине использование onKeyUp для критически важной логики валидации требует учёта возможных последующих изменений состояния.

Поведение на мобильных устройствах

На мобильных клавиатурах поведение keyup может отличаться:

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

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

Взаимодействие с кастомной логикой каретки

При ручном управлении кареткой через API Inputmask (setCaretPosition, caret) значение caretPos в onKeyUp может использоваться как контрольная точка:

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

Частые сценарии применения

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

Взаимодействие с производительностью

onKeyUp вызывается часто, особенно при быстром наборе текста. В масках с высокой сложностью регулярных выражений или большим количеством условных правил возможны:

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

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

Оглавление