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

Библиотека Cleave.js предоставляет программный интерфейс для управления форматированием значения, привязанного к полю ввода. Основной объект, с которым происходит взаимодействие после инициализации, — это экземпляр Cleave. Именно через него осуществляется доступ к текущему значению, его программная установка, а также изменение состояния форматирования без прямого вмешательства в DOM.

После создания экземпляра:

const cleave = new Cleave(inputElement, {
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
});

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

Получение текущего значения

Свойство value

Основной способ получить текущее отформатированное значение — обращение к свойству value экземпляра.

const current = cleave.value;

Значение, возвращаемое через value, всегда соответствует отображаемому содержимому input-поля, включая все применённые правила форматирования: разделители тысяч, маски, префиксы и другие трансформации.

Ключевая особенность:

  • возвращается визуально отформатированное значение, а не «сырые» данные;
  • результат синхронизирован с DOM-элементом;
  • учитывает все активные настройки инстанса.

Пример при числовом формате:

// пользователь ввёл: 1000000
cleave.value; // "1,000,000"

Свойство rawValue

Для работы с «чистыми» данными используется rawValue.

const raw = cleave.getRawValue();

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

Особенности поведения:

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

Пример:

// отображается: "1,000,000"
cleave.getRawValue(); // "1000000"

Этот метод особенно важен при:

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

Установка значения программно

Метод setRawValue

Для установки «чистого» значения используется метод:

cleave.setRawValue(value);

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

Пример для числового режима:

cleave.setRawValue("2500000");

Результат в input:

2,500,000

Поведение метода:

  • входное значение интерпретируется как сырой формат;
  • автоматически запускается пересчёт форматирования;
  • обновляется DOM-значение input;
  • внутреннее состояние экземпляра синхронизируется.

Метод setValue

Метод setValue используется для установки уже отформатированного значения:

cleave.setValue(value);

Он полезен, когда значение уже содержит нужную структуру или поступает из внешнего источника в финальном виде.

Пример:

cleave.setValue("1,200,000");

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

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

Разница между setValue и setRawValue

Разграничение этих методов является критическим для корректного управления данными.

setRawValue

  • принимает «сырые» данные;
  • всегда считается источником истины;
  • гарантирует корректное применение маски;
  • предпочтителен при работе с backend-данными.

setValue

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

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

После любого изменения значения через API происходит обновление внутреннего состояния:

  • пересчитывается форматирование;
  • обновляется caret-позиция (если применимо);
  • синхронизируется DOM input;
  • обновляется кеш parsed value.

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

Поведение при изменении значений

Перезапуск форматирования

Каждый вызов setRawValue или setValue фактически инициирует полный цикл обработки:

  1. разбор входной строки;
  2. применение масок и правил;
  3. генерация нового отображаемого значения;
  4. запись в input.

Влияние настроек

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

Пример:

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

cleave.setRawValue("10000");

Результат:

$10,000

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

Получение ссылки на DOM-значение

Хотя Cleave предоставляет собственное состояние, значение input можно получить напрямую:

inputElement.value

Однако такое обращение не учитывает внутреннюю логику библиотеки и может не совпадать с cleave.value в процессе промежуточных обновлений.

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

После вызова:

cleave.destroy();

методы setValue, setRawValue и доступ к value теряют смысл, поскольку обработка событий и форматирование прекращаются. Input возвращается к стандартному поведению DOM-элемента.

Работа с асинхронными обновлениями

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

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

cleave.setRawValue("5000");
console.log(cleave.value);

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

Внутренняя модель хранения данных

Cleave.js поддерживает две формы представления данных:

  • formatted value — отображаемое значение;
  • raw value — логическое значение без форматирования.

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

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

Инициализация с предзаданным значением

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

cleave.setRawValue("75000");

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

fetch('/api/price')
    .then(res => res.json())
    .then(data => {
        cleave.setRawValue(data.price);
    });

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

formData.amount = cleave.getRawValue();

Особенности работы с числовыми форматами

При включённом numeral: true:

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

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

При использовании масок (например, телефон, дата):

  • setRawValue интерпретирует вход в контексте маски;
  • setValue может корректировать структуру;
  • value всегда соответствует маске;
  • rawValue может содержать только значимые символы.

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

Если передать в setRawValue значение, не соответствующее ожидаемому формату:

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

Пример:

cleave.setRawValue("12ab34cd");

Результат:

1234

Итеративное обновление значений

Методы могут вызываться многократно без пересоздания экземпляра:

cleave.setRawValue("1000");
cleave.setRawValue("2000");
cleave.setRawValue("3000");

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

Взаимодействие с пользовательским вводом

При одновременной работе пользователя и программного API:

  • Cleave приоритетно обрабатывает последнее изменение;
  • API-вызов перезаписывает текущее состояние input;
  • пользовательский ввод синхронизируется после перерасчёта форматирования.
Оглавление