Настройка разделителей групп цифр

В Cleave.js обработка чисел строится вокруг преобразования «сырого» ввода пользователя в визуально структурированное представление. Основная задача — разделить длинные последовательности цифр на читаемые группы без изменения фактического значения. Это особенно важно для финансовых полей, статистических данных и любых интерфейсов, где требуется быстрый визуальный разбор числа.

Ключевая особенность библиотеки заключается в том, что форматирование происходит по мере ввода, а не постфактум. Это исключает необходимость ручной обработки строк и снижает вероятность ошибок при отображении.

Включение числового режима

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

  • numeral: true

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

const cleave = new Cleave(input, {
    numeral: true
});

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

Группировка тысяч и настройка разделителей

Основной механизм настройки разделителей реализуется через параметр:

  • numeralThousandsGroupStyle

Он определяет стратегию разбиения числа на группы разрядов.

Доступные режимы группировки:

1. thousand Классическая западная система группировки по три цифры справа налево.

Пример:

1234567 → 1,234,567
new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

2. lakh Индийская система группировки, где первая группа состоит из трёх цифр, а последующие — по две.

Пример:

12345678 → 1,23,45,678
new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'lakh'
});

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

3. wan Китайская система группировки, ориентированная на разбиение по 4 цифры.

Пример:

12345678 → 1,2345,678
new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'wan'
});

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

4. none Полное отключение группировки.

Пример:

1234567 → 1234567
new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'none'
});

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

Управление символом разделителя

Помимо стратегии группировки, важную роль играет символ, используемый между группами. Он задаётся параметром:

  • delimiter

По умолчанию используется запятая, но его можно заменить на любой символ.

new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand',
    delimiter: ' '
});

В результате число будет отображаться так:

1234567 → 1 234 567

Часто применяются следующие варианты:

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

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

Десятичная часть и её взаимодействие с группировкой

Для чисел с плавающей точкой используется параметр:

  • numeralDecimalMark

Он определяет символ, отделяющий целую часть от дробной.

new Cleave(input, {
    numeral: true,
    numeralDecimalMark: '.',
    delimiter: ','
});

Пример поведения:

12345.67 → 12,345.67

При изменении локали часто требуется синхронная настройка:

  • разделителя групп
  • десятичного символа

Чтобы избежать конфликтов между ними.

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

Хотя Cleave.js не предназначен для математической обработки чисел, он позволяет косвенно контролировать формат вводимого значения через комбинацию настроек и внешней логики.

Типичный подход — ограничение длины дробной части через обработку события ввода и переустановку значения через API экземпляра.

cleave.setRawValue('12345.6789');

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

Работа с «сырым» значением

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

Для получения необработанного числа используется метод:

  • getRawValue()

Он возвращает строку без разделителей.

const raw = cleave.getRawValue();
// "1234567"

Это значение используется для:

  • отправки на сервер
  • вычислений
  • валидации бизнес-логики

Отображаемая версия при этом может содержать любые символы форматирования.

Динамическое изменение правил группировки

Cleave.js позволяет изменять настройки после инициализации. Это важно для интерфейсов, где формат зависит от выбора пользователя или локали.

cleave.properties.numeralThousandsGroupStyle = 'lakh';
cleave.init();

При этом происходит повторная инициализация внутреннего парсера, и новое правило применяется ко всему текущему значению.

Сочетание группировки с валютными префиксами

Часто числовое поле используется совместно с валютными символами. В Cleave.js это реализуется через параметры:

  • prefix
  • numeral
new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand',
    prefix: '$'
});

Результат:

$1234567 → $1,234,567

При этом префикс не участвует в расчёте значения и рассматривается как декоративный элемент.

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

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

  • автоматическому перемещению курсора
  • изменению позиции вставки
  • пересчёту групп при удалении символов

Эти эффекты являются следствием синхронного форматирования и не требуют дополнительной обработки в большинстве случаев.

Поведение при вставке больших чисел

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

Пример:

ввод: 1000000000
вывод: 1,000,000,000

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

Комбинации настроек для локализации

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

Типичный набор:

  • numeral: true
  • numeralThousandsGroupStyle
  • delimiter
  • numeralDecimalMark

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

new Cleave(input, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand',
    delimiter: ' ',
    numeralDecimalMark: ','
});

Результат:

1234567.89 → 1 234 567,89

Поведение при некорректном вводе

При вводе символов, не относящихся к числовому формату, Cleave.js выполняет фильтрацию. Однако поведение зависит от режима:

  • в numeral: true всё, кроме цифр и десятичного маркера, игнорируется
  • в строковом режиме (без numeral) фильтрация не применяется

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

Внутренний принцип пересчёта групп

Каждое изменение значения проходит через три этапа:

  1. Очистка входной строки от недопустимых символов
  2. Разделение на целую и дробную часть
  3. Применение выбранной стратегии группировки

После этого формируется итоговая строка отображения, которая синхронизируется с DOM-элементом.

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

Оглавление