FileSystemDirectoryHandle.getFileHandle() — Methode · JavaScript-Referenz

Signatur

FileSystemDirectoryHandle.prototype.getFileHandle(name, options)

Beschreibung

Mit getFileHandle() greifen Sie über ein FileSystemDirectoryHandle auf eine Datei zu, die direkt in diesem Verzeichnis liegt. Das zurückgegebene FileSystemFileHandle dient danach zum Lesen (getFile()) oder Schreiben (createWritable() bzw. createSyncAccessHandle() in Workern).

Standardmäßig muss die Datei schon vorhanden sein, sonst wird das Promise mit einem NotFoundError abgelehnt. Mit { create: true } wird eine fehlende Datei als leere Datei angelegt. Eine bereits vorhandene Datei bleibt dabei unverändert und wird nicht geleert.

Typische Einsatzorte sind das Origin Private File System (OPFS), das Sie über navigator.storage.getDirectory() erhalten und das in allen modernen Browsern verfügbar ist, sowie Verzeichnisse, die der Nutzer mit window.showDirectoryPicker() ausgewählt hat. Letzteres gibt es nur in Chromium-Browsern.

Der Parameter name ist ein einzelner Dateiname und kein Pfad. Für Dateien in Unterordnern gehen Sie mit getDirectoryHandle() Schritt für Schritt durch die Ordnerebenen.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name der Datei im aktuellen Verzeichnis. Er darf kein Pfadtrennzeichen (`/`, `\`) enthalten und nicht `.`, `..` oder leer sein.
$options	object	{}	Optionales Objekt mit Einstellungen.
$options.create	boolean	false	Bei `true` wird eine fehlende Datei angelegt. Bei `false` führt eine fehlende Datei zu einem `NotFoundError`.

Rückgabewert

Typ

Promise<FileSystemFileHandle>

Beschreibung

Ein Promise, das mit dem FileSystemFileHandle der Datei erfüllt wird. Es wird abgelehnt mit NotFoundError (Datei fehlt und create ist nicht gesetzt), TypeMismatchError (unter dem Namen existiert ein Verzeichnis), TypeError (ungültiger Name), NotAllowedError (Berechtigung fehlt) oder QuotaExceededError (Speicherplatz reicht nicht).

Beispiele

Datei im OPFS anlegen und beschreiben

const root = await navigator.storage.getDirectory();
// Datei anlegen, falls sie noch nicht existiert
const fileHandle = await root.getFileHandle('notizen.txt', { create: true });

const writable = await fileHandle.createWritable();
await writable.write('Hallo OPFS!');
await writable.close();

const file = await fileHandle.getFile();
console.log(file.name, await file.text());

notizen.txt Hallo OPFS!

Prüfen, ob eine Datei existiert

const fileExists = async (dirHandle, name) => {
  try {
    await dirHandle.getFileHandle(name); // ohne create
    return true;
  } catch (err) {
    if (err.name === 'NotFoundError') return false;
    throw err; // z. B. TypeMismatchError bei einem Ordner
  }
};

const root = await navigator.storage.getDirectory();
console.log(await fileExists(root, 'config.json'));

false

Datei in einem verschachtelten Pfad auflösen

const getFileByPath = async (root, path, create = false) => {
  const parts = path.split('/').filter(Boolean);
  const fileName = parts.pop();
  let dir = root;
  for (const part of parts) {
    dir = await dir.getDirectoryHandle(part, { create });
  }
  return dir.getFileHandle(fileName, { create });
};

const root = await navigator.storage.getDirectory();
const handle = await getFileByPath(root, 'daten/2024/bericht.csv', true);
console.log(handle.kind, handle.name);

file bericht.csv

Datei in einem vom Nutzer gewählten Ordner lesen (Chromium)

document.querySelector('#open').addEventListener('click', async () => {
  const dir = await window.showDirectoryPicker();
  try {
    const handle = await dir.getFileHandle('package.json');
    const json = JSON.parse(await (await handle.getFile()).text());
    console.log('Projekt:', json.name);
  } catch (err) {
    console.error('package.json nicht gefunden:', err.name);
  }
});

Projekt: mein-projekt

// Wichtig · Fallstricke

Kein Pfad: Übergeben Sie etwa 'a/b.txt', wird das Promise mit einem TypeError abgelehnt. Unterordner lösen Sie mit getDirectoryHandle() auf.
Namenskonflikt: Heißt ein Verzeichnis so wie die gesuchte Datei, schlägt der Aufruf auch mit { create: true } fehl, und zwar mit einem TypeMismatchError.
create: true leert nichts: Eine vorhandene Datei bleibt erhalten. Zum Überschreiben verwenden Sie createWritable(). Diese Methode schreibt standardmäßig in eine neue, leere Datei, die das Original beim close() ersetzt.
Berechtigungen: Bei Ordnern aus showDirectoryPicker() ist für create: true eine Schreibberechtigung nötig (requestPermission({ mode: 'readwrite' })). Im OPFS ist keine Berechtigung erforderlich.
Kompatibilität: Im OPFS funktioniert getFileHandle() in allen modernen Browsern. showDirectoryPicker() gibt es dagegen nur in Chromium (Chrome, Edge, Opera), nicht in Firefox und Safari.
Die API steht nur in einem sicheren Kontext (HTTPS) zur Verfügung, sowohl im Hauptthread als auch in Workern.

Siehe auch

FileSystemDirectoryHandle.getDirectoryHandle() FileSystemDirectoryHandle.entries() FileSystemDirectoryHandle.removeEntry() FileSystemDirectoryHandle.resolve() FileSystemDirectoryHandle.keys()