DataTransferItemList.clear() — Methode · JavaScript-Referenz

Signatur

DataTransferItemList.prototype.clear()

Beschreibung

Die Methode clear() der Schnittstelle DataTransferItemList löscht alle Einträge aus der Liste der Zieh-Daten. Das sind Texte, URLs, HTML-Fragmente und Dateien. Danach ist length gleich 0. Die Liste erreichst du über DataTransfer.items, zum Beispiel über event.dataTransfer.items in einem Drag-and-Drop-Ereignis.

Meistens rufst du clear() im dragstart-Ereignis auf. Dort kannst du Daten entfernen, die der Browser automatisch einträgt, etwa die URL und den HTML-Code eines gezogenen Links oder Bildes. Anschließend setzt du mit items.add() oder setData() nur die Daten, die du selbst übertragen willst. Auch bei eigenen DataTransfer-Objekten, die du mit new DataTransfer() erzeugst, eignet sich clear(), um eine Dateiliste zurückzusetzen, zum Beispiel für input.files.

Wichtig: Die Liste kann nur im Lese-/Schreibmodus verändert werden. Beim Drag-and-Drop gilt dieser Modus nur während dragstart. In dragover, drop und anderen Ereignissen ist das Objekt geschützt. Dort bewirkt clear() nichts, und es wird auch kein Fehler geworfen.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Standard-Daten beim Ziehen eines Links ersetzen

const link = document.querySelector('a.produkt');

link.addEventListener('dragstart', (event) => {
  const items = event.dataTransfer.items;
  console.log('Vorher:', items.length);

  // Automatisch gesetzte URL/HTML-Daten entfernen
  items.clear();
  console.log('Nach clear():', items.length);

  // Nur eigene Nutzdaten übertragen
  items.add(JSON.stringify({ id: 42, name: 'Tastatur' }), 'application/json');
  items.add('Tastatur (#42)', 'text/plain');
});

Vorher: 3 Nach clear(): 0

Dateiliste eines eigenen DataTransfer-Objekts zurücksetzen

const dt = new DataTransfer();
dt.items.add(new File(['Hallo'], 'a.txt', { type: 'text/plain' }));
dt.items.add(new File(['Welt'], 'b.txt', { type: 'text/plain' }));
console.log(dt.items.length, dt.files.length);

dt.items.clear();
console.log(dt.items.length, dt.files.length);

// Leere Liste einem Datei-Input zuweisen
const input = document.querySelector('input[type=file]');
input.files = dt.files;

2 2 0 0

Wirkungslos im geschützten Modus (drop)

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

zone.addEventListener('dragover', (e) => e.preventDefault());
zone.addEventListener('drop', (event) => {
  event.preventDefault();
  const items = event.dataTransfer.items;
  const vorher = items.length;
  items.clear(); // wird ignoriert, kein Fehler
  console.log(vorher === items.length ? 'Liste unverändert' : 'geleert');
});

Liste unverändert

// Wichtig · Fallstricke

Nur in dragstart wirksam: In anderen Drag-Ereignissen ist der Datenspeicher geschützt. Dort ignoriert der Browser clear() ohne Fehlermeldung. Das kann bei der Fehlersuche verwirren.
clear() leert die Liste vollständig, auch DataTransfer.files. Um nur einen Datentyp zu löschen, nimm DataTransfer.clearData(format), für einen einzelnen Eintrag items.remove(index).
Rufst du clear() in dragstart auf und fügst danach keine Daten hinzu, starten manche Browser (vor allem Firefox) den Ziehvorgang nicht. Setze deshalb mindestens einen Eintrag, z. B. text/plain.
Kompatibilität: wird von allen modernen Browsern unterstützt. new DataTransfer() gibt es in Safari erst ab Version 14.1.

Siehe auch

DataTransferItemList DataTransferItemList.add() DataTransferItemList.remove() DataTransfer.clearData() DataTransfer.items new TransformStream()