FileEntrySync — Schnittstelle · JavaScript-Referenz

Signatur

interface FileEntrySync extends EntrySync

Beschreibung

FileEntrySync gehört zur synchronen Variante der alten „File API: Directories and System“ (auch FileSystem API genannt). Ein Objekt dieses Typs steht für eine einzelne Datei im privaten, sandboxed Dateisystem einer Herkunft (Origin). Es erbt von EntrySync und hat daher Eigenschaften wie name, fullPath, isFile und filesystem sowie Methoden wie moveTo(), copyTo(), remove() und getMetadata().

Dazu kommen zwei eigene Methoden:

createWriter() gibt ein FileWriterSync zurück. Darüber schreibt man blockierend in die Datei (write(), seek(), truncate()).
file() gibt ein File-Objekt mit dem aktuellen Inhalt der Datei zurück. Lesen kann man es zum Beispiel mit FileReaderSync.

Ein FileEntrySync bekommt man nie über einen Konstruktor. Man erhält es immer über DirectoryEntrySync.getFile(), meist ausgehend von requestFileSystemSync() und dessen root. Weil die Aufrufe blockieren, war die API nur in Web Workers verfügbar. Dort ist sie praktisch, um große Datenmengen ohne Callback-Verschachtelung zu verarbeiten.

Für neue Projekte kommt die API nicht mehr in Frage. Der moderne Ersatz ist das Origin Private File System (OPFS) aus dem File System Standard. Dort bietet FileSystemFileHandle.createSyncAccessHandle() im Worker ebenfalls schnellen, synchronen Dateizugriff.

Rückgabewert

Typ

FileEntrySync

Beschreibung

Wird von DirectoryEntrySync.getFile(path, options) zurückgegeben. Die Methode createWriter() liefert ein FileWriterSync, die Methode file() ein File.

Beispiele

FileEntrySync im Worker holen und beschreiben

// worker.js – funktionierte nur in älteren Chrome-Versionen
const requestFS = self.requestFileSystemSync || self.webkitRequestFileSystemSync;

try {
  const fs = requestFS(self.TEMPORARY, 1024 * 1024); // 1 MB
  // getFile() liefert ein FileEntrySync
  const entry = fs.root.getFile('log.txt', { create: true });

  const writer = entry.createWriter(); // FileWriterSync
  writer.seek(writer.length);          // ans Dateiende springen
  writer.write(new Blob([`Start: ${new Date().toISOString()}\n`], { type: 'text/plain' }));

  postMessage(`Geschrieben: ${entry.fullPath} (${writer.length} Bytes)`);
} catch (err) {
  postMessage(`Fehler: ${err.name} – ${err.message}`);
}

Geschrieben: /log.txt (31 Bytes)

Dateiinhalt synchron mit file() und FileReaderSync lesen

// worker.js
const fs = self.webkitRequestFileSystemSync(self.TEMPORARY, 1024 * 1024);
const entry = fs.root.getFile('log.txt'); // ohne create: Datei muss existieren

const file = entry.file();             // File-Snapshot
const reader = new FileReaderSync();
const text = reader.readAsText(file);

postMessage({ name: entry.name, size: file.size, text });

{ name: 'log.txt', size: 31, text: 'Start: 2024-05-01T10:00:00.000Z\n' }

Moderner Ersatz: OPFS mit createSyncAccessHandle()

// worker.js – heute in allen aktuellen Browsern verfügbar
const schreibeLog = async (zeile) => {
  const root = await navigator.storage.getDirectory();
  const handle = await root.getFileHandle('log.txt', { create: true });
  const access = await handle.createSyncAccessHandle();

  const bytes = new TextEncoder().encode(zeile + '\n');
  access.write(bytes, { at: access.getSize() }); // synchron anhängen
  access.flush();
  const groesse = access.getSize();
  access.close();
  return groesse;
};

schreibeLog('Worker gestartet').then((size) => postMessage(`Dateigröße: ${size}`));

Dateigröße: 17

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die synchrone FileSystem API (requestFileSystemSync, EntrySync, FileEntrySync, FileWriterSync) gab es nur in Chromium mit webkit-Präfix. Sie wird nicht mehr unterstützt. Firefox und Safari hatten sie nie. Für neuen Code nimmt man FileSystemFileHandle.createSyncAccessHandle() (OPFS).
Nur in Workern: Im Hauptthread gab es die API nicht, weil blockierende Datei-Operationen die Oberfläche einfrieren würden.
Fehler werden geworfen: Anders als bei der asynchronen Variante (FileEntry) gibt es keine Fehler-Callbacks. Fehler wie NotFoundError, QuotaExceededError oder SecurityError kommen als Ausnahmen. Aufrufe gehören deshalb in try…catch.
Kein Zugriff auf echte Nutzerdateien: Das Dateisystem ist eine Sandbox pro Origin. Bei TEMPORARY darf der Browser die Daten jederzeit löschen.
file() liefert einen Stand zum Zeitpunkt des Aufrufs. Wird die Datei danach geändert, muss man file() erneut aufrufen.

Siehe auch

FileReaderSync FileSystemSync DirectoryEntrySync FileSystem Clients