HTML Drag and Drop API

HTML Drag-and-Drop verwendet das DOM-Event-Modell und drag events, die von mouse events erben. Eine typische Ziehoperation beginnt, wenn ein Benutzer ein draggable Element auswählt, geht weiter, wenn der Benutzer das Element zu einem droppable Element zieht, und endet, wenn der Benutzer das gezogene Element loslässt.

Während Ziehoperationen werden verschiedene Ereignistypen ausgelöst, und einige Ereignisse können viele Male auftreten, wie z.B. die drag und dragover Ereignisse.

Jeder Drag-Ereignistyp hat einen zugehörigen Ereignis-Handler:

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

Ermitteln, was ziehbar ist

Damit ein Element draggable wird, muss das draggable-Attribut und der dragstart Ereignis-Handler 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:

• Referenz zum Draggable-Attribut
• Leitfaden zu Ziehoperationen

Definieren Sie die Daten des Ziehens

Die Anwendung kann beliebig viele Datenobjekte in eine Ziehoperation einbeziehen. Jedes Datenobjekt ist eine Zeichenkette 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) hat auch Methoden, um die Ziehdaten zu verwalten. Die setData() Methode wird verwendet, um ein Element zu den Ziehdaten 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 häufig verwendeten Datentypen in Drag-and-Drop (wie Text, HTML, Links und Dateien) siehe Empfohlene Zieh-Typen.
• Für weitere Informationen über Ziehdaten siehe Ziehdaten.

Definieren Sie das Ziehbild

Standardmäßig liefert der Browser ein Bild, das während einer Ziehoperation neben dem Zeiger erscheint. Eine Anwendung kann jedoch ein benutzerdefiniertes Bild mit der setDragImage() Methode 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 Bilder zum Zieh-Feedback in:

• Festlegen des Drag-Feedback-Bildes

Definieren Sie den Drop-Effekt

Die dropEffect Eigenschaft wird verwendet, um die Rückmeldung zu steuern, die der Benutzer während einer Drag-and-Drop-Operation erhält. Sie beeinflusst typischerweise, welchen Cursor der Browser beim Ziehen anzeigt. Beispielsweise kann der Cursor des Browsers beim Überfahren eines Zieh-Ziels den Typ der Operation anzeigen, die stattfinden wird.

Drei Effekte können definiert werden:

1. copy zeigt an, dass die gezogenen Daten von ihrem aktuellen Standort zum Abwurf-Zielort kopiert werden.
2. move zeigt an, dass die gezogenen Daten von ihrem aktuellen Standort zum Abwurf-Zielort verschoben werden.
3. link zeigt an, dass eine Form von Beziehung oder Verbindung zwischen der Quelle und den Abwurf-Zielen hergestellt wird.

Während der Ziehoperation können Zieh-Effekte modifiziert werden, um anzuzeigen, dass bestimmte Effekte an bestimmten Orten 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 Sie eine 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, so dass ein Element zu einer Drop-Zone oder droppable wird, muss das Element sowohl auf dragover als auch auf drop Ereignisse hören.

Das folgende Beispiel zeigt, wie diese Attribute verwendet werden und enthält grundlegende Ereignis-Handler 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 Zeiger-Ereignisse).

Für weitere Informationen siehe:

• Spezifizieren von Drop-Zielen

Behandeln des Drop-Effekts

Der Handler für das drop Ereignis ist frei, die Ziehdaten auf eine anwendungsspezifische Weise zu verarbeiten.

Typischerweise verwendet eine Anwendung die getData() Methode, um Ziehobjekte zu erfassen und sie dann entsprechend zu verarbeiten. Zusätzlich können sich die Semantiken der Anwendung je nach dem Wert der dropEffect und/oder dem Zustand der Modifikatortasten unterscheiden.

Das folgende Beispiel zeigt, wie ein Drop-Handler die id des Quell-Elements aus den Ziehdaten ermittelt und dann diese id verwendet, um das Quell-Element zum Drop-Element zu bewegen:

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

• Durchführen eines Drops

Drag-Ende

Am Ende einer Ziehoperation wird das dragend Ereignis auf dem Quell-Element ausgelöst — dem Element, das das Ziel des Ziehbeginns war.

Dieses Ereignis wird unabhängig davon ausgelöst, ob das Ziehen abgeschlossen oder abgebrochen wurde. Der dragend Ereignis-Handler kann den Wert der dropEffect Eigenschaft überprüfen, um zu bestimmen, ob die Ziehoperation erfolgreich war oder nicht.

Für weitere Informationen über die Behandlung des Endes einer Ziehoperation siehe:

• Beenden eines Ziehens

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 umfassen den Zustand des Zieh-Ereignisses, wie die Art des durchgeführten Ziehens (wie copy oder move), die Ziehdaten (eines oder mehrere Elemente) und den MIME-Typ jedes Zieh-Elements. DataTransfer Objekte haben auch Methoden, um Elemente zu den Ziehdaten hinzuzufügen oder zu entfernen.

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

Jedes DataTransfer Objekt enthält eine items Eigenschaft, die eine list von DataTransferItem Objekten ist. Ein DataTransferItem Objekt repräsentiert ein einzelnes Zieh-Element, jeweils 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 Zieh-Elements zu erfassen.

Das DataTransferItemList Objekt ist eine Liste von DataTransferItem Objekten. Das Listenobjekt hat Methoden, um ein Zieh-Element zur Liste hinzuzufügen, ein Zieh-Element aus der Liste zu entfernen und die Liste aller Zieh-Elemente zu leeren.

Ein wesentlicher Unterschied zwischen den Schnittstellen DataTransfer und DataTransferItem besteht darin, dass erstere die synchrone getData() Methode verwendet, um auf die Daten eines Zieh-Elements zuzugreifen, während 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
• Dateien ziehen und ablegen (nur Firefox): https://jsfiddle.net/9C2EF/
• Dateien ziehen und ablegen (Alle Browser): https://jsbin.com/hiqasek/
• Ein Parkprojekt unter Verwendung der Drag and Drop API: https://park.glitch.me/ (Sie können hier bearbeiten)

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