DataTransfer.setData() — Methode · JavaScript-Referenz

Signatur

DataTransfer.prototype.setData(format, data)

Beschreibung

setData() speichert einen String unter einem Formatbezeichner (meist ein MIME-Typ wie text/plain, text/html oder text/uri-list) im DataTransfer-Objekt. Gibt es für dieses Format schon Daten, werden sie ersetzt. Ist das Format neu, wird es ans Ende der Liste types angehängt.

Typischerweise rufst du die Methode im dragstart-Handler auf. Dort legst du fest, was beim Loslassen übertragen wird. Im drop-Handler liest du die Werte mit getData() wieder aus. Auch bei den Zwischenablage-Ereignissen copy und cut kannst du über event.clipboardData.setData() eigene Inhalte in die Zwischenablage legen. Dafür musst du dort event.preventDefault() aufrufen.

Du kannst mehrere Formate parallel setzen, zum Beispiel reinen Text und HTML. So wählt jedes Ziel das passende Format: Ein Texteditor nimmt text/plain, eine Rich-Text-Ansicht nimmt text/html. Für Daten innerhalb der eigenen Anwendung eignen sich eigene Formate wie application/x-meine-app+json.

Wichtig: Beschreibbar ist das Objekt nur im Lese-/Schreibmodus, also während dragstart (bzw. copy/cut). In dragover, dragenter oder drop haben Aufrufe keine Wirkung.

Parameter

Name	Typ	Default	Beschreibung
$format Pflicht	string		Formatbezeichner der Daten, meist ein MIME-Typ wie `text/plain`, `text/html` oder `text/uri-list`. Er wird in Kleinbuchstaben umgewandelt. `text` wird als `text/plain` und `url` als `text/uri-list` behandelt.
$data Pflicht	string		Die Daten, die gespeichert werden sollen. Andere Typen werden in einen String umgewandelt. Objekte musst du vorher selbst mit `JSON.stringify()` umwandeln.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Einfaches Ziehen von Text zwischen Elementen

// HTML: <p id="quelle" draggable="true">Zieh mich</p> <div id="ziel">Hier ablegen</div>
const quelle = document.getElementById('quelle');
const ziel = document.getElementById('ziel');

quelle.addEventListener('dragstart', (event) => {
  event.dataTransfer.setData('text/plain', event.target.id);
  event.dataTransfer.effectAllowed = 'move';
});

// dragover muss preventDefault() aufrufen, sonst ist kein drop möglich
ziel.addEventListener('dragover', (event) => event.preventDefault());

ziel.addEventListener('drop', (event) => {
  event.preventDefault();
  const id = event.dataTransfer.getData('text/plain');
  ziel.appendChild(document.getElementById(id));
  console.log(`Element #${id} verschoben`);
});

Element #quelle verschoben

Mehrere Formate und eigene JSON-Daten setzen

const karte = document.querySelector('.produkt-karte');

karte.addEventListener('dragstart', (event) => {
  const produkt = { id: 42, name: 'Tastatur', preis: 49.9 };
  const dt = event.dataTransfer;

  // Formate für externe Ziele
  dt.setData('text/plain', `${produkt.name} – ${produkt.preis} €`);
  dt.setData('text/html', `<strong>${produkt.name}</strong> – ${produkt.preis} €`);
  dt.setData('text/uri-list', `https://shop.example/produkt/${produkt.id}`);

  // Eigenes Format für die eigene App
  dt.setData('application/x-shop-produkt+json', JSON.stringify(produkt));

  console.log([...dt.types]);
});

document.querySelector('.warenkorb').addEventListener('drop', (event) => {
  event.preventDefault();
  const json = event.dataTransfer.getData('application/x-shop-produkt+json');
  if (json) console.log('In den Warenkorb:', JSON.parse(json).name);
});

["text/plain", "text/html", "text/uri-list", "application/x-shop-produkt+json"] In den Warenkorb: Tastatur

Kopierten Text in der Zwischenablage anpassen

// Beim Kopieren automatisch eine Quellenangabe anhängen
document.addEventListener('copy', (event) => {
  const auswahl = document.getSelection().toString();
  if (!auswahl) return;

  event.clipboardData.setData('text/plain', `${auswahl}\n\nQuelle: ${location.href}`);
  event.preventDefault(); // Ohne diesen Aufruf wird die Standard-Kopie verwendet
});

// Wichtig · Fallstricke

Nur in dragstart beschreibbar: In dragenter, dragover, dragleave und drop ist das DataTransfer-Objekt geschützt oder nur lesbar. Aufrufe von setData() werden dort ohne Fehlermeldung ignoriert.
Daten in dragover nicht lesbar: Aus Sicherheitsgründen liefert getData() erst im drop einen Inhalt. Vorher kannst du nur über dataTransfer.types prüfen, welche Formate vorhanden sind. Wenn du Informationen im Formatnamen kodierst, denk daran, dass er in Kleinbuchstaben umgewandelt wird.
Nur Strings: Objekte musst du mit JSON.stringify() umwandeln. Dateien fügst du über dataTransfer.items.add(file) hinzu, nicht über setData().
Sicherheit: Gezogene oder eingefügte Daten können aus fremden Quellen stammen, zum Beispiel aus anderen Fenstern oder Anwendungen. Füge text/html aus dem drop niemals ungeprüft per innerHTML ein, sonst droht XSS. Verwende textContent oder bereinige den Inhalt vorher, etwa mit DOMPurify. Ebenso solltest du im dragstart keine vertraulichen Daten ablegen, denn jedes Ablageziel kann sie lesen.
Kompatibilität: Alle modernen Browser unterstützen die Methode. Ältere Versionen des Internet Explorers kannten nur "text" und "url". Firefox startet das Ziehen teilweise nur, wenn im dragstart mindestens ein Format gesetzt wurde. Auf Touch-Geräten wird natives HTML-Drag-and-Drop nur eingeschränkt unterstützt, auf iOS zum Beispiel erst ab Safari 15.

Siehe auch

DataTransfer.getData() DataTransfer.clearData() DataTransfer.setDragImage() DataTransfer.addElement() DataTransferItemList.add()