drake.end() - программная остановка

Dragula — это библиотека для реализации drag-and-drop функционала в веб-приложениях на JavaScript. Основная цель Dragula — упростить перетаскивание элементов между контейнерами или внутри одного контейнера. Важной частью управления жизненным циклом Dragula является метод drake.end(), который позволяет программно завершить текущее перетаскивание.

Основное назначение drake.end()

Метод drake.end() предназначен для принудительного завершения перетаскивания элемента. Он имитирует ситуацию, когда пользователь отпускает перетаскиваемый объект мышью. Этот метод полезен в случаях, когда нужно контролировать процесс drag-and-drop программно: например, отменить текущее действие при определённых условиях или автоматически переместить элемент в исходное положение.

Синтаксис и использование

drake.end();

Где drake — это объект, возвращаемый функцией dragula(containers, options).

Простейший пример использования:

const containers = [document.querySelector('#left'), document.querySelector('#right')];
const drake = dragula(containers);

drake.on('drag', function (el) {
    console.log('Начато перетаскивание:', el);
});

// Программная остановка перетаскивания
setTimeout(() => {
    drake.end();
    console.log('Перетаскивание завершено программно');
}, 2000);

В этом примере элемент, находящийся в процессе перетаскивания, будет автоматически «отпущен» через 2 секунды после начала drag-события.

Влияние на события

Метод drake.end() триггерит события Dragula в точности так, как если бы пользователь завершил перетаскивание:

  • dragend — завершается перетаскивание конкретного элемента.
  • drop — вызывается для контейнера, в котором элемент оказался после окончания перетаскивания.
  • cancel — срабатывает, если элемент возвращается в исходное место.

Важно учитывать, что drake.end() не создаёт новых событий помимо стандартного набора Dragula, но активирует все обработчики, зарегистрированные на этих событиях.

Практические сценарии использования

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

Иногда необходимо проверять допустимость перемещения элемента до завершения drag-and-drop. Например, если перемещаемый элемент не соответствует критериям целевого контейнера, можно вызвать drake.end() для принудительного возврата:

drake.on('drop', function (el, target, source, sibling) {
    if (!target.classList.contains('allowed')) {
        drake.end();
        console.log('Перемещение запрещено, возвращаем элемент');
    }
});
  1. Автоматическое завершение перетаскивания

В интерфейсах с тайм-аутами или анимацией может потребоваться автоматически завершить drag через определённое время:

drake.on('drag', function(el) {
    setTimeout(() => drake.end(), 1000); // завершение через 1 секунду
});
  1. Сброс состояния перед новым перетаскиванием

В случаях, когда необходимо гарантировать, что предыдущий drag полностью завершён перед началом нового, метод drake.end() обеспечивает чистое состояние объекта drake:

if (drake.dragging) {
    drake.end();
}

Отличия от методов cancel() и remove()

  • drake.cancel() — возвращает элемент в исходное положение, независимо от того, был ли drop успешным.
  • drake.remove() — удаляет элемент из DOM без перемещения в другой контейнер.
  • drake.end() — завершает перетаскивание в текущем положении элемента, активируя события drop или cancel в зависимости от состояния.

Советы по использованию

  • Вызов drake.end() безопасно выполнять даже вне обработчиков событий; это не вызывает ошибок, если перетаскивание неактивно.
  • Метод помогает интегрировать Dragula с другими интерфейсными библиотеками, где drag-and-drop может быть ограничен внешними условиями.
  • Рекомендуется использовать вместе с проверками drake.dragging, чтобы избежать лишних вызовов и ненужных событий.

Пример комплексного применения

const containers = [document.querySelector('#todo'), document.querySelector('#done')];
const drake = dragula(containers);

drake.on('drag', (el) => {
    console.log('Элемент в процессе перетаскивания:', el.textContent);
});

drake.on('drop', (el, target, source) => {
    if (!target.classList.contains('done')) {
        console.log('Перемещение запрещено');
        drake.end(); // элемент возвращается
    } else {
        console.log('Элемент успешно перемещён в Done');
    }
});

В этом сценарии drake.end() выступает инструментом контроля, позволяя программно отменять неразрешённые действия и поддерживать консистентность интерфейса.

Метод drake.end() является ключевым инструментом для управления жизненным циклом drag-and-drop, позволяя программно завершать перетаскивание, контролировать события и интегрировать Dragula в сложные интерфейсы. Его использование обеспечивает надежность и предсказуемость поведения при работе с динамическими DOM-элементами.

Оглавление