Создание собственных плагинов

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

  • Инициализация: плагин подключается к экземпляру Cleave через опцию plugins. Каждый плагин должен реализовать метод init, вызываемый при создании экземпляра Cleave.
  • Обработчики событий: плагины могут подписываться на события ввода (onInput, onKeyDown, onPaste) для динамического управления поведением поля.
  • Методы форматирования: при необходимости плагин может вмешиваться в процесс форматирования через переопределение методов getFormattedValue, setRawValue и других внутренних функций Cleave.js.
  • Жизненный цикл: плагин может реализовать методы destroy и reset, обеспечивая корректное удаление всех слушателей и очистку состояния при уничтожении экземпляра Cleave.

Структура плагина

Минимальный плагин состоит из объекта с обязательным методом init и необязательными методами обработки событий и очистки:

class ExamplePlugin {
    constructor(instance, options) {
        this.instance = instance; // Экземпляр Cleave
        this.options = options;   // Пользовательские опции
    }

    init() {
        // Код инициализации плагина
        this.instance.input.addEventListener('input', this.onInput.bind(this));
    }

    onInput(event) {
        // Пример: автоматическое удаление пробелов
        const value = event.target.value.replace(/\s+/g, '');
        this.instance.setRawValue(value);
    }

    destroy() {
        // Очистка слушателей при уничтожении
        this.instance.input.removeEventListener('input', this.onInput);
    }
}
  • constructor(instance, options) — сохраняет ссылку на Cleave и пользовательские опции.
  • init() — основной метод, где регистрируются события и устанавливаются начальные параметры.
  • destroy() — освобождает ресурсы, предотвращая утечки памяти.

Интеграция плагинов в Cleave.js

Для подключения плагина используется массив plugins при создании экземпляра Cleave:

const cleave = new Cleave('#input', {
    creditCard: true,
    plugins: [
        new ExamplePlugin(this, { removeSpaces: true })
    ]
});

Особенности подключения:

  • Плагины исполняются в порядке, в котором они указаны в массиве.
  • Каждый плагин получает ссылку на один и тот же экземпляр Cleave, что позволяет взаимодействовать между плагинами через общие методы и свойства.
  • Параметры плагина передаются через объект опций, что делает поведение настраиваемым.

Обработка пользовательского ввода

Плагины могут изменять текст до или после применения встроенного форматирования. Различие между этими этапами важно:

  • До форматирования: плагин получает “сырые” данные пользователя. Можно фильтровать символы, изменять порядок ввода или предотвращать определенные действия.
  • После форматирования: плагин получает уже отформатированное значение, что полезно для создания масок, дополнительных разделителей или визуальных эффектов.

Пример плагина, вставляющего тире после каждых трех символов:

class DashPlugin {
    constructor(instance) {
        this.instance = instance;
    }

    init() {
        this.instance.input.addEventListener('input', this.formatValue.bind(this));
    }

    formatValue() {
        let value = this.instance.getRawValue().replace(/-/g, '');
        value = value.match(/.{1,3}/g)?.join('-') || '';
        this.instance.setRawValue(value);
    }

    destroy() {
        this.instance.input.removeEventListener('input', this.formatValue);
    }
}

Работа с событиями

Cleave.js поддерживает привязку событий на уровне плагинов:

  • onKeyDown(event) — позволяет перехватывать и модифицировать клавиши до стандартной обработки.
  • onPaste(event) — позволяет фильтровать или изменять вставляемый текст.
  • onInput(event) — основной способ динамического изменения текста при вводе.

Использование этих событий повышает гибкость и позволяет реализовывать нестандартные сценарии, такие как:

  • ограничение диапазона значений,
  • автоматическая коррекция регистра,
  • динамическая подстановка символов.

Совместимость и взаимодействие плагинов

При использовании нескольких плагинов важно учитывать:

  • Порядок исполнения: первый плагин может изменять данные так, что последующие получают уже модифицированный текст.
  • Конфликты методов: плагины, переопределяющие одни и те же методы Cleave (setRawValue, getFormattedValue), должны корректно вызывать родительские методы через instance.
  • Чистка ресурсов: все плагины должны реализовать destroy, чтобы предотвратить утечки памяти и дублирование слушателей.

Настраиваемые опции плагинов

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

const cleave = new Cleave('#phone', {
    phone: true,
    plugins: [
        new CustomPlugin(this, { format: 'dash', maxLength: 12 })
    ]
});

Примеры опций:

  • maxLength — ограничение длины ввода.
  • format — стиль форматирования (тире, пробелы, точки).
  • allowNumbers / allowLetters — фильтрация допустимых символов.

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

Практические рекомендации по созданию плагинов

  • Минимизировать обработку в onInput: использовать дебаунс или throttling для полей с большим количеством символов.
  • Использовать внутренние методы Cleave (setRawValue, getFormattedValue) вместо прямой модификации input.value.
  • Тестировать совместимость с различными масками (номер карты, телефон, дата).
  • Очистка ресурсов обязательна при динамическом создании/удалении полей ввода.

Плагины в Cleave.js предоставляют мощный инструмент расширения стандартного поведения масок, позволяя создавать гибкие и интерактивные формы с поддержкой сложных сценариев форматирования и валидации.

Оглавление