HTMLElement: dragenter — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("dragenter", handler)

Beschreibung

Das dragenter-Ereignis gehört zur HTML Drag and Drop API. Es wird am potenziellen Ablageziel ausgelöst, sobald der Mauszeiger mit einem gezogenen Element, einer Datei oder einer Textauswahl dessen Bereich betritt. Registrieren lässt es sich per addEventListener("dragenter", handler) oder über die Eigenschaft ondragenter. Der Handler erhält ein DragEvent mit der Eigenschaft dataTransfer.

Typischerweise nutzt man dragenter, um dem Nutzer optisches Feedback zu geben, z. B. eine Ablagezone hervorzuheben. Als Gegenstück setzt man die Hervorhebung in dragleave oder drop wieder zurück.

Wichtig: Ein Element gilt nur dann als gültiges Ablageziel, wenn in dragenter und dragover die Standardaktion mit event.preventDefault() unterdrückt wird. Sonst lehnt der Browser das Ablegen ab und drop wird nie ausgelöst. Das Ereignis steigt im DOM auf (bubbles) und ist abbrechbar (cancelable).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"dragenter"`.
$handler Pflicht	(event: DragEvent) => void		Callback, das ein `DragEvent` erhält. Wichtige Eigenschaften sind `event.dataTransfer` (Typen, `dropEffect`), `event.target` (betretenes Element) und `event.relatedTarget` (vorher verlassenes Element).
$options	boolean \| AddEventListenerOptions	false	Optional: `capture`, `once`, `passive`, `signal`. Kein `passive: true` verwenden, wenn `preventDefault()` nötig ist.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Ruft der Handler preventDefault() auf, wird das Element als Ablageziel akzeptiert.

Beispiele

Ablagezone beim Betreten hervorheben

const zone = document.querySelector('#dropzone');

zone.addEventListener('dragenter', (event) => {
  event.preventDefault(); // Ablegen erlauben
  zone.classList.add('aktiv');
  console.log('Zone betreten:', event.target.id);
});

zone.addEventListener('dragover', (event) => {
  event.preventDefault(); // ebenfalls nötig, sonst kein drop
});

zone.addEventListener('dragleave', () => zone.classList.remove('aktiv'));

zone.addEventListener('drop', (event) => {
  event.preventDefault();
  zone.classList.remove('aktiv');
  console.log('Abgelegt:', event.dataTransfer.getData('text/plain'));
});

Zone betreten: dropzone Abgelegt: Hallo Welt

Flackern bei Kindelementen per Zähler vermeiden

const zone = document.querySelector('#dropzone');
let tiefe = 0;

zone.addEventListener('dragenter', (event) => {
  event.preventDefault();
  tiefe++;
  zone.classList.add('aktiv');
});

zone.addEventListener('dragleave', () => {
  tiefe--;
  if (tiefe === 0) zone.classList.remove('aktiv');
});

zone.addEventListener('dragover', (e) => e.preventDefault());
zone.addEventListener('drop', (e) => {
  e.preventDefault();
  tiefe = 0;
  zone.classList.remove('aktiv');
});

Nur Dateien akzeptieren – mit ondragenter

const upload = document.querySelector('#upload');

upload.ondragenter = (event) => {
  const istDatei = event.dataTransfer.types.includes('Files');
  if (istDatei) {
    event.preventDefault();
    event.dataTransfer.dropEffect = 'copy';
    upload.textContent = 'Datei hier ablegen …';
  } else {
    upload.textContent = 'Nur Dateien erlaubt';
  }
};

// Handler wieder entfernen
// upload.ondragenter = null;

// Wichtig · Fallstricke

Kein drop ohne preventDefault: Sowohl in dragenter als auch in dragover muss preventDefault() aufgerufen werden, sonst wird drop nicht ausgelöst.
Flackern durch Kindelemente: Betritt der Zeiger ein Kindelement, feuert erst dragenter am Kind und dann dragleave am Elternelement. Abhilfe schaffen ein Zähler, eine Prüfung von event.relatedTarget oder pointer-events: none auf den Kindelementen.
Daten nicht lesbar: Aus Sicherheitsgründen liefert dataTransfer.getData() während dragenter nur leere Werte (geschützter Modus). Lesbar ist nur dataTransfer.types, der eigentliche Inhalt erst in drop.
Touch-Geräte: Auf Mobilgeräten wird die native Drag-and-Drop-API nur eingeschränkt unterstützt (iOS Safari ab 15 teilweise). Für Touch-Bedienung sind oft Pointer Events oder Bibliotheken nötig.
Außer auf HTMLElement ist das Ereignis auch auf Document, Window und SVGElement verfügbar.

Siehe auch

HTMLElement: dragend HTMLElement: dragover HTMLElement: dragleave HTMLElement: dragstart HTMLElement: drag