Signatur
Beschreibung
Die Eigenschaft items des DataTransfer-Objekts liefert eine DataTransferItemList. Sie enthält für jedes übertragene Datenelement ein DataTransferItem, zum Beispiel einen Text, eine URL, HTML oder eine Datei. Jedes Element hat die Eigenschaften kind ("string" oder "file") und type (MIME-Typ).
Gegenüber den älteren Wegen getData() und files ist items vielseitiger. Du kannst Text- und Dateielemente einheitlich durchlaufen, Dateien mit getAsFile() lesen, Strings asynchron mit getAsString() abrufen und mit webkitGetAsEntry() bzw. getAsFileSystemHandle() sogar ganze Ordner verarbeiten. Beim Start eines Drags kannst du mit items.add() eigene Daten anhängen und sie mit remove() oder clear() wieder entfernen.
Die Eigenschaft selbst ist schreibgeschützt: Du kannst ihr keine neue Liste zuweisen, wohl aber die zurückgegebene Liste verändern, sofern der Vorgang das erlaubt. Typische Einsatzorte sind Handler für drop, dragstart, dragover und paste (über ClipboardEvent.clipboardData).
Rückgabewert
DataTransferItem-Objekten. Sie ist array-ähnlich (length, Indexzugriff) und iterierbar, aber kein echtes Array.Beispiele
Abgelegte Dateien und Texte in einer Drop-Zone auswerten
const zone = document.querySelector('#dropzone');
zone.addEventListener('dragover', (event) => {
event.preventDefault(); // nötig, damit ein Drop möglich ist
});
zone.addEventListener('drop', (event) => {
event.preventDefault();
for (const item of event.dataTransfer.items) {
if (item.kind === 'file') {
const file = item.getAsFile();
console.log(`Datei: ${file.name} (${file.size} Bytes)`);
} else if (item.kind === 'string' && item.type === 'text/plain') {
item.getAsString((text) => console.log(`Text: ${text}`));
}
}
});Eigene Daten beim Drag-Start hinzufügen
const card = document.querySelector('#task-card');
card.draggable = true;
card.addEventListener('dragstart', (event) => {
const { items } = event.dataTransfer;
items.clear();
items.add(card.dataset.id, 'text/plain');
items.add(JSON.stringify({ id: card.dataset.id, title: card.textContent }), 'application/json');
console.log(`Anzahl Elemente: ${items.length}`);
});Bilder aus der Zwischenablage einfügen
document.addEventListener('paste', (event) => {
const images = [...event.clipboardData.items]
.filter((item) => item.kind === 'file' && item.type.startsWith('image/'))
.map((item) => item.getAsFile());
for (const img of images) {
const el = document.createElement('img');
el.src = URL.createObjectURL(img);
document.body.append(el);
}
console.log(`${images.length} Bild(er) eingefügt`);
});Abgelegte Ordner erkennen
zone.addEventListener('drop', (event) => {
event.preventDefault();
for (const item of event.dataTransfer.items) {
const entry = item.webkitGetAsEntry?.();
if (entry) {
console.log(`${entry.isDirectory ? 'Ordner' : 'Datei'}: ${entry.name}`);
}
}
});// Wichtig · Fallstricke
- Nur synchron nutzbar: Die Liste ist nur während des Event-Handlers gültig. Nach dem ersten
awaitoder in einem späteren Callback ist sie leer. Hol dir Dateien mitgetAsFile()deshalb sofort und verarbeite sie erst danach asynchron. - Schutzmodi: In
dragenterunddragoverist der Datenspeicher geschützt. Dort siehst du nurkindundtype, aber keine Inhalte. Lesbar sind die Daten nur indrop(bzw.paste), schreibbar nur indragstart. getAsString()arbeitet mit einem Callback und liefert kein Promise.- Die Liste ist kein
Array. Fürfilterodermapwandelst du sie zuerst um, z. B. mit[...items]oderArray.from(items). - Ohne
preventDefault()indragoverunddropöffnet der Browser die Datei selbst, statt deinen Code auszuführen. - Kompatibilität: Wird von allen modernen Browsern unterstützt, Safari erst seit 11.1.
webkitGetAsEntry()ist nicht standardisiert, funktioniert aber in allen großen Browsern. - Sicherheit: Abgelegter HTML-Inhalt (
text/html) kann Schadcode enthalten. Füge ihn nie ungeprüft perinnerHTMLein, sonst droht XSS.