DataTransferItemList.length — Eigenschaft · JavaScript-Referenz

Signatur

get DataTransferItemList.length

Beschreibung

Die schreibgeschützte Eigenschaft length liefert die Anzahl der Elemente in einer DataTransferItemList. Diese Liste erreicht man über DataTransfer.items, z. B. in Drag-and-Drop-Events (dragstart, dragover, drop) oder in Zwischenablage-Events (paste, copy, cut) über event.clipboardData.items.

Jeder Eintrag ist ein DataTransferItem mit der Art "string" oder "file". Mit length lässt sich prüfen, ob überhaupt Daten vorhanden sind, und man kann die Liste mit einer klassischen for-Schleife und Indexzugriff (items[i]) durchlaufen. DataTransferItemList ist nämlich kein echtes Array und hat keine Array-Methoden wie map oder filter.

Der Wert ändert sich, sobald Einträge mit add(), remove() oder clear() hinzugefügt oder entfernt werden. Diese Änderungen sind aber nur im Lese-/Schreibmodus möglich, also während dragstart. Ist der zugehörige DataTransfer nicht mehr aktiv (z. B. nach dem Ende eines Event-Handlers), gibt length 0 zurück.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative Ganzzahl mit der Anzahl der DataTransferItem-Objekte in der Liste. Ist der Drag-Datenspeicher deaktiviert, ist der Wert 0.

Beispiele

Anzahl abgelegter Elemente beim Drop ermitteln

const dropZone = document.querySelector('#drop-zone');

// dragover muss abgebrochen werden, sonst ist ein Drop nicht erlaubt
dropZone.addEventListener('dragover', (event) => event.preventDefault());

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();
  const { items } = event.dataTransfer;
  console.log(`Abgelegte Einträge: ${items.length}`);

  for (let i = 0; i < items.length; i++) {
    const item = items[i];
    console.log(i, item.kind, item.type);
  }
});

Abgelegte Einträge: 2 0 file image/png 1 file application/pdf

Eingefügte Bilder aus der Zwischenablage erkennen

document.addEventListener('paste', (event) => {
  const items = event.clipboardData?.items;
  if (!items || items.length === 0) {
    console.log('Zwischenablage ist leer.');
    return;
  }

  // In ein Array umwandeln, um Array-Methoden zu nutzen
  const images = Array.from(items)
    .filter((item) => item.kind === 'file' && item.type.startsWith('image/'))
    .map((item) => item.getAsFile());

  console.log(`${items.length} Einträge, davon ${images.length} Bild(er)`);
});

3 Einträge, davon 1 Bild(er)

length ändert sich durch add() und clear() in dragstart

const source = document.querySelector('#draggable');

source.addEventListener('dragstart', (event) => {
  const { items } = event.dataTransfer;
  items.clear();
  console.log('Nach clear():', items.length);

  items.add('Hallo Welt', 'text/plain');
  items.add('<b>Hallo Welt</b>', 'text/html');
  console.log('Nach add():', items.length);
});

Nach clear(): 0 Nach add(): 2

// Wichtig · Fallstricke

Nur Lesezugriff: Eine Zuweisung wie items.length = 0 hat keine Wirkung (im Strict Mode wird ein TypeError geworfen). Zum Leeren der Liste dient clear().
Geschützter Modus: In dragenter und dragover sind Anzahl, kind und type der Einträge sichtbar, die Inhalte aber nicht. Die Daten selbst lassen sich erst bei drop auslesen.
Nicht über den Handler hinaus aufheben: Wer eine Referenz auf items speichert und später (z. B. nach einem await) darauf zugreift, bekommt oft length === 0. Deshalb die benötigten Einträge oder Dateien synchron im Handler kopieren, z. B. mit Array.from(items) oder getAsFile().
items.length und dataTransfer.files.length können sich unterscheiden: items enthält auch Texteinträge, files nur Dateien.
Wird von allen modernen Browsern unterstützt. Ältere Safari-Versionen (vor 11.1) kannten DataTransfer.items nicht; dort als Ausweichlösung dataTransfer.types bzw. files verwenden.

Siehe auch

SVGTransformList.length DataTransferItem.kind DataTransferItem.type DataTransfer.items CSSTransformValue.length