Метод setRawValue

Метод setRawValue в Cleave.js используется для программного задания «сырого» значения поля ввода без применения форматирования на уровне отображения. В отличие от стандартного обновления значения через DOM или метода setValue, данный метод работает с внутренним представлением данных, которое библиотека использует до применения масок, разделителей и локализованных правил отображения.

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

Разделение raw и formatted значения

Внутренняя модель Cleave.js строится вокруг двух состояний:

  • raw value — «чистое» значение, которое не содержит разделителей, масок и локализационных символов;
  • formatted value — отображаемое значение, модифицированное согласно конфигурации (делимитеры, блоки, префиксы, дата/число/телефонные форматы).

Метод setRawValue напрямую воздействует на raw-слой, после чего Cleave.js самостоятельно пересчитывает отображаемое значение.

Пример концептуального различия:

  • raw: 79991234567
  • formatted: +7 999 123 45 67

Если установить значение через setRawValue, библиотека автоматически выполнит преобразование raw → formatted согласно текущим настройкам инстанса.

Сигнатура метода

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

cleave.setRawValue(value);

Параметр:

  • value — строка или число, представляющее неформатированное значение.

Метод не возвращает значение. Его задача — изменить состояние текущего экземпляра Cleave и обновить DOM-элемент.

Поведение при вызове setRawValue

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

  1. Переданное значение преобразуется в строку (если это число).

  2. Значение сохраняется во внутреннем raw state.

  3. Применяются правила текущей конфигурации Cleave.js:

    • разделение на блоки (blocks);
    • добавление разделителей (delimiter);
    • применение префиксов (prefix);
    • форматирование даты/времени (если активировано);
    • числовая нормализация (если включён numeric режим).

  4. Обновляется значение DOM-элемента.

  5. Генерируются соответствующие события изменения (если они активны).

Отличие от setValue

Метод setValue и setRawValue часто используются взаимозаменяемо, однако их поведение принципиально различается:

setValue

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

setRawValue

  • работает строго с исходным значением;
  • исключает повторное парсинг-форматирование входной строки;
  • предпочтителен при работе с API-данными.

Поведение в различных режимах Cleave.js

1. Numeric режим

При numeral: true значение интерпретируется как число:

cleave.setRawValue("1000000");

Результат отображения зависит от настроек:

  • разделители тысяч;
  • десятичный разделитель;
  • префиксы валют.

Пример результата:

1,000,000

2. Phone формат

При использовании телефонной маски raw-значение обычно содержит только цифры:

cleave.setRawValue("79991234567");

Cleave преобразует его в формат:

+7 999 123 45 67

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

3. Date формат

При конфигурации типа date: true:

cleave.setRawValue("20260125");

При заданном формате YYYY-MM-DD отображение станет:

2026-01-25

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

4. Blocks и delimiter формат

При кастомных масках:

{
  blocks: [4, 4, 4],
  delimiter: "-"
}

Вызов:

cleave.setRawValue("123456789012");

Результат:

1234-5678-9012

Влияние prefix и noImmediatePrefix

При использовании префикса:

{
  prefix: "+7 ",
  noImmediatePrefix: false
}

Вызов:

cleave.setRawValue("9991234567");

Отображение:

+7 999 123 45 67

Если включён noImmediatePrefix: true, поведение меняется: префикс может не отображаться до ввода значимых символов, однако при setRawValue он всё равно добавляется, так как значение уже считается установленным.

Работа с очисткой и нормализацией

Перед применением raw-значения Cleave.js выполняет нормализацию:

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

Пример:

cleave.setRawValue("  +7 (999) 123-45-67 ");

Внутренне значение преобразуется к:

79991234567

После чего применяется форматирование.

Взаимодействие с событиями input

В большинстве конфигураций вызов setRawValue приводит к триггеру событий:

  • input
  • change

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

Особенность:

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

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

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

  • текущий raw value;
  • formatted value;
  • позиция курсора (в зависимости от конфигурации);
  • кешированные блоки и сегменты;
  • состояние числового или масочного парсера.

При этом экземпляр Cleave остаётся полностью работоспособным без необходимости повторной инициализации.

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

1. Передача уже форматированного значения

cleave.setRawValue("+7 999 123 45 67");

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

Корректнее:

cleave.setRawValue("79991234567");

2. Несоответствие формату даты

Если формат ожидает YYYYMMDD, передача:

cleave.setRawValue("25-01-2026");

может привести к некорректному отображению или частичной интерпретации.

3. Использование с динамическими масками

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

cleave.setRawValue("1234");
cleave.setProperties({ blocks: [2, 2] });

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

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

Обновление значения из API

При получении данных с сервера обычно приходят «чистые» значения:

fetch("/api/user")
  .then(res => res.json())
  .then(data => {
    cleave.setRawValue(data.phone);
  });

Синхронизация состояния формы

При восстановлении состояния формы:

formState.forEach(field => {
  cleaveInstances[field.name].setRawValue(field.value);
});

Программная инициализация без пользовательского ввода

const cleave = new Cleave(input, {
  phone: true,
  phoneRegionCode: "KZ"
});

cleave.setRawValue("7012345678");

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

Метод setRawValue является лёгкой операцией, однако при частых вызовах в циклах (например, при анимации или потоковой обработке данных) может приводить к:

  • множественным перерисовкам DOM;
  • повторным вычислениям масок;
  • перерасчёту курсора.

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

Оглавление