DataTransfer.setDragImage() — Methode · JavaScript-Referenz

Signatur

DataTransfer.prototype.setDragImage(imgElement, xOffset, yOffset)

Beschreibung

Mit setDragImage() ersetzen Sie das Standard-Vorschaubild, das der Browser beim Ziehen erzeugt. Normalerweise ist das eine halbtransparente Kopie des gezogenen Elements. Mit der Methode können Sie stattdessen ein Symbol, eine Miniaturansicht oder ein eigens gestaltetes DOM-Element anzeigen, zum Beispiel „3 Dateien“ beim Ziehen mehrerer Einträge.

Aufrufen müssen Sie die Methode im dragstart-Handler, und zwar auf event.dataTransfer. In späteren Events wie drag oder dragover hat der Aufruf keine Wirkung, weil der Datenspeicher dann nur noch gelesen werden kann (geschützter Modus).

Als Bildquelle eignet sich ein HTMLImageElement, ein HTMLCanvasElement oder ein beliebiges anderes Element. Handelt es sich nicht um ein Bild, erstellt der Browser eine Art Momentaufnahme des Elements, so wie es gerade dargestellt wird. Deshalb muss das Element im Dokument vorhanden und gerendert sein. Es darf aber außerhalb des sichtbaren Bereichs liegen.

Die beiden Versatzwerte legen fest, an welcher Stelle im Bild der Mauszeiger „greift“. Sie werden in CSS-Pixeln relativ zur linken oberen Ecke des Bildes angegeben.

Parameter

Name	Typ	Beschreibung
$imgElement Pflicht	Element (HTMLImageElement \| HTMLCanvasElement \| beliebiges Element)	Das Element, das als Drag-Bild dient. Bei `<img>` wird das Bild verwendet, bei anderen Elementen eine gerenderte Momentaufnahme.
$xOffset Pflicht	number	Waagerechter Versatz des Mauszeigers innerhalb des Bildes in Pixeln, gemessen vom linken Rand.
$yOffset Pflicht	number	Senkrechter Versatz des Mauszeigers innerhalb des Bildes in Pixeln, gemessen vom oberen Rand.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Vorab geladenes Bild als Drag-Symbol

// Bild vorab laden, damit es beim dragstart sicher bereitsteht
const dragIcon = new Image();
dragIcon.src = '/icons/datei-64.png';

const item = document.querySelector('#datei');
item.draggable = true;

item.addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('text/plain', item.dataset.id);
  event.dataTransfer.effectAllowed = 'move';
  // Mauszeiger in die Mitte des 64×64-Symbols setzen
  event.dataTransfer.setDragImage(dragIcon, 32, 32);
});

Eigenes DOM-Element als Vorschau („3 Elemente“)

const list = document.querySelector('#liste');

list.addEventListener('dragstart', (event) => {
  const selected = list.querySelectorAll('.ausgewaehlt');

  // Vorschau-Element erzeugen und außerhalb des sichtbaren Bereichs rendern
  const ghost = document.createElement('div');
  ghost.textContent = `${selected.length} Elemente`;
  Object.assign(ghost.style, {
    position: 'absolute',
    top: '-1000px',
    padding: '6px 12px',
    background: '#2563eb',
    color: '#fff',
    borderRadius: '6px'
  });
  document.body.append(ghost);

  event.dataTransfer.setData('text/plain', [...selected].map((el) => el.id).join(','));
  event.dataTransfer.setDragImage(ghost, 10, 10);

  // Erst nach dem Snapshot wieder entfernen
  requestAnimationFrame(() => ghost.remove());
});

Canvas-Bild dynamisch zeichnen

const canvas = document.createElement('canvas');
canvas.width = 80;
canvas.height = 30;
const ctx = canvas.getContext('2d');
ctx.fillStyle = '#16a34a';
ctx.fillRect(0, 0, 80, 30);
ctx.fillStyle = '#fff';
ctx.font = '14px sans-serif';
ctx.fillText('Kopieren', 10, 20);

document.querySelector('#karte').addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('text/plain', 'karte-42');
  event.dataTransfer.setDragImage(canvas, 0, 0);
});

Standard-Vorschau ausblenden (transparentes Bild)

// 1×1 transparentes GIF, z. B. für eine eigene, per JS gesteuerte Vorschau
const empty = new Image();
empty.src = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';

document.querySelector('#slider-griff').addEventListener('dragstart', (event) => {
  event.dataTransfer.setDragImage(empty, 0, 0);
});

// Wichtig · Fallstricke

Nur in dragstart wirksam: In späteren Drag-Events ignoriert der Browser den Aufruf.
Bild muss geladen sein: Ein Image, das erst im Handler erzeugt wird, ist meist noch nicht geladen. Dann erscheint gar kein Bild oder die Standardvorschau. Laden Sie Bilder deshalb vorab.
DOM-Elemente müssen gerendert sein: Elemente mit display: none oder ohne Einbindung ins Dokument liefern ein leeres Bild. Verschieben Sie sie lieber mit position: absolute; top: -1000px aus dem sichtbaren Bereich und entfernen Sie sie erst nach dem Snapshot, etwa per requestAnimationFrame oder setTimeout.
Browserunterschiede: Safari und Chrome stellen Transparenz, Schatten und Größenlimits unterschiedlich dar. Sehr große Bilder werden teils ausgeblendet oder beschnitten. Unter Windows zeigen manche Browser das Bild halbtransparent an.
Touch-Geräte: Natives HTML5-Drag-and-Drop wird auf Mobilgeräten nur eingeschränkt unterstützt (iOS erst ab Safari 15). Für einheitliches Verhalten sind oft Pointer-Events oder eine Bibliothek nötig.
Bilder von fremden Domains funktionieren meist. Canvas-Inhalte mit Cross-Origin-Bildern ohne CORS können aber „verunreinigt“ (tainted) sein. Das stört die Anzeige hier meist nicht, verhindert jedoch das spätere Auslesen des Canvas.

Siehe auch

DataTransfer DataTransfer.setData() DataTransfer.effectAllowed DragEvent HTMLElement.draggable DataTransfer.addElement()