Signatur
Beschreibung
Die schreibgeschützte Eigenschaft webkitEntries eines <input type="file">-Elements liefert ein Array von Einträgen der File and Directory Entries API. Jeder Eintrag ist entweder ein FileSystemFileEntry (Datei) oder ein FileSystemDirectoryEntry (Verzeichnis). Beide erben von FileSystemEntry.
Im Gegensatz zu HTMLInputElement.files, das nur eine flache FileList liefert, kann man mit den Einträgen Verzeichnisstrukturen durchlaufen. Das geht über FileSystemDirectoryEntry.createReader() und readEntries(). Ob überhaupt Verzeichnisse ausgewählt werden können, hängt vom Attribut webkitdirectory ab.
Wichtiger Hinweis zur Praxis: In vielen Browsern (vor allem Chrome) ist das Array bei Auswahl über den normalen Dateidialog leer. Zuverlässig mit Einträgen gefüllt wird es meist nur beim Ablegen per Drag & Drop auf das Input-Element. Für Drag & Drop auf beliebige Elemente nimmt man stattdessen DataTransferItem.webkitGetAsEntry().
Rückgabewert
FileSystemEntry-Objekten (FileSystemFileEntry bzw. FileSystemDirectoryEntry). Wurde nichts ausgewählt oder unterstützt der Browser die Eigenschaft in diesem Fall nicht, ist das Array leer.Beispiele
Ausgewählte Einträge auflisten
// <input type="file" id="picker" webkitdirectory multiple>
const picker = document.getElementById('picker');
picker.addEventListener('change', () => {
const entries = picker.webkitEntries;
if (entries.length === 0) {
console.log('Keine Einträge, Fallback auf files:', picker.files.length);
return;
}
for (const entry of entries) {
console.log(entry.isDirectory ? '📁' : '📄', entry.fullPath);
}
});Verzeichnis rekursiv durchlaufen (Promise-basiert)
const readAllEntries = (dirEntry) => new Promise((resolve, reject) => {
const reader = dirEntry.createReader();
const all = [];
// readEntries liefert Ergebnisse stückweise – so lange lesen, bis ein leeres Array kommt
const readBatch = () => reader.readEntries((batch) => {
if (batch.length === 0) return resolve(all);
all.push(...batch);
readBatch();
}, reject);
readBatch();
});
const collectFiles = async (entry, result = []) => {
if (entry.isFile) {
const file = await new Promise((res, rej) => entry.file(res, rej));
result.push({ path: entry.fullPath, size: file.size });
} else if (entry.isDirectory) {
for (const child of await readAllEntries(entry)) {
await collectFiles(child, result);
}
}
return result;
};
const input = document.querySelector('input[type=file]');
input.addEventListener('drop', async () => {
// Einträge stehen nach dem Drop zur Verfügung
await new Promise((r) => setTimeout(r));
for (const entry of input.webkitEntries) {
console.table(await collectFiles(entry));
}
});Feature-Erkennung mit Fallback
const input = document.querySelector('input[type=file]');
const supportsEntries = 'webkitEntries' in HTMLInputElement.prototype;
input.addEventListener('change', () => {
if (supportsEntries && input.webkitEntries.length > 0) {
console.log('Einträge-API:', input.webkitEntries.map((e) => e.name));
} else {
// webkitRelativePath enthält bei webkitdirectory den relativen Pfad
console.log('FileList:', [...input.files].map((f) => f.webkitRelativePath || f.name));
}
});// Wichtig · Fallstricke
- Nicht standardisiert: Die Eigenschaft gehört zum Entwurf der File and Directory Entries API und hat das Präfix
webkit, auch in Firefox. Für Produktivcode immer eine Feature-Erkennung und einen Fallback aufinput.fileseinbauen. - Häufig leer: Bei Auswahl über den Dateidialog liefert Chrome ein leeres Array. Wer verlässlich Einträge braucht, sollte Drag & Drop mit
DataTransferItem.webkitGetAsEntry()verwenden oder beiwebkitdirectorymitFile.webkitRelativePatharbeiten. readEntries()liefert Ergebnisse stückweise (in Chrome höchstens 100 pro Aufruf). Man muss so oft erneut aufrufen, bis ein leeres Array zurückkommt, sonst fehlen Dateien.- Die API arbeitet mit Callbacks statt Promises, deshalb braucht man eigene Promise-Wrapper.
- Für echten Lese- und Schreibzugriff auf das Dateisystem ist die modernere File System Access API (
showDirectoryPicker()) gedacht. Sie wird allerdings nur in Chromium-Browsern unterstützt. - Die Einträge sind ein Sandbox-Abbild der Auswahl. Einen Zugriff auf absolute Pfade des Nutzersystems gibt es nicht.