Опции prefix и noImmediatePrefix

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

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

Базовое поведение

При указании prefix библиотека автоматически:

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

Пример использования

import Cleave from 'cleave.js';

const cleave = new Cleave('#input', {
    prefix: 'USD ',
    numeral: true
});

В этом случае поле всегда будет начинаться с USD, а пользователь вводит только числовую часть.

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

Поведение prefix тесно связано с внутренним механизмом нормализации значения:

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

Важно учитывать, что prefix влияет не только на отображение, но и на структуру данных, которую возвращает поле.

Использование с числовыми форматами

Наиболее частый сценарий — денежные значения:

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

Результат ввода:

$1,000,000

Здесь префикс становится частью UI-формата, но не частью числовой логики.

Параметр noImmediatePrefix

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

Поведение по умолчанию

Без noImmediatePrefix:

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

Поведение с noImmediatePrefix: true

При включении:

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

Пример конфигурации

new Cleave('#input', {
    prefix: '+7',
    noImmediatePrefix: true,
    phone: true
});

В этом случае поле выглядит пустым до ввода первой цифры. После ввода, например 9, значение становится:

+79

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

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

Сценарии взаимодействия

1. Обычный режим

prefix: 'EUR '
noImmediatePrefix: false

Поведение:

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

2. Отложенный префикс

prefix: 'EUR '
noImmediatePrefix: true

Поведение:

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

3. Динамическая инициализация

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

const cleave = new Cleave('#input', {
    prefix: 'ID-',
    noImmediatePrefix: true,
    blocks: [3, 3, 3]
});

cleave.setRawValue('123456');

Результат:

ID-123-456

Префикс добавляется только после того, как появляется фактическое содержимое.

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

Логика вставки prefix

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

  • существует ли префикс в начале строки;
  • нужно ли его восстановить;
  • не нарушена ли позиция курсора.

Если noImmediatePrefix = true, добавляется дополнительное условие:

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

Курсор и позиционирование

Одна из сложных частей реализации — управление кареткой:

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

Практические сценарии применения

Валютные поля

new Cleave('#salary', {
    prefix: '₸ ',
    numeral: true,
    noImmediatePrefix: false
});

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

Телефонные номера

new Cleave('#phone', {
    prefix: '+7',
    noImmediatePrefix: true,
    phone: true
});

Позволяет избежать визуального «засорения» поля до ввода данных.

Идентификаторы

new Cleave('#order', {
    prefix: 'ORD-',
    noImmediatePrefix: true,
    blocks: [4, 4, 4]
});

Формирует структурированный ID вида:

ORD-1234-5678-9012

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

Конфликт с пользовательским вводом

Если prefix содержит пробелы или спецсимволы, важно учитывать:

  • они становятся частью строки;
  • могут влиять на валидацию на стороне сервера;
  • могут неожиданно участвовать в копировании/вставке.

Неправильное ожидание поведения noImmediatePrefix

Распространённое заблуждение:

  • ожидание, что prefix вообще не будет существовать до submit.

Фактически:

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

Совместимость с numeral и blocks

При комбинировании:

  • numeral требует числовой обработки;
  • blocks создают сегментацию строки;
  • prefix всегда остаётся фиксированным сегментом слева.

Неправильная конфигурация может привести к конфликтам отображения, если формат не согласован.

Поведенческие особенности в edge-case сценариях

Пустое значение

При noImmediatePrefix: true:

  • значение '' остаётся пустым;
  • prefix не отображается.

При false:

  • поле уже содержит prefix даже при отсутствии данных.

Очистка поля

При полном удалении содержимого:

  • в режиме false prefix остаётся;
  • в режиме true поле возвращается к состоянию «без prefix».

Программное обновление value

cleave.setRawValue('');
  • с noImmediatePrefix: false prefix восстанавливается;
  • с true остаётся скрытым до нового ввода.

Итоговая логика взаимодействия

Поведение можно свести к следующей модели:

  • prefix задаёт фиксированную структуру начала строки;
  • noImmediatePrefix управляет моментом её визуального появления;
  • вместе они формируют гибкий механизм контроля UX ввода.

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

Оглавление