Работа с буквенными символами

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

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

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

---

Формирование буквенных блоков

Основной механизм буквенных масок строится вокруг параметров blocks и delimiter.

Простейший пример:

<input id="code">

new Cleave('#code', {
    blocks: [3, 3, 3],
    delimiter: '-',
    uppercase: true
});

Результат ввода:

ABC-DEF-GHI

Здесь:

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

---

Использование свойства uppercase

Параметр uppercase — один из ключевых инструментов при работе с буквенными кодами.

new Cleave('#serial', {
    blocks: [4, 4],
    delimiter: ':',
    uppercase: true
});

Ввод:

ab12cd34

Преобразуется в:

AB12:CD34

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

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

---

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

Для некоторых систем требуется строгое использование нижнего регистра.

new Cleave('#slug', {
    blocks: [5, 5],
    delimiter: '_',
    lowercase: true
});

Ввод:

HELLOworld

Результат:

hello_world

Подобный режим часто применяется:

• в URL-идентификаторах;
• при генерации slug;
• в системных ключах;
• в API-токенах;
• в Linux-ориентированных интерфейсах.

---

Ограничение длины буквенных сегментов

Массив blocks позволяет жёстко ограничивать длину отдельных частей.

new Cleave('#product', {
    blocks: [2, 5, 3],
    delimiter: '-',
    uppercase: true
});

Формат:

AB-12345-XYZ

Поведение:

Блок	Максимальная длина
Первый	2
Второй	5
Третий	3

При превышении длины Cleave.js автоматически переносит курсор к следующему сегменту.

---

Работа с буквенно-цифровыми идентификаторами

Наиболее распространённый сценарий — смешанный ввод букв и цифр.

new Cleave('#license', {
    blocks: [2, 2, 4],
    delimiter: '-',
    uppercase: true
});

Пример:

AB-12-CD34

Библиотека не запрещает смешивать символы внутри блока, если явно не задана дополнительная фильтрация.

---

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

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

new Cleave('#complex', {
    blocks: [2, 3, 2],
    delimiters: ['/', ':'],
    uppercase: true
});

Результат:

AB/CDE:FG

Массив delimiters применяется последовательно между блоками.

---

Комбинирование буквенных кодов с префиксами

Свойство prefix позволяет добавлять фиксированную текстовую часть.

new Cleave('#employee', {
    prefix: 'EMP',
    delimiter: '-',
    blocks: [3, 4],
    uppercase: true
});

Результат:

EMP-ABC-1234

Префикс:

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

---

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

Иногда префикс должен появляться только после начала ввода.

new Cleave('#client', {
    prefix: 'CL',
    noImmediatePrefix: true,
    blocks: [2, 4],
    delimiter: '-'
});

Поведение:

• пустое поле остаётся пустым;
• префикс появляется после первого символа.

---

Фильтрация символов через onValueChanged

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

new Cleave('#letters-only', {
    blocks: [4, 4],
    delimiter: '-',

    onValueChanged: function (e) {
        e.target.value = e.target.value.replace(/[^A-Z\-]/g, '');
    }
});

Разрешены только:

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

---

Ограничение только кириллических символов

Возможна фильтрация под конкретные алфавиты.

new Cleave('#cyrillic', {
    blocks: [3, 3],

    onValueChanged: function (e) {
        e.target.value = e.target.value.replace(/[^А-Яа-я]/g, '');
    }
});

Допускаются только символы кириллицы.

---

Поддержка Unicode

Поскольку Cleave.js работает поверх стандартных строк JavaScript, библиотека поддерживает Unicode-символы:

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

Пример:

new Cleave('#unicode', {
    blocks: [2, 2, 2],
    delimiter: '-'
});

Ввод:

ЖБ-漢字-AB

---

Работа с регулярными выражениями

На практике буквенные маски часто объединяются с регулярными выражениями.

new Cleave('#passport', {
    blocks: [2, 7],
    delimiter: ' ',

    onValueChanged: function (e) {
        e.target.value = e.target.value
            .replace(/[^A-Z0-9 ]/g, '')
            .toUpperCase();
    }
});

Формат:

AB 1234567

---

Создание автомобильных номеров

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

new Cleave('#car', {
    blocks: [1, 3, 2],
    delimiters: [' ', ' '],
    uppercase: true
});

Результат:

A 123 BC

---

Форматирование артикулов

Артикулы часто содержат группы букв и цифр.

new Cleave('#sku', {
    blocks: [3, 4, 2],
    delimiters: ['-', '/'],
    uppercase: true
});

Пример:

ABC-1234/XY

---

Работа с корпоративными кодами

Внутренние системы часто используют длинные буквенные идентификаторы.

new Cleave('#corp', {
    blocks: [4, 4, 4, 4],
    delimiter: '-',
    uppercase: true
});

Формат:

ABCD-EFGH-IJKL-MNOP

Подобная структура облегчает:

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

---

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

Метод getRawValue() возвращает строку без разделителей.

const cleave = new Cleave('#promo', {
    blocks: [4, 4],
    delimiter: '-',
    uppercase: true
});

console.log(cleave.getRawValue());

Если пользователь ввёл:

ABCD-EFGH

Метод вернёт:

ABCDEFGH

Это особенно важно:

• при отправке данных на сервер;
• в API;
• при сравнении идентификаторов;
• в системах поиска.

---

Динамическое изменение формата

Конфигурацию можно менять во время работы приложения.

const instance = new Cleave('#dynamic', {
    blocks: [3, 3],
    delimiter: '-'
});

Позже:

instance.destroy();

new Cleave('#dynamic', {
    blocks: [4, 4, 4],
    delimiter: ':',
    uppercase: true
});

---

Интеграция с React

Пример буквенной маски в React:

import Cleave from 'cleave.js/react';

function App() {
    return (
        <Cleave
            options={{
                blocks: [4, 4],
                delimiter: '-',
                uppercase: true
            }}
        />
    );
}

---

Интеграция с Vue

mounted() {
    new Cleave(this.$refs.code, {
        blocks: [3, 3, 3],
        delimiter: '-',
        uppercase: true
    });
}

---

Интеграция с Angular

ngAfterViewInit() {
    new Cleave('#field', {
        blocks: [2, 2, 2],
        delimiter: ':',
        uppercase: true
    });
}

---

Типичные ошибки при работе с буквенными масками

Конфликт с ручной валидацией

Неправильная последовательность обработки:

input.addEventListener('input', function () {
    this.value = this.value.replace(/\d/g, '');
});

Подобная логика может конфликтовать с внутренним управлением курсором Cleave.js.

---

Разрушение разделителей

Ошибка:

value.replace(/-/g, '')

Если обработка выполняется некорректно, формат может ломаться во время ввода.

---

Повторная инициализация

Создание нескольких экземпляров для одного поля:

new Cleave('#id', {...});
new Cleave('#id', {...});

Может привести к:

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

---

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

Большие буквенные шаблоны:

blocks: [4,4,4,4,4,4,4]

Обычно работают быстро, поскольку Cleave.js:

• не использует тяжёлый DOM-анализ;
• обновляет только текущее значение поля;
• минимизирует количество операций.

Однако чрезмерно сложная логика внутри onValueChanged может вызывать задержки.

---

Практический пример универсального буквенного идентификатора

new Cleave('#universal-id', {
    blocks: [3, 3, 4, 2],
    delimiters: ['-', '/', '-'],
    uppercase: true,

    onValueChanged: function (e) {
        e.target.value = e.target.value.replace(
            /[^A-Z0-9\-\/]/g,
            ''
        );
    }
});

Результат:

ABC-DEF/1234-XY

Особенности реализации:

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