Передача props и опций

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

Конфигурация может задаваться в двух основных формах:

  • объект опций при создании экземпляра Cleave
  • props в обёртках для React, Vue, Angular и других интеграций

Базовая передача опций при инициализации

В классическом JavaScript-использовании Cleave.js принимает объект конфигурации вторым аргументом конструктора.

const cleave = new Cleave('.input-phone', {
  phone: true,
  phoneRegionCode: 'RU'
});

Объект опций определяет режим работы:

  • phone — включает телефонное форматирование
  • date — активирует формат даты
  • numeral — числовое форматирование
  • creditCard — режим банковской карты
  • blocks — кастомное разбиение строки

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

Приоритет и объединение конфигурации

При инициализации Cleave.js применяется фиксированный порядок приоритета параметров:

  1. Явно указанные опции конструктора
  2. Значения по умолчанию внутри выбранного пресета (phone/date/numeral)
  3. Внутренние fallback-значения библиотеки

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

Пример переопределения поведения:

new Cleave('.input-card', {
  creditCard: true,
  onCreditCardTypeChanged: function (type) {
    console.log(type);
  }
});

Опции форматирования чисел

Режим numeral использует расширенный набор параметров:

new Cleave('.input-number', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand',
  numeralDecimalMark: ',',
  delimiter: ' '
});

Ключевые параметры:

  • numeralThousandsGroupStyle — стиль группировки (thousand, lakh, wan)
  • numeralDecimalMark — символ десятичного разделителя
  • delimiter — символ группировки разрядов
  • numeralDecimalScale — количество знаков после запятой

Изменение любого параметра приводит к пересборке строки при каждом вводе, без необходимости дополнительной логики.

Передача опций для дат

Режим date использует структурированные блоки:

new Cleave('.input-date', {
  date: true,
  datePattern: ['d', 'm', 'Y'],
  delimiter: '.'
});

Основные параметры:

  • datePattern — массив сегментов даты
  • delimiter — разделитель между сегментами
  • dateMin и dateMax — ограничения диапазона

Структура datePattern определяет порядок и длину блоков, например:

  • ['Y', 'm', 'd'] → ISO-подобный формат
  • ['d', 'm', 'Y'] → европейский формат

Кастомные блоки через blocks

Наиболее универсальный механизм — blocks, позволяющий полностью управлять разбиением строки.

new Cleave('.input-custom', {
  blocks: [4, 4, 4, 4],
  delimiter: '-'
});

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

  • каждый элемент задаёт длину сегмента
  • delimiter вставляется между сегментами
  • избыточный ввод автоматически обрезается

Применение:

  • номера счетов
  • идентификаторы
  • внутренние коды систем

Передача опций в React-обёртке

В React используется компонент-обёртка, где конфигурация передаётся через props.

import Cleave from 'cleave.js/react';

function PhoneInput() {
  return (
    <Cleave
      options={{
        phone: true,
        phoneRegionCode: 'RU'
      }}
    />
  );
}

Здесь объект options полностью соответствует нативному API Cleave.js, но передаётся декларативно через props.

Разделение props и options

В React-реализации существует важное разделение:

  • props компонента (React-уровень)
  • options (уровень Cleave.js)

Пример:

<Cleave
  value={value}
  onCha nge={handleChange}
  options={{
    numeral: true,
    numeralDecimalScale: 2
  }}
/>

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

  • value управляется React
  • onChange пробрасывает событие изменения
  • options не участвуют в React lifecycle напрямую

Динамическое изменение опций

Изменение props options приводит к пересозданию внутренней конфигурации.

const [region, setRegion] = useState('RU');

<Cleave
  options={{
    phone: true,
    phoneRegionCode: region
  }}
/>

При изменении region происходит:

  • пересоздание форматтера
  • перерасчёт текущего значения
  • повторное применение маски

Это важно учитывать при частых обновлениях состояния, чтобы избежать лишних пересборок.

Передача опций в Vue-обёртке

Во Vue конфигурация также задаётся через props компонента:

<cleave
  :options="{
    numeral: true,
    numeralThousandsGroupStyle: 'thousand'
  }"
/>

Особенность Vue-интеграции:

  • реактивность автоматически отслеживает изменения объекта options
  • изменения применяются без ручного пересоздания экземпляра

Локальные изменения и переинициализация

В некоторых случаях изменение опций требует полного пересоздания экземпляра Cleave.js. Это происходит при изменении:

  • режима форматирования (например, phone → numeral)
  • структуры blocks
  • типа даты (datePattern)

В таких случаях библиотека уничтожает текущий инстанс и создаёт новый.

cleave.destroy();

cleave = new Cleave(element, newOptions);

Дефолтные значения и переопределение

Каждая опция имеет значение по умолчанию. При отсутствии явного указания используются встроенные настройки:

  • delimiter = ’’
  • numeralDecimalScale = unlimited
  • dateDelimiter = ‘/’

Переопределение работает полностью поверх этих значений:

{
  numeral: true,
  delimiter: ' '
}

Даже если внутренний пресет устанавливает другой разделитель, внешний параметр имеет приоритет.

Сложные конфигурации и комбинирование опций

Некоторые режимы допускают расширенную комбинацию параметров:

new Cleave('.input', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand',
  prefix: '₽ ',
  rawValueTrimPrefix: true
});

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

  • prefix добавляет статический префикс
  • rawValueTrimPrefix управляет извлечением «чистого» значения
  • numeral активирует числовую логику

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

Обработка функций-колбэков в опциях

Некоторые опции принимают функции, позволяющие реагировать на изменения состояния:

new Cleave('.input-card', {
  creditCard: true,
  onCreditCardTypeChanged: function (type) {
    console.log(type);
  }
});

Колбэки используются для:

  • определения типа карты
  • отслеживания изменений ввода
  • интеграции с UI-логикой

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

Наследование и повторное использование конфигураций

Конфигурации можно выносить в отдельные объекты:

const phoneConfig = {
  phone: true,
  phoneRegionCode: 'RU'
};

new Cleave('.input1', phoneConfig);
new Cleave('.input2', phoneConfig);

Это обеспечивает:

  • единообразие форматирования
  • упрощение поддержки
  • снижение дублирования кода

При необходимости объект можно расширять:

const extended = {
  ...phoneConfig,
  delimiter: ' '
};

Поведение при конфликтующих опциях

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

{
  phone: true,
  numeral: true
}

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

Оглавление