HTML Drag and Drop API

Интерфейс HTML Drag and Drop позволяет приложениям использовать функционал перетаскивания в браузерах. Пользователь может выбрать перетаскиваемые элементы мышью, перетащить к элементу сброса и бросить их, отпустив кнопку мыши. Во время переноса за указателем следует полупрозрачный образ перетаскиваемого элемента

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

Данный обзор HTML Drag and Drop включает описание интерфейса, основные шаги по добавлению поддержки данного функционала в приложение, а также краткие данные о поддержке.

События перетаскивания

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

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

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

Событие Обработчик события Запускается, когда…
drag (en-US) ondrag (en-US) …длится перетаскивание элемента или выделения текста.
dragend (en-US) ondragend (en-US) …завершается перетаскивание (например, отпускается кнопка мыши или нажимается Escape; подробнее в Завершение перетаскивания.)
dragenter (en-US) ondragenter (en-US) …перетаскиваемый элемент попадает в допустимую цель сброса (Подробнее в Указание целей сброса.)
dragexit ondragexit (en-US) …элемент больше не является целью операции перетаскивания.
dragleave (en-US) ondragleave (en-US) …перетаскиваемый элемент покидает допустимую цель сброса.
dragover (en-US) ondragover (en-US) …элемент перетаскивается над допустимой целью сброса каждые несколько сотен миллисекунд
dragstart (en-US) ondragstart …пользователь начал перетаскивать элемент. (Подробнее в Начало операции перетаскивания.)
drop (en-US) ondrop (en-US) …элемент сброшен в допустимую зону сброса. (Подробнее в Выполнение сброса.)

Примечание: При перемещении файла из операционной системы в браузер ни событие dragstart, ни dragend не вызывается.

Интерфейсы

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

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

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

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

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

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

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

Примечание: DragEvent (en-US) и DataTransfer широко поддерживаются десктопными браузерами. Однако, поддержка интерфейсов DataTransferItem (en-US) и DataTransferItemList (en-US) достаточно ограниченная. Более подробно можно узнать в разделе Поддержка .

Специфичные для Gecko интерфейсы

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

Основы

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

Обозначьте, что можно перетаскивать

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

html
<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>

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

Определите данные перетаскивания

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

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

js
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,
  );
}

Определите изображение перетаскивания

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

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

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

Определите эффект перетаскивания

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

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

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

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

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

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

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

Определите зону сброса

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

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

html
<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 (en-US) может по-разному обрабатывать данные перетаскивания, в зависимости от конкретного приложения.

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

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

html
<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 (en-US) происходит у исходного элемента, который был целью начала перетаскивания.

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

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

Поддержка

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

Примеры и демо

Спецификации

Specification
HTML Standard

Совместимость с браузерами

{{Compat}}

Смотрите также