Использование блоков и их настройка

Одной из ключевых возможностей библиотеки Cleave.js является механизм блоков (blocks). Он позволяет разбивать вводимые данные на группы символов фиксированной длины. Такой подход применяется при форматировании:

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

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

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

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

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

1234-5678-9012-3456

Каждый элемент массива blocks определяет количество символов до автоматической вставки разделителя.

Принцип работы блоков

При вводе символов Cleave.js:

  1. отслеживает позицию курсора;
  2. анализирует текущее значение;
  3. определяет активный блок;
  4. автоматически вставляет разделитель;
  5. ограничивает длину сегмента.

Массив:

blocks: [3, 2, 5]

создаёт структуру:

XXX-XX-XXXXX

где:

  • первый блок — 3 символа;
  • второй — 2 символа;
  • третий — 5 символов.

Настройка разделителей между блоками

Параметр delimiter

Разделитель между блоками задаётся свойством delimiter.

Пример с пробелом:

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

Результат:

1234 5678 9012 3456

Пример с точкой:

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

Результат:

12.34.56

Использование нескольких разделителей

Параметр delimiters

Если требуется использовать разные разделители между сегментами, применяется массив delimiters.

new Cleave('.input', {
    blocks: [3, 3, 3],
    delimiters: ['.', '-']
});

Результат:

123.456-789

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

Блок Разделитель
после первого .
после второго -

Количество разделителей обычно на единицу меньше количества блоков.

Ограничение длины ввода

Общая длина определяется суммой блоков.

Пример:

blocks: [2, 2, 2]

Максимально допустимый ввод:

6 символов

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

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

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

Пример буквенно-цифрового кода:

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

Результат:

ABC-123-DE45

Применение numericOnly

Для разрешения только цифр используется параметр numericOnly.

new Cleave('.code', {
    blocks: [4, 4, 4],
    delimiter: '-',
    numericOnly: true
});

Теперь любые буквы будут автоматически удаляться.

Настройка автоматического перевода в верхний регистр

Параметр uppercase

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

Ввод:

ab12cd34ef56

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

AB12-CD34-EF56

Настройка нижнего регистра

Параметр lowercase

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

Результат:

ab12:cd34

Использование префиксов совместно с блоками

Параметр prefix

new Cleave('.account', {
    prefix: 'ACC',
    blocks: [3, 4, 4],
    delimiter: '-'
});

Результат:

ACC123-4567-8901

Префикс не считается частью блока, а добавляется отдельно.

Поведение префикса при редактировании

Параметр noImmediatePrefix

new Cleave('.account', {
    prefix: 'ID',
    noImmediatePrefix: true,
    blocks: [4, 4]
});

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

Работа с пользовательскими шаблонами

Форматирование серийных номеров

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

Результат:

AB/1234-5678/CD

Динамическая длина блоков

В Cleave.js длина блоков задаётся статически. Однако конфигурацию можно менять динамически.

Пример изменения шаблона:

const cleave = new Cleave('.input', {
    blocks: [4, 4, 4, 4]
});

function switchFormat() {
    cleave.destroy();

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

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

Блоки могут иметь произвольную длину.

blocks: [1, 8, 2, 16]

Результат:

A-12345678-99-1234567890123456

Работа с датами через блоки

Формат даты фактически основан на тех же блоках.

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

Внутри используется структура:

blocks: [2, 2, 4]

Форматирование времени

new Cleave('.time', {
    time: true,
    timePattern: ['h', 'm', 's']
});

Внутренне применяется:

blocks: [2, 2, 2]

Комбинирование блоков с пользовательской логикой

Использование обработчиков событий

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

document.querySelector('.input')
    .addEventListener('input', function(event) {

        console.log(event.target.value);
        console.log(cleave.getRawValue());

    });

Отличие значений

Метод Результат
value форматированное значение
getRawValue() данные без разделителей

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

Разделителем может быть практически любой символ.

new Cleave('.input', {
    blocks: [3, 3, 3],
    delimiter: '|'
});

Результат:

123|456|789

Использование Unicode-разделителей

new Cleave('.input', {
    blocks: [2, 2, 2],
    delimiter: '•'
});

Результат:

12•34•56

Поведение курсора внутри блоков

Cleave.js автоматически корректирует позицию курсора:

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

Это особенно важно для длинных шаблонов:

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

Удаление символов между блоками

При нажатии Backspace:

1234-5678

удаление происходит корректно:

1234-567

а не:

1234--567

Библиотека самостоятельно управляет разделителями.

Вставка текста из буфера обмена

При вставке строки:

123456789012

и конфигурации:

blocks: [4, 4, 4],
delimiter: '-'

результат автоматически станет:

1234-5678-9012

Использование блоков без разделителей

Разделители можно отключить.

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

Визуально разделения не будет, однако ограничение длины сегментов сохранится внутренне.

Объединение блоков с пользовательской валидацией

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

document.querySelector('.input')
    .addEventListener('blur', function() {

        const raw = cleave.getRawValue();

        if (raw.length !== 12) {
            console.log('Ошибка длины');
        }

    });

Использование блоков в React

import Cleave from 'cleave.js/react';

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

Использование блоков во Vue

mounted() {

    new Cleave(this.$refs.input, {
        blocks: [3, 3, 3],
        delimiter: '.'
    });

}

Использование блоков в Angular

ngAfterViewInit() {

    new Cleave(this.input.nativeElement, {
        blocks: [2, 2, 4],
        delimiter: '/'
    });

}

Частые ошибки при настройке блоков

Неверное количество разделителей

Некорректно:

blocks: [3, 3, 3],
delimiters: ['-']

Корректно:

blocks: [3, 3, 3],
delimiters: ['-', '-']

Конфликт numericOnly и буквенных данных

numericOnly: true

не позволит вводить:

ABCD

Слишком короткие блоки

Конфигурация:

blocks: [1, 1, 1, 1, 1, 1]

может создавать неудобное перемещение курсора и ухудшать UX.

Оптимизация работы с большими шаблонами

Для длинных кодов рекомендуется:

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

Пример рациональной структуры:

blocks: [4, 4, 4, 4]

вместо:

blocks: [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]

Внутреннее представление блоков

При работе Cleave.js хранит:

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

Именно благодаря этому библиотека способна корректно:

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