Обработчики событий и их параметры

Библиотека Dragula предоставляет удобный и гибкий способ реализации перетаскивания элементов в веб-приложениях на JavaScript. Центральным элементом работы с Dragula являются обработчики событий, которые позволяют реагировать на действия пользователя и управлять поведением перетаскиваемых элементов.

Основные события Dragula

Dragula генерирует несколько ключевых событий, каждое из которых передает определённый набор параметров, необходимых для точного контроля над перетаскиванием:

  • drag — событие срабатывает в момент начала перетаскивания элемента. Параметры:

    • el — DOM-элемент, который начал перетаскиваться.
    • source — контейнер, из которого был взят элемент.

  • dragend — событие завершения перетаскивания, независимо от того, был ли элемент перемещен в другой контейнер или возвращён на место. Параметры:

    • el — перетаскиваемый элемент.
    • container — контейнер, к которому элемент вернулся или был помещён.

  • drop — срабатывает при успешной отгрузке элемента в новый контейнер. Параметры:

    • el — элемент, который был перемещён.
    • target — контейнер, в который помещён элемент.
    • source — исходный контейнер.
    • sibling — элемент, перед которым вставлен перемещаемый элемент (или null, если элемент помещен в конец).

  • over и out — события при наведении элемента на контейнер или уходе с него. Параметры:

    • el — перетаскиваемый элемент.
    • container — контейнер, над которым произошло событие.
    • source — исходный контейнер элемента.

  • cancel — событие при отмене перетаскивания, если элемент возвращается на исходное место. Параметры совпадают с dragend.

  • cloned — срабатывает, когда создается клон элемента при перетаскивании. Параметры:

    • clone — клонированный элемент.
    • original — исходный элемент.
    • type — тип клона (обычно "mirror").

Регистрация обработчиков

Обработчики событий подключаются через метод on экземпляра Dragula. Стандартная форма:

const drake = dragula([container1, container2]);

drake.on('drop', function(el, target, source, sibling) {
    console.log('Элемент перемещён:', el);
});

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

Параметры el, source, target и sibling

  • el — всегда DOM-элемент, который перетаскивается. С его помощью можно изменять стили, добавлять классы или изменять данные через dataset.
  • source — контейнер, из которого был перемещен элемент. Полезен для отслеживания исходного расположения.
  • target — контейнер, в который элемент помещён. Может совпадать с source, если элемент возвращён на место.
  • sibling — указывает на элемент, перед которым вставляется перетаскиваемый элемент. Если null, вставка происходит в конец контейнера.

Особенности работы с mirror

Dragula создает зеркало (mirror) перетаскиваемого элемента, которое следует за курсором. Обработчик события cloned позволяет получить доступ к этому зеркалу, изменять его стиль или добавлять эффекты. Параметр type указывает, что элемент является зеркалом, что позволяет отделять логику работы с оригиналом от визуального представления.

Сценарии использования

  1. Изменение порядка элементов Используя drop и параметр sibling, можно динамически переставлять элементы в DOM:
drake.on('drop', (el, target, source, sibling) => {
    if(sibling) {
        target.insertBefore(el, sibling);
    } else {
        target.appendChild(el);
    }
});
  1. Валидация перетаскивания Проверка допустимости переноса через события drag или over:
drake.on('over', (el, container) => {
    if(container.dataset.type !== el.dataset.allowed) {
        container.classList.add('invalid-drop');
    }
});
drake.on('out', (el, container) => {
    container.classList.remove('invalid-drop');
});
  1. Создание визуальных эффектов Событие cloned позволяет кастомизировать зеркало элемента:
drake.on('cloned', (clone, original, type) => {
    if(type === 'mirror') {
        clone.style.opacity = '0.7';
        clone.style.border = '2px dashed #333';
    }
});

Удаление обработчиков

Чтобы убрать обработчик события, используется метод off:

drake.off('drop', myDropHandler);

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

Передача дополнительных данных

Хотя Dragula передает фиксированные параметры, часто требуется передавать собственные данные. Это делается через свойства DOM-элемента (dataset) или внешние структуры данных:

el.dataset.itemId = '123';

drake.on('drop', (el, target) => {
    console.log('ID элемента:', el.dataset.itemId);
});

Использование dataset позволяет привязывать информацию к элементу без изменения API Dragula.

Итоговая структура обработки событий

Правильная организация обработчиков включает:

  1. Определение цели события (drag, drop, over и т.д.).
  2. Использование параметров el, source, target, sibling для точного контроля DOM.
  3. Применение кастомных данных через dataset при необходимости.
  4. Управление визуальными эффектами через cloned и CSS-классы.
  5. Очистка обработчиков при удалении контейнеров.

Такой подход обеспечивает полное управление логикой перетаскивания и делает интеграцию Dragula в проект гибкой и предсказуемой.

Оглавление