Методы экземпляра

Для начала работы с библиотекой Shopify Draggable необходимо создать экземпляр класса Draggable. Основной конструктор принимает два обязательных аргумента: контейнер элементов и массив селекторов элементов, которые будут перетаскиваться.

import { Draggable } from '@shopify/draggable';

const draggable = new Draggable(document.querySelectorAll('.container'), {
  draggable: '.item'
});

Пояснение ключевых параметров:

  • container — DOM-элемент или NodeList контейнера, в котором находятся перетаскиваемые элементы.
  • draggable — CSS-селектор элементов, которые можно перетаскивать.
  • Дополнительно можно передать такие опции, как handle (селектор для захвата), mirror (параметры зеркального объекта), delay, ignore и т. д.

Экземпляр, созданный через new Draggable(...), предоставляет набор методов для управления поведением перетаскивания, подписки на события и изменения состояния.

Методы управления состоянием

destroy()

Метод полностью удаляет все обработчики событий и очищает внутренние данные экземпляра. Используется, когда необходимость в перетаскивании элементов отпадает.

draggable.destroy();

После вызова destroy экземпляр больше не будет реагировать на события, и DOM-элементы вернутся к обычному поведению.

enable() и disable()

Позволяют динамически включать или отключать перетаскивание без уничтожения экземпляра.

draggable.disable(); // Перетаскивание отключено
draggable.enable();  // Перетаскивание включено

Особенности:

  • disable() отключает события drag & drop, но сохраняет конфигурацию.
  • enable() восстанавливает возможность перетаскивания для всех элементов.

addContainer(container)

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

draggable.addContainer(document.querySelector('.new-container'));

После вызова все элементы внутри нового контейнера, соответствующие селектору draggable, становятся доступными для перетаскивания.

removeContainer(container)

Удаляет контейнер из отслеживания экземпляром. Элементы внутри этого контейнера перестают быть перетаскиваемыми.

draggable.removeContainer(document.querySelector('.container'));

Метод не вызывает destroy, а только исключает указанный контейнер из текущего экземпляра.

Методы работы с элементами

getDraggableElements()

Возвращает массив всех элементов, которые могут быть перетаскиваемыми в текущий момент.

const items = draggable.getDraggableElements();
console.log(items);

Используется для динамической проверки состояния элементов, например, для обновления UI или применения стилей.

update()

Обновляет внутренние данные экземпляра, полезно при динамическом изменении DOM: добавлении или удалении элементов, изменении классов, изменении размеров контейнера.

draggable.update();

Важно: метод не пересоздаёт экземпляр, а лишь синхронизирует его внутреннее состояние с текущим DOM.

getDraggableContainers()

Возвращает массив всех контейнеров, в которых могут перемещаться элементы.

const containers = draggable.getDraggableContainers();
console.log(containers);

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

Методы работы с зеркалами и позиционированием

getMirror()

Возвращает DOM-элемент зеркала (mirror), создаваемого при перетаскивании.

const mirrorElement = draggable.getMirror();

Применение:

  • Стилизация зеркала.
  • Динамическое изменение позиции или размеров во время drag.

getDraggableElement(event)

Возвращает элемент, который инициировал событие drag или drop. Используется внутри обработчиков событий.

draggable.on('drag:start', (event) => {
  const item = draggable.getDraggableElement(event);
  item.style.opacity = '0.5';
});

Методы для интеграции с событиями

Экземпляр Draggable активно взаимодействует с системой событий. Методы on и off позволяют управлять подпиской на события.

draggable.on('drag:stop', (event) => {
  console.log('Перетаскивание завершено', event);
});

draggable.off('drag:stop'); // Отписка от события

Ключевые моменты:

  • События имеют формат тип:действие, например, drag:start, drag:move, drag:stop, sortable:sorted.
  • Передаваемый объект события содержит source, mirror, sensorEvent и другие свойства для работы с DOM и логикой.

Методы расширенной настройки

setOptions(options)

Позволяет изменить конфигурацию экземпляра на лету.

draggable.setOptions({
  delay: 200,
  handle: '.handle'
});

Изменения применяются к последующим событиям drag & drop без пересоздания экземпляра.

trigger(eventName, eventData)

Инициирует кастомное событие экземпляра. Используется для интеграции с внешними системами или для тестирования.

draggable.trigger('drag:stop', { source: someElement });

Метод может быть полезен для программного имитации действий пользователя или отладки.

Методы экземпляра Shopify Draggable обеспечивают полное управление поведением перетаскиваемых элементов, позволяют динамически изменять конфигурацию, работать с контейнерами и элементами, а также интегрироваться с системой событий для построения сложных интерфейсов drag & drop.

Оглавление