new DragEvent() — Methode · JavaScript-Referenz

Signatur

new DragEvent(type, options)

Beschreibung

Der Konstruktor new DragEvent() legt ein neues DragEvent an. Diese Schnittstelle erbt von MouseEvent und hat zusätzlich die Eigenschaft dataTransfer, in der die gezogenen Daten stehen. Normalerweise erzeugt der Browser solche Events selbst, wenn jemand etwas mit der Maus zieht (dragstart, dragover, drop usw.). Mit dem Konstruktor kann man sie auch selbst erzeugen.

Das braucht man vor allem für automatisierte Tests von Drag-and-Drop-Oberflächen, zum Beispiel sortierbare Listen, Kanban-Boards oder Upload-Bereiche. Auch wenn ein Nutzer ohne Maus arbeitet, etwa per Tastatur, kann man so dieselben Handler aufrufen. Erst durch element.dispatchEvent(event) wird das Event an ein Element geschickt.

Man kann alle Optionen von MouseEvent mitgeben (clientX, button, shiftKey …) und zusätzlich ein eigenes DataTransfer-Objekt. Selbst erzeugte Events haben immer isTrusted === false. Deshalb lösen sie keine eingebauten Browser-Aktionen aus: Es gibt keinen echten Drag-Vorgang und keinen Zugriff auf Dateien des Systems.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events, z. B. `"dragstart"`, `"drag"`, `"dragenter"`, `"dragover"`, `"dragleave"`, `"drop"` oder `"dragend"`. Groß- und Kleinschreibung zählt.
$options	DragEventInit	{}	Optionales Objekt mit allen Feldern von `MouseEventInit` (u. a. `bubbles`, `cancelable`, `composed`, `clientX`, `clientY`, `button`, `ctrlKey`, `shiftKey`, `relatedTarget`) und zusätzlich `dataTransfer`.
$options.dataTransfer	DataTransfer \| null	null	Das `DataTransfer`-Objekt, das später über `event.dataTransfer` abrufbar ist. Ohne diese Angabe ist `dataTransfer` gleich `null`.
$options.bubbles	boolean	false	Gibt an, ob das Event im DOM nach oben weitergereicht wird. Das ist wichtig bei Event-Delegation.
$options.cancelable	boolean	false	Gibt an, ob `preventDefault()` wirkt. Das braucht man z. B. bei `dragover` und `drop`.

Rückgabewert

Typ

DragEvent

Beschreibung

Ein neues, noch nicht ausgelöstes DragEvent-Objekt mit isTrusted === false.

Beispiele

Einfaches DragEvent erzeugen und auslösen

const box = document.createElement('div');
document.body.append(box);

box.addEventListener('dragstart', (event) => {
  console.log(event.type, event instanceof MouseEvent, event.isTrusted);
});

const event = new DragEvent('dragstart', { bubbles: true, cancelable: true });
box.dispatchEvent(event);

dragstart true false

Drop mit eigenem DataTransfer simulieren (z. B. im Test)

const dropZone = document.createElement('div');
document.body.append(dropZone);

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();
  const id = event.dataTransfer.getData('text/plain');
  console.log(`Element ${id} wurde abgelegt`);
});

const dt = new DataTransfer();
dt.setData('text/plain', 'task-42');

const dropEvent = new DragEvent('drop', {
  bubbles: true,
  cancelable: true,
  dataTransfer: dt,
  clientX: 120,
  clientY: 80
});

const notCanceled = dropZone.dispatchEvent(dropEvent);
console.log('Standardaktion ausgeführt:', notCanceled);

Element task-42 wurde abgelegt Standardaktion ausgeführt: false

Datei-Upload per Drop testen

const uploadZone = document.querySelector('#upload') ?? document.body;

uploadZone.addEventListener('drop', (event) => {
  event.preventDefault();
  for (const file of event.dataTransfer.files) {
    console.log(file.name, file.type, file.size);
  }
});

const dt = new DataTransfer();
dt.items.add(new File(['Hallo Welt'], 'notiz.txt', { type: 'text/plain' }));

uploadZone.dispatchEvent(new DragEvent('drop', {
  bubbles: true,
  cancelable: true,
  dataTransfer: dt
}));

notiz.txt text/plain 10

Kompletten Drag-Ablauf in einem Test nachbilden

const fireDrag = (target, type, dataTransfer) =>
  target.dispatchEvent(new DragEvent(type, {
    bubbles: true,
    cancelable: true,
    dataTransfer
  }));

const source = document.createElement('li');
const target = document.createElement('ul');
source.draggable = true;
document.body.append(source, target);

source.addEventListener('dragstart', (e) => e.dataTransfer.setData('text/plain', 'item-1'));
target.addEventListener('dragover', (e) => e.preventDefault());
target.addEventListener('drop', (e) => console.log('Empfangen:', e.dataTransfer.getData('text/plain')));

const dt = new DataTransfer();
fireDrag(source, 'dragstart', dt);
fireDrag(target, 'dragenter', dt);
fireDrag(target, 'dragover', dt);
fireDrag(target, 'drop', dt);
fireDrag(source, 'dragend', dt);

Empfangen: item-1

// Wichtig · Fallstricke

Keine echte Browser-Aktion: Selbst erzeugte Events haben isTrusted === false. Der Browser startet damit keinen echten Drag-Vorgang, zeigt kein Vorschaubild beim Ziehen und öffnet keine Dateien.
Standardwerte beachten: bubbles und cancelable sind standardmäßig false. Wenn Handler über Event-Delegation arbeiten oder preventDefault() nutzen, muss man beide ausdrücklich auf true setzen.
dataTransfer ist sonst null: Ohne die Option dataTransfer führen Handler, die event.dataTransfer.getData() aufrufen, zu einem TypeError.
Nur ein Drag-Ablauf: Ein einmal erzeugtes DataTransfer sollte man für alle Events eines Ablaufs wiederverwenden (von dragstart bis dragend), damit gesetzte Daten erhalten bleiben.
Kompatibilität: new DataTransfer() gibt es in Safari erst ab Version 14.1. Ältere Browser und manche Testumgebungen unterstützen ihn gar nicht, z. B. jsdom: Dort fehlen DragEvent und DataTransfer oft ganz und müssen nachgerüstet werden (Polyfill), oder man testet in einem echten Browser (Playwright, Puppeteer).
Auf Touch-Geräten löst natives Ziehen je nach Browser keine DragEvents aus. Für mobile Geräte sollte man zusätzlich Pointer-Events nutzen.

Siehe auch

new SnapEvent() new TrackEvent() new BlobEvent() new ErrorEvent() new Event()