FileSystemSyncAccessHandle.close() — Methode · JavaScript-Referenz

Signatur

FileSystemSyncAccessHandle.prototype.close()

Beschreibung

Die Methode close() der Schnittstelle FileSystemSyncAccessHandle beendet die Arbeit mit einem synchronen Zugriffs-Handle. Einen solchen Handle erzeugt man mit FileSystemFileHandle.createSyncAccessHandle() im Origin Private File System (OPFS). Solange er offen ist, hält er eine exklusive Sperre auf die Datei. Andere Handles, auch aus anderen Workern oder Tabs derselben Herkunft, können die Datei in dieser Zeit weder synchron öffnen noch per createWritable() beschreiben.

Nach dem Aufruf von close() ist der Handle unbrauchbar: read(), write(), truncate(), getSize() und flush() werfen dann einen InvalidStateError. Gleichzeitig wird die Sperre freigegeben, sodass die Datei wieder geöffnet werden kann. Deshalb sollte man close() immer in einem finally-Block aufrufen. Ein Fehler beim Lesen oder Schreiben würde die Datei sonst bis zum Beenden des Workers sperren.

Die Methode arbeitet synchron und gibt undefined zurück. Beim Schließen werden ausstehende Änderungen auf den Datenträger geschrieben. Ein vorheriges flush() brauchen Sie also nur, wenn Sie die Daten schon während der Arbeit mit dem Handle dauerhaft sichern wollen. Ein zweiter Aufruf von close() auf einem bereits geschlossenen Handle bewirkt nichts und wirft keinen Fehler.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. In älteren Chromium-Versionen (vor 108) gab die Methode noch ein Promise<undefined> zurück.

Beispiele

Datei im Worker schreiben und sicher schließen

// worker.js – läuft in einem dedizierten Web Worker
const saveLog = async (text) => {
  const root = await navigator.storage.getDirectory();
  const fileHandle = await root.getFileHandle('log.txt', { create: true });
  const access = await fileHandle.createSyncAccessHandle();

  try {
    const data = new TextEncoder().encode(text);
    // An das Dateiende anhängen
    const written = access.write(data, { at: access.getSize() });
    console.log(`${written} Bytes geschrieben`);
  } finally {
    // Sperre immer freigeben – auch im Fehlerfall
    access.close();
  }
};

self.onmessage = (e) => saveLog(e.data);

12 Bytes geschrieben

Datei nach close() erneut öffnen

// worker.js
const demo = async () => {
  const root = await navigator.storage.getDirectory();
  const fileHandle = await root.getFileHandle('daten.bin', { create: true });

  const first = await fileHandle.createSyncAccessHandle();
  try {
    // Zweiter Handle schlägt fehl, solange 'first' offen ist
    await fileHandle.createSyncAccessHandle();
  } catch (err) {
    console.log('Gesperrt:', err.name);
  }

  first.close();

  // Nach close() ist die Sperre frei
  const second = await fileHandle.createSyncAccessHandle();
  console.log('Neu geöffnet, Größe:', second.getSize());
  second.close();
};

demo();

Gesperrt: NoModificationAllowedError Neu geöffnet, Größe: 0

Zugriff auf einen geschlossenen Handle

// worker.js
const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle('test.txt', { create: true });
const access = await fileHandle.createSyncAccessHandle();

access.close();
access.close(); // zweiter Aufruf: kein Fehler

try {
  access.getSize();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Nur in dedizierten Web Workern verfügbar: createSyncAccessHandle() gibt es weder im Hauptthread noch in Shared Workern oder Service Workern.
Sperre nicht vergessen: Ohne close() bleibt die Datei gesperrt, bis der Garbage Collector den Handle aufräumt oder der Worker beendet wird. Weitere Öffnungsversuche scheitern bis dahin mit NoModificationAllowedError. Rufen Sie close() daher immer in einem finally-Block auf.
Altes asynchrones Verhalten: In Chromium vor Version 108 waren close(), flush(), getSize() und truncate() asynchron und gaben ein Promise zurück. Ein await access.close() funktioniert in beiden Varianten. Für moderne Browser ist das aber nicht mehr nötig.
Die Methode braucht einen sicheren Kontext (HTTPS oder localhost).
Beim Schließen werden ausstehende Schreibvorgänge automatisch gesichert. Ein explizites flush() direkt davor ist überflüssig.

Siehe auch

FileSystemDirectoryHandle.entries() FileSystemSyncAccessHandle.flush() FileSystemSyncAccessHandle.write() FileSystemSyncAccessHandle.getSize() FileSystemSyncAccessHandle.read()