Signatur
Beschreibung
Die Methode addElement() des DataTransfer-Objekts gibt es nur in Firefox und sie gehört nicht zum Standard. Mit ihr legt man fest, welches Element als Quelle einer Drag-Operation gilt. Normalerweise ist das der Knoten, auf dem dragstart ausgelöst wurde. Nach dem Aufruf von addElement() erhält stattdessen das übergebene Element die folgenden Events drag und dragend.
Nützlich ist das, wenn ein kleines Bedienelement das Ziehen startet (etwa ein „Griff“-Symbol), die Logik für Fortschritt und Abschluss aber zu einem übergeordneten Element gehört, zum Beispiel zu einer ganzen Karte oder Listenzeile. Aufrufen darf man die Methode nur im dragstart-Handler, denn nur dort ist das DataTransfer-Objekt beschreibbar.
Für plattformübergreifenden Code sollte man addElement() nicht verwenden. Dasselbe Ziel erreicht man mit Event-Delegation: Die Listener für drag und dragend hängen am Elternelement, weil diese Events ohnehin nach oben weitergereicht werden. Das Vorschaubild beim Ziehen steuert man mit setDragImage().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $element Pflicht | Element | Das Element, das ab jetzt als Quelle der Drag-Operation gilt und die Events drag und dragend erhält. |
Rückgabewert
undefined).Beispiele
Griff-Symbol startet das Ziehen, die Karte gilt als Quelle
// HTML: <div class="card"><span class="handle" draggable="true">⠿</span> Aufgabe</div>
const handle = document.querySelector('.handle');
const card = handle.closest('.card');
handle.addEventListener('dragstart', (event) => {
event.dataTransfer.setData('text/plain', 'aufgabe-42');
// Nur in Firefox vorhanden: auf Verfügbarkeit prüfen
if (typeof event.dataTransfer.addElement === 'function') {
event.dataTransfer.addElement(card);
}
});
card.addEventListener('dragend', (event) => {
console.log('dragend auf:', event.currentTarget.className);
});Browserübergreifende Alternative mit Event-Delegation
// Ohne addElement: drag und dragend werden nach oben weitergereicht,
// deshalb reicht ein Listener auf dem Elternelement.
const list = document.querySelector('#aufgaben');
list.addEventListener('dragstart', (event) => {
const item = event.target.closest('li');
if (!item) return;
event.dataTransfer.setData('text/plain', item.dataset.id);
event.dataTransfer.setDragImage(item, 10, 10); // ganze Zeile als Vorschau
item.classList.add('wird-gezogen');
});
list.addEventListener('dragend', (event) => {
event.target.closest('li')?.classList.remove('wird-gezogen');
console.log('Ziehen beendet');
});Verfügbarkeit prüfen
document.addEventListener('dragstart', (event) => {
const supported = 'addElement' in event.dataTransfer;
console.log(`addElement verfügbar: ${supported}`);
});// Wichtig · Fallstricke
- Nicht standardisiert: Die Methode kommt weder in der HTML-Spezifikation noch in Chrome, Edge oder Safari vor. In aktuellen Firefox-Versionen steht sie normalen Webseiten unter Umständen gar nicht zur Verfügung, sondern nur privilegiertem Browser-Code. Deshalb vor jedem Aufruf mit
typeof dt.addElement === 'function'prüfen. - Nur im
dragstart-Handler aufrufen. Später ist dasDataTransfer-Objekt schreibgeschützt oder geschützt, und ein Aufruf bleibt wirkungslos oder löst einen Fehler aus. addElement()ändert nicht das Vorschaubild beim Ziehen. Dafür istsetDragImage()zuständig.- Für Produktionscode Event-Delegation auf einem gemeinsamen Elternelement verwenden. Das funktioniert in allen Browsern (Baseline).