DirectoryReaderSync — Schnittstelle · JavaScript-Referenz

Signatur

interface DirectoryReaderSync

Beschreibung

DirectoryReaderSync gehört zur synchronen Variante der alten File and Directory Entries API, früher auch „FileSystem API“ genannt. Ein Objekt dieses Typs bekommst du über DirectoryEntrySync.createReader(). Mit seiner einzigen Methode readEntries() liest du die Einträge des Verzeichnisses aus. Das sind FileEntrySync- und DirectoryEntrySync-Objekte.

Die API ist synchron und blockiert. Deshalb gibt es sie nur in Web Workern, im Haupt-Thread nicht. Sie ist praktisch, wenn du in einem Worker ohne Callbacks durch ein Verzeichnis im privaten, sandboxed Dateisystem der Seite gehen willst, etwa für Dateilisten, Aufräumjobs oder Exporte.

Wichtig: readEntries() liefert nicht unbedingt alle Einträge auf einmal. Du musst die Methode so lange aufrufen, bis ein leeres Array zurückkommt. Erst dann hast du das Verzeichnis vollständig gelesen.

Die Schnittstelle ist nicht standardisiert und veraltet. Für neuen Code nimm das Origin Private File System (OPFS) mit navigator.storage.getDirectory() und FileSystemDirectoryHandle.entries(). In Workern gibt es dafür zusätzlich FileSystemFileHandle.createSyncAccessHandle().

Parameter

Name	Typ	Default	Beschreibung
$readEntries()	function		Einzige Methode des Interfaces. Nimmt keine Argumente und gibt synchron den nächsten Block von Verzeichniseinträgen als `Array<EntrySync>` zurück. Ein leeres Array bedeutet: Es gibt keine weiteren Einträge. Bei einem Fehler wird eine Ausnahme geworfen (`FileException` bzw. `DOMException`, z. B. `NOT_FOUND_ERR` oder `SECURITY_ERR`).

Rückgabewert

Typ

Array<FileEntrySync | DirectoryEntrySync>

Beschreibung

readEntries() gibt ein Array mit Einträgen zurück. Jeder Eintrag hat unter anderem die Eigenschaften name, fullPath, isFile und isDirectory. Ein leeres Array zeigt an, dass das Verzeichnis vollständig gelesen ist.

Beispiele

Reader anlegen und alle Einträge des Stammverzeichnisses lesen (im Worker)

// worker.js
const requestFs = self.requestFileSystemSync || self.webkitRequestFileSystemSync;
const fs = requestFs(self.TEMPORARY, 5 * 1024 * 1024);

// DirectoryReaderSync erzeugen
const reader = fs.root.createReader();

// readEntries() so lange aufrufen, bis ein leeres Array kommt
const entries = [];
let batch;
while ((batch = reader.readEntries()).length > 0) {
  entries.push(...batch);
}

self.postMessage(entries.map((e) => `${e.isDirectory ? '[D]' : '[F]'} ${e.name}`));

["[D] bilder", "[F] notizen.txt", "[F] config.json"]

Verzeichnisbaum rekursiv auflisten

// worker.js
const readAll = (dirEntry) => {
  const reader = dirEntry.createReader();
  const result = [];
  let batch;
  while ((batch = reader.readEntries()).length) {
    result.push(...batch);
  }
  return result;
};

const walk = (dirEntry, depth = 0) => {
  for (const entry of readAll(dirEntry)) {
    console.log(`${'  '.repeat(depth)}${entry.fullPath}`);
    if (entry.isDirectory) walk(entry, depth + 1);
  }
};

try {
  const fs = self.webkitRequestFileSystemSync(self.TEMPORARY, 1024 * 1024);
  walk(fs.root);
} catch (err) {
  console.error('Lesen fehlgeschlagen:', err.name, err.message);
}

/bilder /bilder/logo.png /notizen.txt

Funktionsprüfung mit modernem Ersatz (OPFS)

// worker.js – modul- oder klassischer Worker
const listRoot = async () => {
  if (self.navigator?.storage?.getDirectory) {
    // Moderner, standardisierter Weg
    const root = await navigator.storage.getDirectory();
    const names = [];
    for await (const [name, handle] of root.entries()) {
      names.push(`${handle.kind}: ${name}`);
    }
    return names;
  }
  if (self.webkitRequestFileSystemSync) {
    // Veralteter Weg mit DirectoryReaderSync
    const reader = self.webkitRequestFileSystemSync(self.TEMPORARY, 1024 * 1024).root.createReader();
    const names = [];
    let batch;
    while ((batch = reader.readEntries()).length) {
      names.push(...batch.map((e) => `${e.isFile ? 'file' : 'directory'}: ${e.name}`));
    }
    return names;
  }
  throw new Error('Keine Dateisystem-API verfügbar');
};

listRoot().then((list) => self.postMessage(list));

["file: notizen.txt", "directory: bilder"]

// Wichtig · Fallstricke

Nicht standardisiert und veraltet: Die API gab es nur in Chromium-basierten Browsern und meist mit Präfix (webkitRequestFileSystemSync). Firefox und Safari haben die synchrone Variante nie angeboten. Nutze sie nicht für neuen Code, sondern nimm das Origin Private File System (navigator.storage.getDirectory()).
Nur in Web Workern: Im Haupt-Thread gibt es weder requestFileSystemSync noch DirectoryReaderSync.
Häufiger Fehler: Wer readEntries() nur einmal aufruft, bekommt bei großen Verzeichnissen womöglich nicht alle Einträge. Lies immer in einer Schleife, bis ein leeres Array zurückkommt.
Kein fester Zustand: Ein Reader liest das Verzeichnis genau einmal durch. Wenn du es erneut lesen willst, erzeugst du mit createReader() einen neuen Reader.
Ausnahmen: Fehler kommen als Ausnahme, nicht über Callbacks. Pack die Aufrufe deshalb in try…catch.
Sandbox: Die API erreicht nur das private Dateisystem der jeweiligen Herkunft, nicht das Dateisystem des Nutzers.

Siehe auch

Worker DirectoryEntrySync FileReaderSync DOMRectReadOnly FileEntrySync