DataTransferItemList.remove() — Methode · JavaScript-Referenz

Signatur

DataTransferItemList.prototype.remove(index)

Beschreibung

Mit remove() löschst du einen einzelnen Eintrag aus der Liste DataTransfer.items. Das kann ein Texteintrag (kind === "string") oder eine Datei (kind === "file") sein. Danach rücken alle folgenden Einträge nach, length wird also um eins kleiner.

Typische Einsatzfälle sind:

In einem dragstart-Handler bestimmte Datenformate wieder aus den Drag-Daten nehmen, zum Beispiel ein automatisch gesetztes text/uri-list.
Bei den Ereignissen copy oder cut die Daten in der Zwischenablage anpassen.
Einen selbst erzeugten new DataTransfer() verändern, etwa um eine einzelne Datei aus einem <input type="file"> zu entfernen.

Du kannst Einträge nur ändern, wenn der Datenspeicher im Lese-/Schreibmodus ist. Bei Drag-and-Drop gilt das nur während dragstart. Bei dragover, drop und ähnlichen Ereignissen ist der Speicher geschützt oder nur lesbar. Dann wirft remove() einen InvalidStateError.

Parameter

Name	Typ	Default	Beschreibung
$index Pflicht	number		Index des zu entfernenden Eintrags, beginnend bei 0. Liegt der Wert außerhalb von `0` bis `length - 1`, passiert nichts und es gibt keinen Fehler.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Liste wird direkt verändert.

Beispiele

Datenformat im dragstart-Handler entfernen

const link = document.querySelector('#drag-link');

link.addEventListener('dragstart', (event) => {
  const { items } = event.dataTransfer;

  // Eigene Daten ergänzen
  items.add('Nur Klartext, bitte', 'text/plain');

  // Automatisch gesetzte URL-Liste entfernen (rückwärts, damit die Indizes stimmen)
  for (let i = items.length - 1; i >= 0; i--) {
    if (items[i].type === 'text/uri-list') {
      items.remove(i);
    }
  }

  console.log([...items].map((item) => item.type));
});

["text/plain"] (je nach Browser auch weitere Formate wie "text/html")

Eine Datei aus einem Datei-Eingabefeld entfernen

const input = document.querySelector('input[type="file"][multiple]');

const removeFile = (indexToRemove) => {
  const dt = new DataTransfer();

  // Alle ausgewählten Dateien übernehmen
  for (const file of input.files) {
    dt.items.add(file);
  }

  // Gewünschte Datei entfernen
  dt.items.remove(indexToRemove);

  // Neue FileList zurückschreiben
  input.files = dt.files;
  console.log(`${input.files.length} Datei(en) verbleiben`);
};

input.addEventListener('change', () => {
  if (input.files.length > 1) removeFile(0);
});

z. B. "2 Datei(en) verbleiben" nach Auswahl von drei Dateien

Verhalten bei ungültigem Index und im geschützten Modus

const dt = new DataTransfer();
dt.items.add('Hallo', 'text/plain');
dt.items.add('<b>Hallo</b>', 'text/html');

dt.items.remove(99); // außerhalb des Bereichs: passiert nichts
console.log(dt.items.length); // 2

dt.items.remove(0);
console.log(dt.items[0].type); // text/html

document.addEventListener('drop', (event) => {
  event.preventDefault();
  try {
    event.dataTransfer.items.remove(0);
  } catch (err) {
    console.log(err.name); // InvalidStateError
  }
});

2 text/html InvalidStateError (beim Drop)

// Wichtig · Fallstricke

Nur im Lese-/Schreibmodus: Das gilt bei dragstart sowie bei copy und cut. Außerhalb davon, etwa bei drop, dragover oder paste, wirft remove() einen DOMException vom Typ InvalidStateError.
Indizes verschieben sich: Nach jedem Entfernen rücken die folgenden Einträge nach vorn. Wenn du in einer Schleife mehrere Einträge löschst, gehe rückwärts durch die Liste oder nimm gleich clear().
Ein ungültiger Index, zum Beispiel ein negativer oder zu großer Wert, führt nicht zu einem Fehler. Der Aufruf bewirkt dann einfach nichts.
Du kannst ein Eingabefeld nur über new DataTransfer() und das Zuweisen von input.files = dt.files verändern. Das funktioniert in allen aktuellen Browsern. Sehr alte Safari-Versionen (vor 14.1) unterstützen den DataTransfer-Konstruktor nicht.
Gibt es mehrere Einträge mit dem Typ kind === "string", entfernt DataTransfer.clearData(format) gezielt ein Format. remove() dagegen arbeitet mit der Position in der Liste.

Siehe auch

DataTransferItemList DataTransferItemList.add() DataTransferItemList.clear() DataTransferItem DataTransfer.clearData() DataTransferItem.getAsFileSystemHandle()