HTML Drag and Drop API

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

Während der Drag-Operationen werden mehrere Ereignistypen ausgelöst, und einige Ereignisse können viele Male ausgelöst werden, wie beispielsweise die drag und dragover Ereignisse.

Jeder Drag-Ereignistyp hat einen zugeordneten Ereignishandler:

Dieser Abschnitt ist eine Zusammenfassung der grundlegenden Schritte zur Hinzufügung von Drag-and-Drop-Funktionalität zu einer Anwendung.

Identifizieren, was ziehbar ist

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

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

// Get the element by id
const element = document.getElementById("p1");
// Add the ondragstart event listener
element.addEventListener("dragstart", (ev) => {
  // Add the target element's id to the data transfer object
  ev.dataTransfer.setData("text/plain", ev.target.id);
});

Für weitere Informationen siehe:

• Draggable-Attribut-Referenz
• Leitfaden für Drag-Operationen

Definieren der Drag-Daten

Die Anwendung kann eine beliebige Anzahl von Datenobjekten in einem Drag-Vorgang einschließen. Jedes Datenobjekt ist ein String eines bestimmten type — typischerweise ein MIME-Typ wie text/html.

Jedes DragEvent hat eine dataTransfer-Eigenschaft, die die Daten des Ereignisses enthält. Diese Eigenschaft (die ein DataTransfer-Objekt ist) verfügt auch über Methoden, um Drag-Daten zu verwalten. Die setData()-Methode wird verwendet, um ein Element 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 mehr Informationen über Drag-Daten, siehe Drag-Daten.

Definieren des Drag-Bildes

Standardmäßig liefert der Browser ein Bild, das während eines Drag-Vorgangs neben dem Zeiger erscheint. Eine Anwendung kann jedoch mit der setDragImage()-Methode 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 des Ablageeffekts

Die dropEffect-Eigenschaft wird verwendet, um das Feedback zu steuern, das der Benutzer während eines Drag-and-Drop-Vorgangs erhält. Sie beeinflusst in der Regel, welchen Cursor der Browser während des Ziehens anzeigt. Zum Beispiel, wenn der Benutzer über ein Ablageziel schwebt, kann der Cursor des Browsers den Typ der ausgeführten Operation anzeigen.

Drei Effekte können definiert werden:

1. copy zeigt an, dass die gezogenen Daten von ihrem aktuellen Standort zum Ablagestandort kopiert werden.
2. move zeigt an, dass die gezogenen Daten von ihrem aktuellen Standort zum Ablagestandort verschoben werden.
3. link zeigt an, dass eine Art von Beziehung oder Verbindung zwischen der Quelle und den Ablagestandorten erstellt wird.

Während des Drag-Vorgangs können Drag-Effekte modifiziert werden, um anzuzeigen, dass bestimmte Effekte an bestimmten Standorten erlaubt sind.

Das folgende Beispiel zeigt, wie Sie diese Eigenschaft verwenden.

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

Für weitere Details siehe:

• Drag-Effekte

Definieren einer Ablagezone

Standardmäßig verhindert der Browser, dass etwas passiert, wenn etwas auf die meisten HTML-Elemente fallen gelassen wird. Um dieses Verhalten zu ändern, sodass ein Element zu einem Ablagebereich oder ablegbar wird, muss das Element sowohl auf dragover als auch auf drop Ereignisse hören.

Das folgende Beispiel zeigt, wie Sie diese Ereignisse verwenden.

<p id="target">Drop Zone</p>

const target = document.getElementById("target");

target.addEventListener("dragover", (ev) => {
  ev.preventDefault();
  ev.dataTransfer.dropEffect = "move";
});
target.addEventListener("drop", (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));
});

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

Für mehr Informationen siehe:

• Spezifizieren von Ablagezielen

Umgang mit dem Ablageeffekt

Der Handler für das drop-Ereignis ist frei, die Drag-Daten auf eine für die Anwendung spezifische Weise zu verarbeiten.

Typischerweise verwendet eine Anwendung die getData()-Methode, um Drag-Items abzurufen und sie dann entsprechend zu verarbeiten. Außerdem können die Anwendungssemantiken je nach Wert der dropEffect und/oder dem Status der Modifikatortasten unterschiedlich sein.

Das folgende Beispiel zeigt einen Drop-Handler, der die id des Quell-Elements aus den Drag-Daten erhält und dann die id verwendet, um das Quell-Element zum Ablageelement zu verschieben:

<p id="p1" draggable="true">This element is draggable.</p>
<div id="target">Drop Zone</div>

const source = document.getElementById("p1");
const target = document.getElementById("target");

source.addEventListener("dragstart", (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";
});
target.addEventListener("dragover", (ev) => {
  ev.preventDefault();
  ev.dataTransfer.dropEffect = "move";
});
target.addEventListener("drop", (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));
});

Für mehr Informationen siehe:

• Durchführen einer Ablage

Drag-Ende

Am Ende eines Drag-Vorgangs wird das dragend-Ereignis am _Quell-_Element ausgelöst — dem Element, das das Ziel der Drag-Start-Operation war.

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

Für weitere Informationen zum Umgang mit dem Ende eines Drag-Vorgangs siehe:

• Beenden eines Drags

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 Drag-Ereignisses, wie den Typ des durchgeführten Drags (z.B. copy oder move), die Drag-Daten (ein oder mehrere Elemente) und den MIME-Typ jedes Drag-Elements. DataTransfer-Objekte haben auch Methoden, um Elemente zu den Drag-Daten hinzuzufügen oder zu entfernen.

Die DragEvent- und DataTransfer-Schnittstellen 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 Drag-Element dar, jedes mit einer kind-Eigenschaft (entweder string oder file) und einer type-Eigenschaft für den MIME-Typ des Datenelements. Das DataTransferItem-Objekt hat außerdem Methoden, um die Daten des Drag-Elements abzurufen.

Das DataTransferItemList-Objekt ist eine Liste von DataTransferItem-Objekten. Das Listenobjekt hat Methoden, um ein Drag-Element zur Liste hinzuzufügen, ein Drag-Element aus der Liste zu entfernen und die Liste von allen Drag-Elementen zu löschen.

Ein wesentlicher Unterschied zwischen den DataTransfer- und DataTransferItem-Schnittstellen besteht darin, dass die erstere die synchrone getData()-Methode verwendet, um auf die Daten eines Drag-Elements zuzugreifen, während die letztere stattdessen 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 Parkplatzprojekt mit der Drag-and-Drop-API: https://park.glitch.me/ (Hier bearbeiten)

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