Настройка rawValueTrimPrefix

Опция rawValueTrimPrefix управляет тем, как библиотека обрабатывает значение поля ввода при извлечении «сырых» данных (rawValue) в сценариях, где используется префикс (prefix). Основная задача этой настройки — контроль сохранения или удаления префикса в чистом значении, которое возвращается приложению.

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

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

В Cleave.js существует разделение между:

  • formatted value — значение, отображаемое в input
  • raw value — «чистое» значение без форматирования

При использовании prefix библиотека добавляет фиксированную строку в начало отображаемого значения. Например:

const cleave = new Cleave('#input', {
  prefix: '+7',
  numericOnly: true
});

В поле пользователь видит:

+7 999 123 45 67

Но при извлечении rawValue возникает вопрос: должен ли результат содержать +7 или нет?

Именно здесь вступает в работу rawValueTrimPrefix.

Логика работы rawValueTrimPrefix

Опция определяет, будет ли префикс удаляться из rawValue.

Возможные значения

  • true — префикс удаляется из rawValue
  • false — префикс сохраняется в rawValue

По умолчанию поведение зависит от версии и конфигурации, но чаще всего используется значение true, чтобы бизнес-логика получала «чистые» данные.

Поведение при rawValueTrimPrefix: true

При включенной опции:

const cleave = new Cleave('#input', {
  prefix: '+7',
  rawValueTrimPrefix: true,
  numericOnly: true
});

Результат работы:

  • В поле ввода:

    +7 777 123 45 67

  • rawValue:

    7771234567

Смысл поведения

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

  • телефонных номеров
  • валютных полей
  • идентификаторов с фиксированным отображаемым кодом

Поведение при rawValueTrimPrefix: false

При отключенной обрезке:

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

Результат:

  • В поле ввода:

    USD 1200

  • rawValue:

    USD 1200

Смысл поведения

Префикс становится частью данных, а не только отображения. Это важно, когда:

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

Связь с rawValue

rawValueTrimPrefix напрямую влияет только на rawValue, не затрагивая отображаемое значение.

В Cleave.js это принципиальный момент: библиотека всегда отделяет:

  • UI-слой (форматирование)
  • data-слой (raw value)

Это позволяет использовать один и тот же input в разных сценариях без изменения DOM-структуры.

Типичные сценарии использования

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

const cleave = new Cleave('#phone', {
  prefix: '+7',
  numericOnly: true,
  rawValueTrimPrefix: true
});

Здесь логично исключить +7 из rawValue, поскольку:

  • backend хранит номер отдельно от кода страны
  • код страны может обрабатываться отдельно

2. Финансовые значения

const cleave = new Cleave('#price', {
  prefix: '$',
  numeral: true,
  rawValueTrimPrefix: true
});

Использование:

  • UI: $ 1,200
  • raw: 1200

Это стандартная модель для расчётов, где символ валюты не участвует в вычислениях.

3. Семантически значимый префикс

const cleave = new Cleave('#invoice', {
  prefix: 'INV-',
  rawValueTrimPrefix: false
});

Здесь важно сохранить полный идентификатор:

  • UI: INV-000123
  • raw: INV-000123

Удаление префикса привело бы к потере смысла идентификатора.

Влияние на обработку событий

При использовании Cleave.js события onChange и onInit могут возвращать разные представления значения.

Типичная структура:

onChange: function (event) {
  console.log(event.target.value);     // formatted
  console.log(this.getRawValue());     // rawValue
}

При rawValueTrimPrefix: true getRawValue() всегда возвращает значение без префикса, независимо от того, как оно отображается.

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

Опция часто используется совместно с:

  • prefix
  • noImmediatePrefix
  • rawValueTrimPrefix

Комбинации влияют на поведение ввода:

Сценарий

const cleave = new Cleave('#input', {
  prefix: '+',
  noImmediatePrefix: true,
  rawValueTrimPrefix: true
});

Поведение:

  • пользователь может вводить значение без автоматического добавления +
  • префикс появляется только при наличии данных
  • rawValue остаётся «чистым»

Особенности обработки пустого значения

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

rawValueTrimPrefix: true

  • rawValue = ""
  • префикс не возвращается даже частично

rawValueTrimPrefix: false

  • rawValue может содержать только префикс:

    "+"

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

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

Ошибка 1: ожидание, что formatted value = raw value

В Cleave.js это разные сущности. Игнорирование различий приводит к некорректной обработке данных.

Ошибка 2: хранение formatted value в базе

Если rawValueTrimPrefix: false, легко случайно сохранить:

USD 1000

вместо:

1000

или наоборот — сохранить число без валютного контекста.

Ошибка 3: смешивание префиксов и масок

При использовании сложных масок:

prefix: '+7',
blocks: [1, 3, 3, 2, 2]

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

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

Логика выбора значения опции обычно строится так:

  • если префикс служебный → true
  • если префикс часть идентификатора → false

Поведение в сложных масках

В комбинированных форматах (например, телефон + расширение) Cleave.js обрабатывает префикс отдельно от блоков маски.

Пример:

const cleave = new Cleave('#phone', {
  prefix: '+7',
  delimiters: [' ', '-', '-'],
  blocks: [1, 3, 3, 2, 2],
  rawValueTrimPrefix: true
});

В этом случае:

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

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

Если параметры изменяются на лету:

cleave.properties.rawValueTrimPrefix = false;

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

Влияние на интеграцию с backend

При проектировании API важно учитывать:

  • rawValueTrimPrefix: true → backend получает «чистые» данные
  • rawValueTrimPrefix: false → backend получает уже форматированную строку

В микросервисных архитектурах чаще используется первый вариант, чтобы:

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

Поведение при числовом режиме (numeral)

В сочетании с:

numeral: true

префикс обычно воспринимается как декоративный элемент. При rawValueTrimPrefix: true:

  • символы валюты исключаются
  • остаётся только число
  • форматирование разделителей тысяч не влияет на raw

Итоговая модель поведения

Опция rawValueTrimPrefix в Cleave.js задаёт границу между визуальной и смысловой частью данных:

  • true — строгая сегрегация UI и data слоя
  • false — префикс становится частью данных

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

Оглавление