DataTransfer: setDragImage() Methode

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since October 2018.

Wenn ein Drag-Vorgang stattfindet, wird ein halbtransparentes Bild vom Drag-Ziel (dem Element, bei dem das dragstart-Ereignis ausgelöst wird) erstellt und folgt während des Drag-Vorgangs dem Mauszeiger. Dieses Bild wird automatisch erstellt, sodass Sie es nicht selbst erstellen müssen. Wenn jedoch ein benutzerdefiniertes Bild gewünscht wird, kann die DataTransfer.setDragImage()-Methode verwendet werden, um das benutzerdefinierte Bild festzulegen. Das Bild ist in der Regel ein <img>-Element, es kann aber auch ein <canvas> oder ein anderes sichtbares Element sein.

Die x- und y-Koordinaten der Methode definieren, wie das Bild relativ zum Mauszeiger erscheinen soll. Diese Koordinaten definieren den Versatz in das Bild, wo sich der Mauszeiger befinden soll. Um beispielsweise das Bild so anzuzeigen, dass der Zeiger in der Mitte ist, verwenden Sie Werte, die die halbe Breite und Höhe des Bildes sind.

Diese Methode muss im dragstart-Ereignishandler aufgerufen werden.

Syntax

setDragImage(imgElement, xOffset, yOffset)

Parameter

imgElement

Ein Bild-Element-Element, das als Drag-Feedback-Bild verwendet werden soll.

Wenn Element ein img-Element ist, setzen Sie den Drag-Datenspeicher-Bitmap auf das Bild des Elements (in seiner intrinsischen Größe); andernfalls setzen Sie den Drag-Datenspeicher-Bitmap auf ein aus dem gegebenen Element generiertes Bild (der genaue Mechanismus dafür ist derzeit nicht spezifiziert).

Hinweis: Wenn das Element ein bestehendes HTMLElement ist, muss es im Viewport sichtbar sein, um als Drag-Feedback-Bild angezeigt zu werden. Alternativ können Sie ein neues DOM-Element erstellen, das speziell für diesen Zweck außerhalb des Bildschirms liegt.

xOffset

Ein long, der den horizontalen Versatz innerhalb des Bildes angibt.

yOffset

Ein long, der den vertikalen Versatz innerhalb des Bildes angibt.

Rückgabewert

Keiner (undefined).

Beispiele

Dieses Beispiel zeigt, wie die setDragImage()-Methode verwendet wird. Beachten Sie, dass sich das Beispiel auf eine Bilddatei namens example.gif bezieht. Wenn diese Datei vorhanden ist, wird sie als Drag-Bild verwendet, und wenn diese Datei nicht vorhanden ist, verwendet der Browser sein Standard-Drag-Bild.

demo

html

<div>
  <p id="source" draggable="true">
    Select this element, drag it to the Drop Zone and then release the selection
    to move the element.
  </p>
</div>
<div id="target">Drop Zone</div>

css

div {
  margin: 0em;
  padding: 2em;
}
#source {
  color: blue;
  border: 1px solid black;
}
#target {
  border: 1px solid black;
}

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

source.addEventListener("dragstart", (ev) => {
  console.log("dragStart");
  // Set the drag's format and data. Use the event target's id for the data
  ev.dataTransfer.setData("text/plain", ev.target.id);
  // Create an image and use it for the drag image
  // NOTE: change "example.gif" to an existing image or the image will not
  // be created and the default drag image will be used.
  const img = new Image();
  img.src = "example.gif";
  ev.dataTransfer.setDragImage(img, 10, 10);
});

target.addEventListener("dragover", (ev) => {
  console.log("dragOver");
  ev.preventDefault();
});

target.addEventListener("drop", (ev) => {
  console.log("Drop");
  ev.preventDefault();
  // Get the data, which is the id of the drop target
  const data = ev.dataTransfer.getData("text");
  ev.target.appendChild(document.getElementById(data));
});

Spezifikationen

Specification
HTML # dom-datatransfer-setdragimage-dev