FileSystemDirectoryEntry.getDirectory() — Methode · JavaScript-Referenz

Signatur

FileSystemDirectoryEntry.prototype.getDirectory(path, options, successCallback, errorCallback)

Beschreibung

Mit getDirectory() holt man sich ausgehend von einem FileSystemDirectoryEntry ein weiteres Verzeichnis, das irgendwo in dessen Unterbaum liegt. Der Pfad kann relativ zum aktuellen Verzeichnis ("bilder/2024") oder absolut zur Wurzel des Dateisystems ("/projekt/src") angegeben werden. Das Ergebnis wird nicht zurückgegeben, sondern asynchron an einen Callback übergeben.

Typischerweise begegnet man der Methode beim Drag-and-Drop von Ordnern: Über DataTransferItem.webkitGetAsEntry() erhält man einen Eintrag für den abgelegten Ordner und kann dann gezielt auf bekannte Unterordner zugreifen, statt den ganzen Baum mit createReader() zu durchlaufen. Auch HTMLInputElement.webkitEntries liefert solche Einträge.

Das options-Objekt kennt create und exclusive. In der Praxis sind per Drag-and-Drop oder Dateiauswahl erhaltene Dateisysteme jedoch schreibgeschützt – create: true führt dort zu einem Fehler. Die Methode dient heute also fast ausschließlich zum Lesen.

Weil die API rein Callback-basiert ist, lohnt es sich, sie in ein Promise zu verpacken, um sie mit async/await nutzen zu können.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Relativer (zum aktuellen Verzeichnis) oder absoluter Pfad (beginnend mit `/`) des gesuchten Verzeichnisses. `..` und `.` sind erlaubt, man kann aber nicht über die Wurzel hinaus navigieren.
$options	{ create?: boolean, exclusive?: boolean }	{}	`create`: Verzeichnis anlegen, falls es fehlt. `exclusive`: nur zusammen mit `create` wirksam – Fehler, wenn das Verzeichnis bereits existiert. In schreibgeschützten Dateisystemen (Drag-and-Drop) nicht nutzbar.
$successCallback	(entry: FileSystemDirectoryEntry) => void		Wird mit dem gefundenen (oder erstellten) Verzeichnis-Eintrag aufgerufen.
$errorCallback	(error: DOMException) => void		Wird bei Fehlern aufgerufen, z. B. mit `NotFoundError`, `TypeMismatchError` (Pfad zeigt auf eine Datei) oder `SecurityError`.

Rückgabewert

Typ

undefined

Beschreibung

Kein direkter Rückgabewert. Das Ergebnis wird an successCallback bzw. ein Fehler an errorCallback übergeben.

Beispiele

Unterordner eines per Drag-and-Drop abgelegten Ordners öffnen

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

dropZone.addEventListener('dragover', (e) => e.preventDefault());

dropZone.addEventListener('drop', (e) => {
  e.preventDefault();
  const entry = e.dataTransfer.items[0]?.webkitGetAsEntry();

  if (!entry?.isDirectory) {
    console.warn('Bitte einen Ordner ablegen.');
    return;
  }

  entry.getDirectory(
    'src',
    {},
    (srcDir) => console.log('Gefunden:', srcDir.fullPath),
    (err) => console.error('Kein src-Ordner:', err.name)
  );
});

Gefunden: /mein-projekt/src

Promise-Wrapper für async/await

const getDirectory = (dirEntry, path, options = {}) =>
  new Promise((resolve, reject) => {
    dirEntry.getDirectory(path, options, resolve, reject);
  });

const readEntries = (dirEntry) =>
  new Promise((resolve, reject) => {
    dirEntry.createReader().readEntries(resolve, reject);
  });

// Nutzung, z. B. im drop-Handler mit einem Verzeichnis-Eintrag rootEntry
const listImages = async (rootEntry) => {
  try {
    const imgDir = await getDirectory(rootEntry, 'assets/images');
    const entries = await readEntries(imgDir);
    console.log(entries.filter((e) => e.isFile).map((e) => e.name));
  } catch (err) {
    console.error(`Fehler (${err.name}): ${err.message}`);
  }
};

["logo.png", "hero.jpg"]

Fehlerfälle unterscheiden

const openConfigDir = (rootEntry) => {
  rootEntry.getDirectory('config', {}, (dir) => {
    console.log('Konfigurationsordner:', dir.fullPath);
  }, (err) => {
    switch (err.name) {
      case 'NotFoundError':
        console.log('Ordner "config" existiert nicht.');
        break;
      case 'TypeMismatchError':
        console.log('"config" ist eine Datei, kein Ordner.');
        break;
      default:
        console.error('Unerwarteter Fehler:', err);
    }
  });
};

Ordner "config" existiert nicht.

// Wichtig · Fallstricke

Schreibgeschützt: Dateisysteme aus Drag-and-Drop oder <input type="file" webkitdirectory> sind nur lesbar. create: true schlägt dort fehl, meist mit SecurityError.
Nur Callbacks: Die Methode gibt kein Promise zurück. Ein await entry.getDirectory(...) ohne Wrapper liefert undefined.
Zeigt der Pfad auf eine Datei, gibt es einen TypeMismatchError. Für Dateien nimmt man stattdessen getFile().
Kompatibilität: Wird in Chrome, Edge, Firefox und Safari unterstützt. Einstiegspunkte wie webkitGetAsEntry() tragen aber weiterhin das webkit-Präfix. Das zugehörige Sandbox-Dateisystem (requestFileSystem) ist veraltet. Für neue Projekte mit Schreibzugriff sollte man die File System Access API bzw. das Origin Private File System verwenden (FileSystemDirectoryHandle.getDirectoryHandle()).
Hat eine Seite keinen Zugriff auf den Pfad, z. B. durch .. über die Wurzel hinaus, wird nur innerhalb des freigegebenen Dateisystems aufgelöst. Man kommt also nie über den abgelegten Ordner hinaus.

Siehe auch

FileSystemDirectoryEntry.createReader() FileSystemDirectoryEntry.getFile() FileSystemDirectoryEntry.removeRecursively() FileSystemDirectoryHandle.getDirectoryHandle() FileSystemDirectoryHandle.removeEntry()