FileSystemSync — Schnittstelle · JavaScript-Referenz

Signatur

interface FileSystemSync

Beschreibung

FileSystemSync ist die synchrone Variante von FileSystem aus der alten File and Directory Entries API (früher „FileSystem API: Directories and System“). Ein Objekt dieses Typs steht für ein sandboxed Dateisystem, das der Browser einer Herkunft (Origin) zuweist. Man erzeugt es nicht selbst, sondern bekommt es als Rückgabewert von requestFileSystemSync(), in Chromium als self.webkitRequestFileSystemSync().

Die Schnittstelle hat nur zwei schreibgeschützte Eigenschaften:

name (string): ein eindeutiger, vom Browser vergebener Name des Dateisystems.
root (DirectoryEntrySync): das Wurzelverzeichnis. Von dort aus legt man Dateien und Verzeichnisse an, liest sie oder löscht sie, zum Beispiel mit getFile() und getDirectory().

Da alle Aufrufe blockieren, gibt es die API nur in Web Workern und nicht im Hauptthread. Gedacht war sie für rechenintensive Aufgaben, bei denen synchroner Dateizugriff den Code einfacher macht, etwa beim Zwischenspeichern großer Binärdaten.

In neuem Code sollte man sie nicht mehr verwenden. Der moderne Ersatz ist das Origin Private File System (OPFS) über navigator.storage.getDirectory(). In Workern bietet FileSystemFileHandle.createSyncAccessHandle() dort ebenfalls schnellen, synchronen Lese- und Schreibzugriff.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	number		Parameter von `requestFileSystemSync(type, size)`, mit dem man ein `FileSystemSync` anfordert: `TEMPORARY` (0) für Speicher, den der Browser löschen darf, oder `PERSISTENT` (1) für dauerhaften Speicher, der ein Kontingent braucht.
$size Pflicht	number		Parameter von `requestFileSystemSync()`: gewünschte Speichergröße in Bytes.

Beispiele

Dateisystem im Worker anfordern und untersuchen

// worker.js – läuft nur in Chromium-Browsern mit Präfix
const requestFS = self.requestFileSystemSync || self.webkitRequestFileSystemSync;

if (requestFS) {
  // 0 = TEMPORARY, 5 MB
  const fs = requestFS(0, 5 * 1024 * 1024);
  console.log('Name:', fs.name);
  console.log('Root:', fs.root.fullPath);
} else {
  console.log('FileSystemSync wird nicht unterstützt');
}

Name: http_localhost_8080:Temporary Root: /

Datei synchron schreiben und lesen

// worker.js
const requestFS = self.webkitRequestFileSystemSync;
const fs = requestFS(0, 1024 * 1024);

try {
  // Datei anlegen (oder öffnen, falls vorhanden)
  const entry = fs.root.getFile('log.txt', { create: true });

  // Schreiben mit FileWriterSync
  const writer = entry.createWriter();
  writer.truncate(0);
  writer.write(new Blob(['Hallo aus dem Worker'], { type: 'text/plain' }));

  // Lesen mit FileReaderSync
  const text = new FileReaderSync().readAsText(entry.file());
  self.postMessage(text);
} catch (err) {
  self.postMessage(`Fehler: ${err.name}`);
}

Hallo aus dem Worker

Moderner Ersatz: OPFS mit synchronem Zugriff im Worker

// worker.js – in allen aktuellen Browsern
const run = async () => {
  const root = await navigator.storage.getDirectory();
  const fileHandle = await root.getFileHandle('log.txt', { create: true });
  const access = await fileHandle.createSyncAccessHandle();

  const data = new TextEncoder().encode('Hallo OPFS');
  access.truncate(0);
  access.write(data, { at: 0 });
  access.flush();

  const buffer = new Uint8Array(access.getSize());
  access.read(buffer, { at: 0 });
  access.close();

  console.log(new TextDecoder().decode(buffer));
};

run();

Hallo OPFS

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Spezifikation wurde aufgegeben. Firefox und Safari haben FileSystemSync nie unterstützt. Chromium bietet es nur mit Präfix (webkitRequestFileSystemSync) an und kann es jederzeit entfernen. Für Produktionscode nicht geeignet.
Nur in Web Workern: Im Hauptthread gibt es requestFileSystemSync nicht. Wer asynchron arbeiten will, nimmt die Variante FileSystem, die über webkitRequestFileSystem angefordert wird.
Sandbox: Das Dateisystem gehört zur jeweiligen Herkunft (Origin) und ist vom echten Dateisystem des Nutzers getrennt. Beliebige lokale Dateien sind damit nicht erreichbar.
Fehlerbehandlung: Synchrone Methoden werfen bei Fehlern Ausnahmen, etwa NotFoundError oder QuotaExceededError. Deshalb Aufrufe immer in try/catch einschließen.
PERSISTENT-Speicher braucht ein vorher genehmigtes Kontingent. Ohne dieses scheitert das Anfordern.
Migration: Besser das Origin Private File System verwenden, also navigator.storage.getDirectory() und im Worker createSyncAccessHandle().

Siehe auch

DirectoryEntrySync FileSystem FileEntrySync FileReaderSync FileSystemEntry