FileSystemDirectoryHandle.getDirectoryHandle() — Methode · JavaScript-Referenz

Signatur

FileSystemDirectoryHandle.prototype.getDirectoryHandle(name, options)

Beschreibung

getDirectoryHandle() ist Teil der File System API. Die Methode sucht im aktuellen Verzeichnis nach einem direkten Unterverzeichnis mit dem Namen name und gibt ein Promise zurück. Dieses wird mit einem FileSystemDirectoryHandle erfüllt. Über das Handle kannst du dann Dateien lesen, schreiben oder weitere Unterverzeichnisse öffnen.

Meist nutzt du die Methode in zwei Situationen: im Origin Private File System (OPFS), das du über navigator.storage.getDirectory() erreichst, oder in einem Verzeichnis, das die Nutzerin per window.showDirectoryPicker() ausgewählt hat. Mit der Option { create: true } wird das Verzeichnis angelegt, falls es noch fehlt. Das funktioniert ähnlich wie mkdir für eine einzelne Ebene.

Wichtig: Die Methode kennt keine Pfade. Der Name darf weder / noch \ enthalten und darf nicht . oder .. sein. Für verschachtelte Pfade rufst du getDirectoryHandle() für jede Ebene einzeln auf. Gibt es unter dem Namen schon eine Datei, wird das Promise mit einem TypeMismatchError abgelehnt.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des Unterverzeichnisses. Muss ein gültiger Dateiname ohne Pfadtrenner sein; `.`, `..` und leere Namen sind nicht erlaubt.
$options	{ create?: boolean }	{}	Optionales Objekt mit Einstellungen.
$options.create	boolean	false	Bei `true` wird das Verzeichnis angelegt, falls es nicht existiert. Bei `false` führt ein fehlendes Verzeichnis zu einem `NotFoundError`.

Rückgabewert

Typ

Promise<FileSystemDirectoryHandle>

Beschreibung

Ein Promise, das mit dem Handle des (vorhandenen oder neu angelegten) Unterverzeichnisses erfüllt wird. Mögliche Ablehnungsgründe: NotAllowedError (Berechtigung fehlt), TypeError (ungültiger Name), TypeMismatchError (unter dem Namen existiert eine Datei), NotFoundError (Verzeichnis fehlt und create ist nicht true, oder das aktuelle Verzeichnis wurde entfernt).

Beispiele

Unterverzeichnis im OPFS anlegen oder öffnen

const root = await navigator.storage.getDirectory();

// Legt 'cache' an, falls es noch nicht existiert
const cacheDir = await root.getDirectoryHandle('cache', { create: true });
console.log(cacheDir.kind, cacheDir.name);

directory cache

Prüfen, ob ein Verzeichnis existiert

const dirExists = async (parent, name) => {
  try {
    await parent.getDirectoryHandle(name);
    return true;
  } catch (err) {
    if (err.name === 'NotFoundError') return false;
    throw err; // z. B. TypeMismatchError, wenn es eine Datei ist
  }
};

const root = await navigator.storage.getDirectory();
console.log(await dirExists(root, 'gibt-es-nicht'));

false

Verschachtelten Pfad Ebene für Ebene anlegen (mkdir -p)

const mkdirp = async (root, path) => {
  let dir = root;
  for (const part of path.split('/').filter(Boolean)) {
    dir = await dir.getDirectoryHandle(part, { create: true });
  }
  return dir;
};

const root = await navigator.storage.getDirectory();
const imgDir = await mkdirp(root, 'projekte/2024/bilder');

// Datei im tiefsten Verzeichnis anlegen
const file = await imgDir.getFileHandle('info.txt', { create: true });
const writable = await file.createWritable();
await writable.write('Hallo OPFS');
await writable.close();
console.log(imgDir.name);

bilder

Unterordner in einem vom Nutzer gewählten Verzeichnis

document.querySelector('#open').addEventListener('click', async () => {
  // Nur Chromium-Browser; braucht eine Nutzeraktion
  const dir = await window.showDirectoryPicker({ mode: 'readwrite' });
  const exportDir = await dir.getDirectoryHandle('export', { create: true });
  for await (const [name, handle] of exportDir.entries()) {
    console.log(handle.kind, name);
  }
});

// Wichtig · Fallstricke

Keine Pfade: getDirectoryHandle('a/b') führt zu einem TypeError. Öffne jede Ebene einzeln.
Datei vs. Verzeichnis: Gibt es unter dem Namen bereits eine Datei, wird das Promise auch mit create: true mit einem TypeMismatchError abgelehnt. Die Datei wird dabei nicht überschrieben.
Berechtigungen: Bei Verzeichnissen aus showDirectoryPicker() braucht create: true Schreibrechte (mode: 'readwrite' bzw. requestPermission()). Sonst gibt es einen NotAllowedError.
Sicherer Kontext: Die Methode ist nur über HTTPS bzw. localhost verfügbar.
Kompatibilität: Im OPFS (navigator.storage.getDirectory()) unterstützen Chrome, Edge, Firefox und Safari die Methode. showDirectoryPicker() und damit der Zugriff auf echte Nutzerordner gibt es nur in Chromium-Browsern. Prüfe die Unterstützung vorher, z. B. mit 'showDirectoryPicker' in window.
Das Anlegen ist nicht atomar über mehrere Ebenen: Bricht ein Durchlauf von mkdirp ab, bleiben die schon angelegten Zwischenverzeichnisse bestehen.

Siehe auch

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