Метод getFormattedValue

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

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

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

Метод вызывается на экземпляре Cleave:

const formatted = cleave.getFormattedValue();

Возвращаемое значение всегда имеет тип string.

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

getFormattedValue возвращает значение, которое уже прошло через все активные преобразования:

  • добавление разделителей (delimiter)
  • применение блоков (blocks)
  • форматирование чисел (numeral)
  • маскирование даты и времени (date / time)
  • применение префиксов и суффиксов
  • кастомные обработчики форматирования

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

Отличие от rawValue

Cleave.js хранит два ключевых представления данных:

  • rawValue — исходное значение без форматирования
  • getFormattedValue() — значение с применённым форматированием

Пример различия:

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

Пользователь вводит:

1000000

Результаты:

  • cleave.getFormattedValue() → "1,000,000"
  • cleave.getRawValue() → "1000000"

Когда используется getFormattedValue

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

Синхронизация UI

При работе с React, Vue или чистым DOM часто нужно обновлять состояние на основе визуального значения:

input.addEventListener('input', () => {
    state.value = cleave.getFormattedValue();
});

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

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

console.log('User input:', cleave.getFormattedValue());

Передача данных в UI-компоненты

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

sidebarValue.textContent = cleave.getFormattedValue();

Особенности работы при динамическом вводе

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

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

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

Числовой формат (numeral)

const cleave = new Cleave(input, {
    numeral: true,
    numeralDecimalMark: '.'
});
  • Ввод: 12345.6
  • getFormattedValue() → 12,345.6

Форматирование зависит от настроек разделителей и локали.

Дата

const cleave = new Cleave(input, {
    date: true,
    datePattern: ['Y', 'm', 'd']
});
  • Ввод: 20260521
  • getFormattedValue() → 2026-05-21

Значение всегда возвращается в виде строки, соответствующей заданному шаблону.

Кастомные блоки

const cleave = new Cleave(input, {
    blocks: [4, 4, 4],
    delimiter: '-'
});
  • Ввод: 123456789012
  • getFormattedValue() → 1234-5678-9012

Влияние programmatic updates

Если значение изменяется программно:

cleave.setRawValue('999999');

после этого:

cleave.getFormattedValue();

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

Ограничения метода

Метод не выполняет:

  • валидацию ввода
  • преобразование типов (число/строка)
  • доступ к DOM напрямую
  • сохранение состояния

Он исключительно читает текущее отформатированное значение внутри экземпляра Cleave.js.

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

Попытка использовать как источник «чистых данных»

const value = cleave.getFormattedValue(); // может содержать разделители

Для вычислений или отправки на сервер это значение часто непригодно без предварительной очистки.

Ожидание пересчёта при вызове

cleave.getFormattedValue();

не инициирует обновление. Если состояние не изменилось, результат останется тем же.

Сравнение с альтернативными подходами

Вместо getFormattedValue иногда используют:

  • input.value — может быть синхронизирован, но зависит от реализации Cleave
  • getRawValue() — для бизнес-логики и вычислений
  • кастомные форматтеры — если требуется контроль над выводом

getFormattedValue занимает промежуточную позицию между UI и данными: это именно то, что видит пользователь в поле ввода.

Поведение при отключённом форматировании

Если Cleave.js инициализирован без активных правил форматирования:

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

тогда:

  • getFormattedValue() возвращает фактически исходную строку ввода
  • форматирование не применяется, но метод остаётся валидным

Использование в сложных конфигурациях

При комбинировании нескольких правил:

const cleave = new Cleave(input, {
    prefix: '+7',
    blocks: [1, 3, 3, 2, 2],
    delimiter: ' '
});

результат getFormattedValue() будет включать:

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

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

+7 999 123 45 67

Стабильность значения

Метод возвращает детерминированный результат при одинаковом состоянии экземпляра. Это означает:

  • одинаковый ввод → одинаковый formatted output
  • отсутствие побочных эффектов при вызове
  • независимость от внешнего состояния DOM (после синхронизации)

Роль в архитектуре Cleave.js

getFormattedValue является частью слоя представления (presentation layer), обеспечивая доступ к данным именно в том виде, в котором они формируются для отображения. Он отделяет:

  • внутренние данные (raw)
  • отображение (formatted)
  • пользовательский ввод (DOM input state)

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

Оглавление