FileSystemSyncAccessHandle

Baseline 2023

Newly available

Since March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Diese Funktion ist nur in Dedicated Web Workers verfügbar.

Das FileSystemSyncAccessHandle Interface der File System API repräsentiert einen synchronen Zugriff auf einen Dateisystemeintrag.

Diese Klasse ist nur innerhalb dedizierter Web Workers zugänglich (damit ihre Methoden die Ausführung im Haupt-Thread nicht blockieren) für Dateien innerhalb des ursprungsbasierten privaten Dateisystems, das für Endnutzer nicht sichtbar ist.

Daher unterliegen ihre Methoden nicht denselben Sicherheitsprüfungen wie Methoden, die auf Dateien im für Nutzer sichtbaren Dateisystem ausgeführt werden, und sind daher wesentlich performanter. Dies macht sie geeignet für bedeutende, groß angelegte Dateiaktualisierungen wie beispielsweise SQLite Datenbankmodifikationen.

Das Interface wird über die Methode FileSystemFileHandle.createSyncAccessHandle() aufgerufen.

Hinweis: In früheren Versionen der Spezifikation waren close(), flush(), getSize() und truncate() fälschlicherweise als asynchrone Methoden spezifiziert, und ältere Versionen einiger Browser implementieren sie auf diese Weise. Allerdings implementieren alle aktuellen Browser, die diese Methoden unterstützen, sie als synchrone Methoden.

Instanz-Eigenschaften

Keine.

Instanz-Methoden

close()

Schließt einen offenen synchronen Datei-Handle, deaktiviert weitere Operationen darauf und gibt die exklusive Sperre frei, die zuvor auf die mit dem Datei-Handle assoziierte Datei gelegt wurde.

flush()

Schreibt alle Änderungen, die über die write() Methode an der mit dem Handle verbundenen Datei vorgenommen wurden, auf die Festplatte.

getSize()

Gibt die Größe der mit dem Handle verknüpften Datei in Bytes zurück.

read()

Liest den Inhalt der mit dem Handle verbundenen Datei in einen angegebenen Puffer, optional bei einem bestimmten Offset.

truncate()

Ändert die Größe der mit dem Handle verbundenen Datei auf eine bestimmte Anzahl von Bytes.

write()

Schreibt den Inhalt eines angegebenen Puffers in die mit dem Handle verknüpfte Datei, optional bei einem bestimmten Offset.

Beispiele

Die folgende asynchrone Ereignisbehandlungsfunktion befindet sich innerhalb eines Web Workers. Beim Empfang einer Nachricht vom Haupt-Thread:

  • Erstellt sie einen synchronen Dateizugriffs-Handle.
  • Holt die Größe der Datei und erstellt einen ArrayBuffer, um sie zu enthalten.
  • Liest den Dateinhalt in den Puffer.
  • Kodiert die Nachricht und schreibt sie ans Ende der Datei.
  • Speichert die Änderungen auf der Festplatte und schließt den Zugriffshandle.
js
onmessage = async (e) => {
  // Retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Get sync access handle
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Get size of the file.
  const fileSize = accessHandle.getSize();
  // Read file content to a buffer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Write the message to the end of the file.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persist changes to disk.
  accessHandle.flush();

  // Always close FileSystemSyncAccessHandle if done.
  accessHandle.close();
};

Spezifikationen

Specification
File System Standard
# api-filesystemsyncaccesshandle

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch