API перетаскивания HTML

Интерфейсы перетаскивания HTML позволяют приложениям использовать возможности перетаскивания в браузере.

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

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

В этом обзоре API перетаскивания HTML содержится описание интерфейсов, основных шагов по добавлению поддержки перетаскивания в приложение и сводка по взаимозаменяемости интерфейсов.

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

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

Каждый тип события перетаскивания имеет связанный обработчик событий:

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

Определение перетаскиваемых элементов

Для того, чтобы сделать элемент перетаскиваемым, необходимо добавить атрибут draggable и обработчик события dragstart, как показано в следующем примере кода:

<script>
  function dragstartHandler(ev) {
    // Add the target element's id to the data transfer object
    ev.dataTransfer.setData("text/plain", ev.target.id);
  }

  window.addEventListener("DOMContentLoaded", () => {
    // Get the element by id
    const element = document.getElementById("p1");
    // Add the ondragstart event listener
    element.addEventListener("dragstart", dragstartHandler);
  });
</script>

<p id="p1" draggable="true">This element is draggable.</p>

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

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

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

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

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

function dragstartHandler(ev) {
  // Add different types of drag data
  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(), как показано в следующем примере.

// Create an image and then use it for the drag image.
// NOTE: change "example.gif" to a real image URL or the image
// will not be created and the default drag image will be used.
let img = new Image();
img.src = "example.gif";
function dragstartHandler(ev) {
  ev.dataTransfer.setDragImage(img, 10, 10);
}

Дополнительную информацию об изображениях обратной связи перетаскивания см. в:

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

Определение эффекта выгрузки

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

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

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

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

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

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

Дополнительные сведения см. в:

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

Определение зоны выгрузки

По умолчанию браузер предотвращает любые действия при выгрузке на большинство HTML-элементов. Чтобы изменить это поведение, чтобы элемент стал зоной выгрузки или перетаскиваемым, элемент должен обрабатывать события dragover и drop.

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

<script>
  function dragoverHandler(ev) {
    ev.preventDefault();
    ev.dataTransfer.dropEffect = "move";
  }
  function dropHandler(ev) {
    ev.preventDefault();
    // Get the id of the target and add the moved element to the target's DOM
    const data = ev.dataTransfer.getData("text/plain");
    ev.target.appendChild(document.getElementById(data));
  }
</script>

<p id="target" ondrop="dropHandler(event)" ondragover="dragoverHandler(event)">
  Drop Zone
</p>

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

Дополнительную информацию см. в:

• Определение целевых элементов выгрузки

Обработка эффекта выгрузки

Обработчик события drop свободно обрабатывает данные перетаскивания специфичным для приложения способом.

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

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

<script>
  function dragstartHandler(ev) {
    // Add the target element's id to the data transfer object
    ev.dataTransfer.setData("application/my-app", ev.target.id);
    ev.dataTransfer.effectAllowed = "move";
  }
  function dragoverHandler(ev) {
    ev.preventDefault();
    ev.dataTransfer.dropEffect = "move";
  }
  function dropHandler(ev) {
    ev.preventDefault();
    // Get the id of the target and add the moved element to the target's DOM
    const data = ev.dataTransfer.getData("application/my-app");
    ev.target.appendChild(document.getElementById(data));
  }
</script>

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

Дополнительную информацию см. в:

• Выполнение выгрузки

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

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

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

Дополнительную информацию об обработке завершения операции перетаскивания см. в:

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

Интерфейсы HTML Перетаскивание и Опускание — это DragEvent, DataTransfer, DataTransferItem и DataTransferItemList.

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

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

Интерфейсы DragEvent и DataTransfer должны быть единственными необходимыми для добавления возможностей HTML Перетаскивания и Опускания в приложение.

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

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

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

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

• Операции перетаскивания
• Рекомендуемые типы перетаскивания
• Стандарт HTML Living: Перетаскивание и опускание
• Данные о совместимости перетаскивания и опускания от CanIUse