HTML Drag and Drop API

HTML drag-and-drop использует модель событий DOM и события перетаскивания унаследованные от событий мыши. Обычно операция перетаскивания начинается, когда пользователь выбирает перетаскиваемый элемент, перемещает его в зону элемента сброса, после чего отпускает.

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

У каждого события перетаскивания есть связанный глобальный обработчик события:

К HTML Drag and Drop интерфейсам относятся DragEvent, DataTransfer, DataTransferItem и DataTransferItemList.

Интерфейс DragEvent имеет конструктор и одно свойство dataTransfer, которое является объектом DataTransfer.

Объекты DataTransfer включают состояние события, такое как тип выполненного перетаскивания (вроде copy или move), данные перетаскивания (один или более элементов) и MIME-тип каждого элемента перетаскивания. Объекты DataTransfer также имеют методы добавления или удаления элементов из данных о перетасивании.

Для добавления в приложение поддержки HTML Drag and Drop, следует использовать только интерфейсы DragEvent и DataTransfer. (Firefox поддерживает некоторые Специфичные для Gecko расширения объекта DataTransfer, но они будут работать только в Firefox.)

Каждый объект DataTransfer содержит свойство items, являющееся списком объектов DataTransferItem. Объект DataTransferItem представляет собой отдельный перетаскиваемый элемент, каждый со свойством kind (либо string либо file) и свойство type для MIME-типа данных элемента. Объект DataTransferItem также имеет методы для получения данных о перемещаемых элементах.

Объект DataTransferItemList содержит список объектов DataTransferItem. Он имеет методы для добавления перетаскиваемых объектов в список, их удаления, и очистки списка.

Ключевое отличие интерфейсов DataTransfer и DataTransferItem заключается в том, что первый использует синхронный метод доступа к данным о перетаскиваемых объектах getData(), а второй – асинхронный метод getAsString().

Mozilla и Firefox поддерживают некоторые функции, которых нет в стандартной drag-and-drop модели. Это удобные функции, помогающие перетаскивать несколько элементов или нестроковых данных (например, файлов). Для получения дополнительной информации смотрите Перетаскивание и Сброс нескольких элементов. Дополнительно посмотрите DataTransfer страницу справочника со всеми специфичными для Gecko свойствами и методами.

В данном разделе кратко описаны основные шаги добавления в приложение функционала drag-and-drop.

Чтобы сделать элемент перетаскиваемым, к нему нужно добавить атрибут draggable и глобальный обработчик события ondragstart. Пример показан в коде ниже:

<script>
  function dragstart_handler(ev) {
    // Добавить id целевого элемента в объект передачи данных
    ev.dataTransfer.setData("text/plain", ev.target.id);
  }

  window.addEventListener("DOMContentLoaded", () => {
    // Найти элемент по id
    const element = document.getElementById("p1");
    // Добавить обработчик события `dragstart`
    element.addEventListener("dragstart", dragstart_handler);
  });
</script>

<p id="p1" draggable="true">Данный элемент является перетаскиваемым.</p>

Для получения дополнительной информации смотрите:

• Справочник атрибута draggable
• Руководство по операциям перетаскивания

Приложение может добавлять в операцию перетаскивания любое количество элементов данных. Каждый элемент данных — это строка определённого типа. Обычно MIME-тип равен text/html.

У каждого события перетаскивания есть свойство dataTransfer, которое содержит данные о событии. Это свойство (являющееся объектом DataTransfer), также имеет методы управления данными перетаскивания. Метод setData() используется для добавления элемента в данные перетаскивания, как показано в следующем примере.

function dragstart_handler(ev) {
  // Добавление различных типов данных перетаскивания
  ev.dataTransfer.setData("text/plain", ev.target.innerText);
  ev.dataTransfer.setData("text/html", ev.target.outerHTML);
  ev.dataTransfer.setData(
    "text/uri-list",
    ev.target.ownerDocument.location.href,
  );
}

• Список общих типов данных, используемых при перетаскивании (например, текст, HTML, ссылки и файлы), смотрите в разделе Рекомендуемые типы перетаскивания.
• Для получения дополнительной информации, смотрите раздел Данные перетаскивания.

По умолчанию браузер предоставляет изображение, которое в процессе перетаскивания отображается рядом с указателем. Тем не менее, приложение может использовать сторонее изображение с помощью метода setDragImage(), как показано в следующем примере.

function dragstart_handler(ev) {
  // Создайте изображение, чтобы использовать как изображение перетаскивания
  // Примечание: замените "example.gif" на URL-адрес реального изоражения,
  // иначе оно не будет создано и будет использоваться изображение по умолчанию
  let img = new Image();
  img.src = "example.gif";
  ev.dataTransfer.setDragImage(img, 10, 10);
}

Узнать больше об изображении перетаскивания можно в:

• Настройка изображения перетаскивания

Свойство dropEffect используется для управления обратной связью, которую пользователь получает во время операции перетаскивания. Обычно это влияет на то, какой курсор будет отображаться во время перетаскивания. Например, когда пользователь наводит указатель на цель сброса, курсор браузера может отражать тип операции, которая будет произведена.

Можно определить три эффекта:

1. copy обозначает, что перетаскиваемые данные будут скопированы из предыдущего места в место сброса.
2. move обозначает, что перетаскиваемые данные будут перемещены из предыдущего места в место сброса.
3. link обозначает, что между исходным местоположением и местом сброса будет создана некоторая форма свази.

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

Следующий пример демонстрирует, как использовать это свойство.

function dragstart_handler(ev) {
  ev.dataTransfer.dropEffect = "copy";
}

Для получения дополнительной информации смотрите:

• Эффекты перетаскивания

По умолчанию, при сбросе на большинство элементов, браузер не производит никаких действий. Чтобы изменить это поведение и сделать элемент зоной сброса или сбрасываемым, он должен иметь атрибуты для обработчиков событий ondragover и ondrop.

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

<script>
  function dragover_handler(ev) {
    ev.preventDefault();
    ev.dataTransfer.dropEffect = "move";
  }
  function drop_handler(ev) {
    ev.preventDefault();
    // Получить id цели и добавить перемещённый элемент в его DOM
    const data = ev.dataTransfer.getData("text/plain");
    ev.target.appendChild(document.getElementById(data));
  }
</script>

<p
  id="target"
  ondrop="drop_handler(event)"
  ondragover="dragover_handler(event)">
  Drop Zone
</p>

Обратите внимание, что каждый обработчик вызывает preventDefault(), чтобы предотвратить дополнительную обработку данного события (например, события касания или события указателя).

Для получения дополнительной информации смотрите:

• Указание целей сброса

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

Как правило, для извлечения и последующей обработки элементов перетаскивания, приложение использует метод getData(). Кроме того, семантика приложения может отличаться в зависимости от значения dropEffect и состояния кнопок-модификаторов.

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

<script>
  function dragstart_handler(ev) {
    // Добавить id целевого элемента в объект передачи данных
    ev.dataTransfer.setData("application/my-app", ev.target.id);
    ev.dataTransfer.effectAllowed = "move";
  }
  function dragover_handler(ev) {
    ev.preventDefault();
    ev.dataTransfer.dropEffect = "move";
  }
  function drop_handler(ev) {
    ev.preventDefault();
    // Получить id целевого элемента и добавить перемещаемый элемент в его DOM
    const data = ev.dataTransfer.getData("application/my-app");
    ev.target.appendChild(document.getElementById(data));
  }
</script>

<p id="p1" draggable="true" ondragstart="dragstart_handler(event)">
  This element is draggable.
</p>
<div
  id="target"
  ondrop="drop_handler(event)"
  ondragover="dragover_handler(event)">
  Drop Zone
</div>

Для получения дополнительной информации смотрите:

• Выполнение сброса

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

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

Для получения дополнительной информации об обработке завершения операции перетаскивания, смотрите:

• Завершение перетаскивания

Из таблицы поддержки браузерами интерфейса DataTransferItem видно, что поддержка drag-and-drop достаточно обширная среди десктопных браузеров (за исключением интерфейсов DataTransferItem и DataTransferItemList, у которых поддержка ниже). Эти данные также указывают, что среди мобильных устройств поддержка очень низкая.

• Копирование и перемещение элементов с помощью интерфейса DataTransfer
• Копирование и перемещение элементов с помощью интерфейса DataTransferListItem
• Перетаскивание и сброс файлов (только Firefox): https://jsfiddle.net/9C2EF/
• Перетаскивание и сброс файлов (все браузеры): https://jsbin.com/hiqasek/
• Использование Drag and Drop API в проекте парковки: https://park.glitch.me/ (Отредактировать можно здесь)

• Операции перетаскивания
• Перетаскивание и сброс нескольких файлов
• Рекомендуемые типы перетаскивания
• HTML5 Living Standard: Drag and Drop
• Информация о поддержке Drag and Drop из CanIUse