FileSystemDirectoryEntry.getFile() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

getFile() gehört zur File and Directory Entries API. Die Methode sucht innerhalb des Verzeichnisbaums, dessen Wurzel das aufgerufene FileSystemDirectoryEntry ist, eine Datei anhand ihres Pfads. Wird die Datei gefunden, bekommt successCallback ein FileSystemFileEntry. Mit dessen Methode file() kommen Sie dann an das eigentliche File-Objekt und damit an den Inhalt.

Solche Verzeichniseinträge bekommen Sie in der Praxis fast nur auf zwei Wegen: per Drag & Drop über DataTransferItem.webkitGetAsEntry() oder über ein <input type="file" webkitdirectory> mit HTMLInputElement.webkitEntries. Nützlich ist getFile() vor allem, wenn Sie in einem hineingezogenen Ordner gezielt eine bestimmte Datei suchen, etwa package.json oder config/settings.json, ohne erst den ganzen Baum mit createReader() zu durchlaufen.

Die API arbeitet ausschließlich mit Callbacks, Promises gibt es hier nicht. Die Methode selbst gibt undefined zurück. Wenn Sie mit async/await arbeiten wollen, packen Sie den Aufruf in ein eigenes Promise (siehe Beispiel). In aktuellen Browsern sind die Dateisysteme dieser API schreibgeschützt. Die Option create ist deshalb in der Praxis ohne Nutzen.

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	string		Pfad zur gesuchten Datei. Ein relativer Pfad wird vom aktuellen Verzeichnis aus aufgelöst, ein absoluter (beginnt mit `/`) von der Wurzel des Dateisystems. Das Trennzeichen ist `/`.
$options	{ create?: boolean, exclusive?: boolean }	{}	`create`: Datei anlegen, falls sie fehlt. `exclusive`: zusammen mit `create` einen Fehler auslösen, wenn die Datei schon existiert. In aktuellen Browsern ist das Dateisystem schreibgeschützt, `create: true` endet dort mit einem Fehler.
$successCallback	(entry: FileSystemFileEntry) => void		Wird mit dem gefundenen `FileSystemFileEntry` aufgerufen.
$errorCallback	(error: DOMException) => void		Wird bei einem Fehler aufgerufen, z. B. mit `NotFoundError` (Datei fehlt), `TypeMismatchError` (der Pfad zeigt auf ein Verzeichnis) oder `SecurityError`.

Rückgabewert

Typ

undefined

Beschreibung

Kein direkter Rückgabewert. Das Ergebnis kommt asynchron über successCallback bzw. errorCallback.

Beispiele

Datei in einem hineingezogenen Ordner finden

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

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.getFile('package.json', {}, (fileEntry) => {
    fileEntry.file(async (file) => {
      const pkg = JSON.parse(await file.text());
      console.log(`Projekt: ${pkg.name}@${pkg.version}`);
    });
  }, (err) => {
    console.error(`Keine package.json gefunden: ${err.name}`);
  });
});

Projekt: mein-projekt@1.2.0

Promise-Wrapper für async/await

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

const entryToFile = (fileEntry) =>
  new Promise((resolve, reject) => fileEntry.file(resolve, reject));

// Nutzung, z. B. im drop-Handler
const readConfig = async (dirEntry) => {
  try {
    const fileEntry = await getFileEntry(dirEntry, 'config/settings.json');
    const file = await entryToFile(fileEntry);
    console.log(fileEntry.fullPath, file.size, 'Bytes');
    return JSON.parse(await file.text());
  } catch (err) {
    if (err.name === 'NotFoundError') return null; // Konfiguration ist optional
    throw err;
  }
};

/mein-ordner/config/settings.json 482 Bytes

Fehlerfall: Pfad zeigt auf ein Verzeichnis

// dirEntry stammt aus webkitGetAsEntry()
dirEntry.getFile('src', {}, 
  (f) => console.log('Datei:', f.name),
  (err) => console.log('Fehler:', err.name)
);

Fehler: TypeMismatchError

// Wichtig · Fallstricke

Nur lesend: In aktuellen Browsern lässt sich mit dieser API nichts anlegen oder schreiben. Wenn Sie Dateien schreiben wollen, nehmen Sie die File System Access API (FileSystemDirectoryHandle.getFileHandle()) oder das Origin Private File System (navigator.storage.getDirectory()).
Nur Callbacks: Ohne errorCallback gehen Fehler still verloren. Geben Sie ihn immer mit an oder nutzen Sie einen Promise-Wrapper.
Zeitpunkt beim Drag & Drop: Rufen Sie webkitGetAsEntry() synchron im drop-Handler auf. Nach einem await ist die DataTransferItemList bereits leer.
Der Pfad muss genau stimmen. Ob Groß- und Kleinschreibung beachtet wird, hängt vom Betriebssystem ab. Das Trennzeichen ist immer /, auch unter Windows.
Kompatibilität: In allen modernen Browsern verfügbar. Viele Einstiegspunkte tragen aber weiterhin das webkit-Präfix (webkitGetAsEntry, webkitdirectory). Die API ist nicht standardisiert im Sinne eines W3C-Empfehlungsstatus und in Node.js nicht vorhanden.

Siehe auch

FileSystemDirectoryEntry.getDirectory() FileSystemDirectoryEntry.createReader() FileSystemDirectoryEntry.removeRecursively() FileSystemDirectoryHandle.entries() FileSystemDirectoryHandle.resolve()