dataTransfer-Objekt

Das dataTransfer-Objekt ist an jedes Drag-Ereignis angehängt und der einzige Kommunikationskanal zwischen Quelle und Ziel. Es überträgt Nutzdaten, Dateilisten, erlaubte Effekte und den ausgewählten Drop-Effekt.

Die Quelle schreibt typisierte Nutzdaten mit e.dataTransfer.setData(format, value). Das Ziel liest sie mit e.dataTransfer.getData(format). Beide Argumente sind Zeichenfolgen; Werte werden vor dem Speichern in Zeichenfolgen umgewandelt.

Wenn dieselbe Nutzlast unter mehreren Typen gespeichert wird, ist ein Drag-Vorgang interoperabel: "text/plain" funktioniert in jedem Texteditor, "text/uri-list" wird von Browsern als URL erkannt und "text/html" bewahrt die Formatierung in Textverarbeitungsprogrammen. Das Ziel wählt den Typ, den es versteht.

Aus Datenschutzgründen stellt der Browser dragenter- und dragover-Handlern über e.dataTransfer.types nur die Liste der Typen zur Verfügung, nicht deren Werte. Die eigentlichen Daten können nur innerhalb des drop-Ereignisses eines akzeptierenden Ziels gelesen werden.

Wenn der Benutzer vom Desktop zieht, ist e.dataTransfer.files eine FileList aus File-Objekten. Bei Drag-Vorgängen, die innerhalb der Seite beginnen, ist sie leer. Betrachten Sie sie als den maßgeblichen Weg, um einen externen Datei-Drop zu erkennen und auf Größe, Namen und Typ zuzugreifen.

e.dataTransfer.items stellt sowohl Zeichenfolgen als auch Dateien als DataTransferItem-Objekte bereit. Jedes Element besitzt kind ("string" oder "file"), type (MIME) und getAsString(cb) / getAsFile(). items ist die moderne, typbewusste Alternative zu files und getData.

effectAllowed wird von der Quelle in dragstart gesetzt und listet die von der Quelle unterstützten Vorgänge auf. dropEffect wird vom Ziel in dragover gesetzt und wählt einen dieser Vorgänge aus. Der Browser bricht den Drop ab, wenn die beiden Werte nicht übereinstimmen.

e.dataTransfer.setDragImage(node, x, y) ersetzt das standardmäßige Geisterbild. Übergeben Sie ein nach Ihren Vorstellungen formatiertes, außerhalb des sichtbaren Bereichs liegendes DOM-Element sowie den Versatz des Cursors relativ zu diesem Element. Die Änderung gilt nur für den aktuellen Drag-Vorgang.

e.dataTransfer.clearData() löscht alle Formate; clearData("text/plain") entfernt ein einzelnes Format. Das ist selten nötig, da dataTransfer für jeden Drag-Vorgang neu erstellt wird, aber nützlich, wenn Sie zunächst Daten eintragen und den Vorgang dann abbrechen möchten.

Dateien, die von einer Seite auf Origin A auf eine Seite auf Origin B gezogen werden, werden weiterhin übermittelt – die API funktioniert über Origins hinweg. Die empfangende Seite sieht jedoch nur, was die Quelle ausdrücklich in dataTransfer abgelegt hat; ein beliebiger Zugriff auf das DOM wird nicht gewährt.

Durch das Schreiben des Typs "DownloadURL" (setData("DownloadURL", "image/png:filename.png:https://...")) kann eine Seite dem Benutzer ermöglichen, eine Datei aus dem Browser auf den Desktop zu ziehen. Die Browserunterstützung ist eingeschränkt (Chromium-basierte Browser); prüfen Sie daher die Unterstützung und bieten Sie einen geeigneten Fallback an.

Warum darf dataTransfer.getData() während des dragover-Ereignisses nicht den tatsächlich gespeicherten Wert zurückgeben?

dataTransfer ist die Verbindung zwischen Ziehquelle und Ablageziel. Verwenden Sie setData/getData für typisierte String-Nutzdaten, items für eine einheitliche Ansicht von Dateien und Strings, files für Ablagen vom Desktop, setDragImage für benutzerdefinierte Vorschauen und effectAllowed/dropEffect, um die Operation auszuhandeln.