Метод formatAndSet

Метод formatAndSet в AutoNumeric относится к числу ключевых инструментов, обеспечивающих одновременное форматирование входного значения и его немедленную установку в привязанный DOM-элемент. Его поведение объединяет две операции, которые обычно разделены: преобразование «сырых» числовых данных в форматированный вид и синхронизацию этого значения с внутренним состоянием экземпляра.

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

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

Сигнатура и общая форма вызова

В контексте экземпляра AutoNumeric метод вызывается следующим образом:

anElement.formatAndSet(value);

где:

  • anElement — экземпляр AutoNumeric, привязанный к DOM-элементу <input>
  • value — значение, подлежащее форматированию и установке

Тип value может варьироваться в зависимости от конфигурации и режима работы библиотеки.

Поддерживаемые типы входных данных

Метод допускает несколько типов входных значений:

Числовые значения

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

anElement.formatAndSet(1234.56);

Строковые представления чисел

Строки проходят этап парсинга с учётом локали и настроек:

anElement.formatAndSet("1,234.56");

Пустые или нулевые значения

Пустые строки и null интерпретируются в зависимости от конфигурации (emptyInputBehavior, zeroEmpty, и др.).

Внутренний процесс обработки

Метод formatAndSet можно рассматривать как последовательность нескольких этапов:

1. Нормализация входного значения

На этом этапе выполняется:

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

2. Парсинг в числовой формат

Значение преобразуется во внутреннее представление (обычно Number или специализированный тип внутри библиотеки).

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

3. Применение правил форматирования

Учитываются настройки экземпляра:

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

4. Синхронизация с DOM

После форматирования результат записывается в input-элемент, вызывая обновление отображения.

Отличие от похожих методов

Метод formatAndSet часто сравнивают с другими операциями библиотеки.

set

set(value) выполняет установку значения без обязательного повторного форматирования входных данных в том же объёме, как formatAndSet.

format

format() работает с уже установленным значением и лишь обновляет его визуальное представление.

parse

parse() возвращает числовое значение без изменения DOM.

Поведение при изменении конфигурации

При изменении настроек экземпляра поведение formatAndSet автоматически адаптируется:

  • изменение decimalCharacter влияет на парсинг строк
  • изменение digitGroupSeparator влияет на итоговый вывод
  • изменение currencySymbol добавляет или убирает префиксы/суффиксы
  • изменение decimalPlaces влияет на округление

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

Особенности обработки локалей

В сценариях, где используются разные форматы чисел (например, европейский и американский), метод корректно интерпретирует:

  • 1.234,56 как 1234.56 (при соответствующей настройке)
  • 1,234.56 как 1234.56 (стандартный формат US)

Критически важно, что formatAndSet не просто отображает строку, а именно приводит её к внутреннему числу, что исключает ошибки двойного форматирования.

Работа с отрицательными значениями

При передаче отрицательных чисел метод учитывает:

  • позицию знака минус (префикс/суффикс)
  • альтернативные форматы отображения отрицательных значений (скобки)
  • ограничения, если включён режим запрета отрицательных чисел

Пример:

anElement.formatAndSet(-9876.5);

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

Обработка ошибок и некорректных значений

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

  • возврат пустого значения
  • установка 0
  • сохранение предыдущего значения
  • генерация внутреннего предупреждения

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

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

При частом вызове formatAndSet, особенно в циклах или при обработке больших массивов данных, важно учитывать:

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

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

Примеры применения в прикладных сценариях

Загрузка данных из API

fetch("/api/price")
  .then(res => res.json())
  .then(data => {
    priceField.formatAndSet(data.price);
  });

Пересчёт значений в форме

const result = quantity * unitPrice;
priceField.formatAndSet(result);

Обработка пользовательского ввода из нестандартного источника

priceField.formatAndSet("2 345,78");

Поведение при повторной установке того же значения

Если значение, переданное в formatAndSet, эквивалентно текущему, библиотека может оптимизировать обновление:

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

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

Влияние на состояние экземпляра

После вызова formatAndSet внутреннее состояние экземпляра включает:

  • обновлённое числовое значение
  • синхронизированное строковое представление
  • актуальные данные для последующего get() и set()

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

Оглавление