HTML Drag and Drop API

HTML Drag-and-Drop verwendet das DOM-Ereignismodell und Drag-Ereignisse, die von Mausereignissen geerbt werden. Ein typischer Drag-Vorgang beginnt, wenn ein Benutzer ein ziehbares Element auswählt, fortgesetzt wird, wenn der Benutzer das Element zu einem ablegbaren Element zieht, und endet, wenn der Benutzer das gezogene Element loslässt.

Während Ziehvorgängen werden mehrere Ereignistypen ausgelöst, und einige Ereignisse können viele Male ausgelöst werden, wie zum Beispiel die Ereignisse drag und dragover.

Jeder Drag-Ereignistyp hat einen zugeordneten Ereignishandler:

Dieser Abschnitt ist eine Zusammenfassung der grundlegenden Schritte, um eine Drag-and-Drop-Funktionalität zu einer Anwendung hinzuzufügen.

Identifizieren, was ziehbar ist

Um ein Element ziehbar zu machen, muss das Attribut draggable und der dragstart Ereignishandler hinzugefügt werden, wie im folgenden Codebeispiel gezeigt:

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

Für weitere Informationen siehe:

• Draggable-Attribut-Referenz
• Leitfaden für Drag-Vorgänge

Definieren der Drag-Daten

Die Anwendung ist frei, eine beliebige Anzahl von Datenobjekten in einen Ziehvorgang einzubeziehen. Jedes Datenobjekt ist ein String eines bestimmten type — typischerweise ein MIME-Typ wie text/html.

Jeder DragEvent hat eine dataTransfer Eigenschaft, die die Daten des Ereignisses enthält. Diese Eigenschaft (die ein DataTransfer Objekt ist) hat auch Methoden, um Drag-Daten zu verwalten. Die Methode setData() wird verwendet, um ein Objekt zu den Drag-Daten hinzuzufügen, wie im folgenden Beispiel gezeigt.

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

• Für eine Liste der gebräuchlichen Datentypen, die beim Drag-and-Drop verwendet werden (wie Text, HTML, Links und Dateien), siehe Empfohlene Drag-Typen.
• Für weitere Informationen über Drag-Daten, siehe Drag-Daten.

Definieren des Drag-Bildes

Standardmäßig liefert der Browser ein Bild, das während eines Ziehvorgangs neben dem Zeiger erscheint. Eine Anwendung kann jedoch mit der Methode setDragImage() ein benutzerdefiniertes Bild definieren, wie im folgenden Beispiel gezeigt.

// 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);
}

Erfahren Sie mehr über Drag-Feedback-Bilder in:

• Festlegen des Drag-Feedback-Bildes

Definieren der Drop-Effekt

Die Eigenschaft dropEffect wird verwendet, um das Feedback zu steuern, das dem Benutzer während eines Drag-and-Drop-Vorgangs gegeben wird. Sie beeinflusst in der Regel, welcher Cursor der Browser beim Ziehen anzeigt. Zum Beispiel kann, wenn der Benutzer über ein Ziel schwebt, der Cursor des Browsers anzeigen, welche Art von Vorgang vorgenommen wird.

Drei Effekte können definiert werden:

1. copy zeigt an, dass die gezogenen Daten von ihrem derzeitigen Standort zum Zielort kopiert werden.
2. move zeigt an, dass die gezogenen Daten von ihrem derzeitigen Standort zum Zielort verschoben werden.
3. link zeigt an, dass eine Art Beziehung oder Verbindung zwischen den Quell- und Zielorten hergestellt wird.

Während des Ziehvorgangs können Zieh-Effekte modifiziert werden, um anzuzeigen, dass an bestimmten Orten bestimmte Effekte erlaubt sind.

Das folgende Beispiel zeigt, wie diese Eigenschaft verwendet wird.

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

Für weitere Details siehe:

• Zieh-Effekte

Definieren einer Drop-Zone

Standardmäßig verhindert der Browser, dass etwas passiert, wenn etwas auf die meisten HTML-Elemente fallen gelassen wird. Um dieses Verhalten zu ändern, damit ein Element eine Drop-Zone wird oder abgelegt werden kann, muss das Element auf die Ereignisse dragover und drop hören.

Das folgende Beispiel zeigt, wie diese Attribute verwendet werden und beinhaltet grundlegende Ereignishandler für jedes Attribut.

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

Beachten Sie, dass jeder Handler preventDefault() aufruft, um eine zusätzliche Ereignisverarbeitung für dieses Ereignis zu verhindern (wie Touch-Ereignisse oder Zeigerereignisse).

Für weitere Informationen siehe:

• Festlegen von Zielorten

Umgang mit dem Drop-Effekt

Der Handler für das drop Ereignis ist frei, die Drag-Daten in einer anwendungsspezifischen Weise zu verarbeiten.

Typischerweise verwendet eine Anwendung die Methode getData(), um Ziehobjekte abzurufen und sie dann entsprechend zu verarbeiten. Zusätzlich können Semantiken der Anwendung je nach Wert der dropEffect und/oder dem Status der Modifikator-Tasten unterschiedlich sein.

Das folgende Beispiel zeigt einen Drop-Handler, der die id des Quell-Elements von den Drag-Daten abruft und dann die id verwendet, um das Quell-Element zum Zielelement zu verschieben:

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

Für weitere Informationen siehe:

• Ausführen eines Drops

Ende des Drag-Vorgangs

Am Ende eines Ziehvorgangs wird das Ereignis dragend am Quell-Element ausgelöst — dem Element, das das Ziel des Ziehstarts war.

Dieses Ereignis wird unabhängig davon ausgelöst, ob der Ziehvorgang abgeschlossen oder abgebrochen wurde. Der dragend Ereignishandler kann den Wert der dropEffect Eigenschaft überprüfen, um festzustellen, ob der Ziehvorgang erfolgreich war oder nicht.

Für weitere Informationen über die Behandlung des Endes eines Ziehvorgangs siehe:

• Abschluss eines Ziehvorgangs

Die HTML Drag-and-Drop-Schnittstellen sind DragEvent, DataTransfer, DataTransferItem, und DataTransferItemList.

Die DragEvent Schnittstelle hat einen Konstruktor und eine dataTransfer Eigenschaft, die ein DataTransfer Objekt ist.

DataTransfer Objekte enthalten den Zustand des Ziehereignisses, wie die Art des Ziehens (wie copy oder move), die Daten des Ziehvorgangs (ein oder mehrere Objekte), und den MIME-Typ jedes Ziehobjekts. DataTransfer Objekte haben auch Methoden, um Elemente zu den Daten des Ziehvorgangs hinzuzufügen oder zu entfernen.

Die Schnittstellen DragEvent und DataTransfer sollten die einzigen sein, die benötigt werden, um HTML Drag-and-Drop-Funktionen zu einer Anwendung hinzuzufügen.

Jedes DataTransfer Objekt enthält eine items Eigenschaft, die eine list von DataTransferItem Objekten ist. Ein DataTransferItem Objekt stellt ein einzelnes Ziehobjekt dar, jedes mit einer kind Eigenschaft (entweder string oder file) und einer type Eigenschaft für den MIME-Typ des Datenobjekts. Das DataTransferItem Objekt hat auch Methoden, um die Daten des Ziehobjekts abzurufen.

Das DataTransferItemList Objekt ist eine Liste der DataTransferItem Objekte. Das Listenobjekt hat Methoden, um ein Ziehobjekt zur Liste hinzuzufügen, ein Ziehobjekt aus der Liste zu entfernen und die Liste von allen Ziehobjekten zu leeren.

Ein wesentlicher Unterschied zwischen den Schnittstellen DataTransfer und DataTransferItem ist, dass erstere die synchrone getData() Methode verwendet, um auf die Daten eines Ziehobjekts zuzugreifen, während letztere die asynchrone getAsString() Methode verwendet.

• Kopieren und Verschieben von Elementen mit der DataTransfer Schnittstelle
• Kopieren und Verschieben von Elementen mit der DataTransferListItem Schnittstelle
• Ziehen und Ablegen von Dateien (nur Firefox): https://jsfiddle.net/9C2EF/
• Ziehen und Ablegen von Dateien (Alle Browser): https://jsbin.com/hiqasek/
• Ein Parkprojekt unter Verwendung der Drag and Drop API: https://park.glitch.me/ (Bearbeitung möglich hier)

• Drag-Vorgänge
• Empfohlene Drag-Typen
• HTML-Living-Standard: Drag and Drop
• Drag and Drop Interoperabilitätsdaten von CanIUse