Событие autoNumeric:formatted

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

Событие фиксирует момент, когда значение элемента ввода уже прошло полный цикл обработки внутри AutoNumeric и стало отображаемым форматом. Это означает, что:

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

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

Момент генерации события

autoNumeric:formatted срабатывает после завершения любого процесса, приводящего к изменению отображаемого значения:

  • ввод пользователем символов в поле ввода;
  • программное изменение значения через методы API (set, setNumericString, setNumber);
  • очистка значения (clear);
  • потеря фокуса при включённой опции автоформатирования;
  • применение настроек локали или обновление конфигурации.

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

  1. получение нового значения;
  2. преобразование во внутренний числовой формат;
  3. применение правил округления;
  4. генерация строкового представления;
  5. обновление DOM;
  6. эмит события autoNumeric:formatted.

Структура и содержимое события

Событие передаётся как DOM Event с расширенными свойствами, специфичными для AutoNumeric. В зависимости от версии библиотеки и режима работы, доступна следующая информация:

  • текущее отформатированное значение (строка);
  • предыдущее значение до форматирования;
  • числовое представление (если доступно);
  • ссылка на экземпляр AutoNumeric;
  • исходный input-элемент;
  • тип триггера изменения.

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

element.addEventListener("autoNumeric:formatted", (event) => {
    const formattedValue = event.detail.formatted;
    const previousValue = event.detail.previous;
    const numericValue = event.detail.number;
    const instance = event.detail.instance;
});

Роль event.detail

Ключевая информация передаётся через event.detail. Этот объект содержит состояние после завершения форматирования.

formatted

Строковое представление значения, уже пригодное для отображения в UI. Содержит:

  • разделители тысяч;
  • десятичные символы;
  • валютные символы;
  • форматирование отрицательных чисел.

number

Числовое значение после парсинга. Используется для вычислений и бизнес-логики.

previous

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

instance

Ссылка на экземпляр AutoNumeric, позволяющая получить доступ к методам API.

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

Ввод пользователем

При каждом изменении поля ввода событие может вызываться многократно, особенно при включённой опции live formatting. Каждая корректировка символа приводит к:

  • пересчёту значения;
  • повторному форматированию;
  • генерации события autoNumeric:formatted.

Это делает событие чувствительным к частым обновлениям DOM.

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

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

  • set()
  • setNumericString()
  • setNumber()

форматирование происходит синхронно, после чего генерируется autoNumeric:formatted. В этом случае событие отражает итоговое состояние после выполнения API-вызова.

Очистка значения

При вызове очистки значение становится пустым или нулевым (в зависимости от конфигурации). Событие фиксирует:

  • пустую строку в formatted;
  • null или 0 в numeric representation;
  • обновлённый state экземпляра.

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

Форматирование зависит от параметров экземпляра AutoNumeric:

  • digitGroupSeparator — разделитель тысяч;
  • decimalCharacter — десятичный символ;
  • currencySymbol — символ валюты;
  • suffixText / prefixText;
  • decimalPlaces;
  • roundingMethod.

Любое изменение этих параметров приводит к пересчёту текущего значения и последующему autoNumeric:formatted.

Использование в цепочках событий

autoNumeric:formatted часто используется как финальная точка в цепочке:

  • autoNumeric:rawValueModified → изменение внутреннего значения;
  • autoNumeric:formatted → обновление отображения.

Такая последовательность позволяет разделять:

  • бизнес-логику (работа с числом);
  • UI-логику (отображение строки).

Примеры обработки события

Логирование форматированных значений

const input = document.querySelector("#price");

input.addEventListener("autoNumeric:formatted", (event) => {
    console.log("Formatted:", event.detail.formatted);
    console.log("Numeric:", event.detail.number);
});

В этом случае фиксируется итоговое состояние после каждого форматирования.

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

input.addEventListener("autoNumeric:formatted", (event) => {
    externalState.amount = event.detail.number;
});

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

Валидация после форматирования

input.addEventListener("autoNumeric:formatted", (event) => {
    const value = event.detail.number;

    if (value < 0) {
        event.detail.instance.set(0);
    }
});

Форматированное значение используется как точка контроля корректности данных.

Особенности повторного форматирования

AutoNumeric может вызывать повторное событие autoNumeric:formatted при:

  • программной коррекции значения внутри обработчика;
  • изменении конфигурации экземпляра;
  • переключении локали;
  • пересчёте округления при потере фокуса.

Это создаёт потенциальный цикл обновлений, который требует контроля:

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

Отличие от других событий библиотеки

autoNumeric:rawValueModified

Работает с числовым представлением до форматирования. Используется для логики данных.

autoNumeric:formatted

Фокусируется исключительно на отображаемом результате. Используется для UI и финального состояния.

input event

Стандартное DOM-событие, которое не содержит информации о числовом преобразовании и форматировании AutoNumeric.

Влияние округления

При применении методов округления:

  • банковское округление;
  • округление вверх/вниз;
  • фиксированное количество знаков;

событие отражает уже итоговое значение после всех вычислений. Это важно для финансовых сценариев, где промежуточные значения недоступны на уровне formatted-события.

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

Финансовые формы

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

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

Динамические калькуляторы

При каждом изменении значения:

  • пересчитываются зависимости;
  • результат синхронизируется с formatted-событием;
  • UI обновляется без дополнительного парсинга.

Интеграция с реактивными фреймворками

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

Обработка частых обновлений

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

  • debounce логики обработки;
  • фильтрация одинаковых значений;
  • сравнение previous и formatted.

Пример защиты от лишней обработки:

let lastValue = null;

input.addEventListener("autoNumeric:formatted", (event) => {
    if (event.detail.formatted === lastValue) return;

    lastValue = event.detail.formatted;
});

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

AutoNumeric фактически реализует динамическую маску числового ввода. autoNumeric:formatted является сигналом завершения применения маски к текущему состоянию. Это позволяет интегрировать библиотеку в системы:

  • форм платежей;
  • бухгалтерских интерфейсов;
  • CRM-форм;
  • аналитических панелей.

Поведение при потерянном фокусе

При blur-событиях input может происходить финальная нормализация значения. В этот момент autoNumeric:formatted отражает:

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

Ограничения события

Несмотря на широкую применимость, событие имеет ряд особенностей:

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

Синхронизация с серверными данными

В сценариях отправки формы autoNumeric:formatted часто используется для подготовки финального отображаемого значения, однако для передачи на сервер предпочтительно использовать числовое значение из event.detail.number, поскольку formatted-строка может содержать локализационные символы, непригодные для парсинга на стороне backend.

Оглавление