Метод setValue

Метод setValue в библиотеке Inputmask отвечает за корректную установку значения в элемент ввода с учётом активной маски. В отличие от прямого присваивания value, данный метод синхронизирует внутреннее состояние маски, пересчитывает позиции символов, применяет правила форматирования и поддерживает консистентность буфера ввода.

Поведение метода setValue в контексте маски

При использовании Inputmask значение поля ввода не является обычной строкой. Оно включает:

  • статические символы маски (например, скобки, дефисы);
  • позиции заполнителей;
  • внутренний буфер введённых данных;
  • служебные метки для управления кареткой.

Прямое присваивание через input.value = "..." приводит к несоответствию между отображаемым значением и внутренним состоянием маски. Метод setValue решает эту проблему, выполняя полный цикл обработки значения.

Ключевые операции внутри setValue:

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

Сигнатура и базовое использование

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

const im = new Inputmask("(999) 999-9999");
im.mask(document.querySelector("#phone"));

im.setValue("(123) 456-7890");

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

  • поле получает значение, соответствующее маске;
  • внутренний буфер Inputmask синхронизируется;
  • каретка устанавливается в корректную позицию.

Отличие setValue от прямого присваивания value

Прямое изменение DOM-значения:

input.value = "1234567890";

При активной маске приводит к следующим проблемам:

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

Эквивалент через Inputmask:

im.setValue("1234567890");

Результат:

  • значение преобразуется в формат (123) 456-7890;
  • символы распределяются по позициям маски;
  • внутренние структуры Inputmask остаются валидными.

Передача «сырого» и «форматированного» значения

setValue может принимать как уже отформатированные строки, так и «чистые» данные.

Сырой ввод

im.setValue("1234567890");

Inputmask интерпретирует последовательность цифр и распределяет их по шаблону.

Форматированный ввод

im.setValue("(123) 456-7890");

В этом случае происходит:

  • разбор строки с учётом маски;
  • удаление лишних символов;
  • повторное построение значения по правилам маски.

Влияние alias и конфигурации маски

Поведение setValue зависит от конфигурации экземпляра Inputmask.

Пример с alias:

Inputmask("decimal", {
  rightAlign: false,
  digits: 2
}).mask(input);

im.setValue("1234.5");

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

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

Работа с неполными значениями

Если переданное значение не полностью заполняет маску, Inputmask сохраняет частичное состояние:

im.setValue("123");

Для маски (999) 999-9999 результатом будет:

(123) ___-____

Поведение определяется настройками:

  • showMaskOnHover
  • showMaskOnFocus
  • clearIncomplete
  • placeholder

setValue и управление кареткой

После установки значения Inputmask автоматически рассчитывает позицию курсора.

Механизм включает:

  • поиск первой незаполненной позиции;
  • проверку допустимости символа;
  • корректировку смещения с учётом литералов маски.

При необходимости каретка может быть установлена в конец заполненной части, если маска считается завершённой.

Асинхронные сценарии использования

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

Пример с подгрузкой данных:

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

Важный аспект:

  • вызов должен происходить после инициализации маски;
  • при повторной инициализации старое состояние сбрасывается.

Повторное применение setValue

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

im.setValue("1111111111");
im.setValue("2222222222");

Каждый вызов:

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

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

setValue может триггерить события обновления:

  • onBeforeWrite
  • onBeforeMask
  • onKeyValidation
  • oncomplete
  • onincomplete

Порядок событий зависит от конфигурации и версии Inputmask.

Пример:

Inputmask("(999) 999-9999", {
  oncomplete: () => console.log("complete"),
  onincomplete: () => console.log("incomplete")
}).mask(input);

im.setValue("1234567890");

Особенности в React и Vue интеграциях

React

При работе с controlled components важно избегать конфликтов между state и Inputmask:

useEffect(() => {
  im.setValue(props.value);
}, [props.value]);

Основная особенность:

  • React обновляет value;
  • Inputmask должен синхронизировать внутренний буфер отдельно.

Vue

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

watch(() => model.value, (val) => {
  im.setValue(val);
});

Ключевой момент:

  • setValue выступает точкой синхронизации между реактивной моделью и DOM.

Сброс и переинициализация через setValue

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

im.setValue("");

Результат:

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

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

Если значение не соответствует допустимым символам маски:

im.setValue("abc!!!");

Inputmask:

  • отфильтровывает недопустимые символы;
  • оставляет только валидные позиции;
  • может вернуть пустую маску, если совпадений нет.

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

Многократные вызовы setValue в короткий промежуток времени приводят к:

  • постоянному пересчёту маски;
  • повторной валидации буфера;
  • перерасчёту каретки.

В высоконагруженных интерфейсах обычно применяется:

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

Взаимодействие с autofill и browser suggestions

При использовании автозаполнения браузера setValue часто применяется для нормализации результата:

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

Типичные сценарии применения

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