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 Handle zu einem 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 origin-privaten Dateisystems, welches für Endbenutzer nicht sichtbar ist.

Infolgedessen unterliegen ihre Methoden nicht denselben Sicherheitsüberprüfungen wie Methoden, die auf Dateien im benutzer-sichtbaren Dateisystem ausgeführt werden, und sind daher wesentlich leistungsfähiger. Das macht sie geeignet für signifikante, großflächige Dateiaktualisierungen wie SQLite-Datenbankmodifikationen.

Auf das Interface wird über die Methode FileSystemFileHandle.createSyncAccessHandle() zugegriffen.

Hinweis: In früheren Versionen der Spezifikation wurden close(), flush(), getSize(), und truncate() fälschlicherweise als asynchrone Methoden angegeben, 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(): Schliesst einen offenen synchronen Datei-Handle, deaktiviert weitere Operationen darauf und gibt die exklusive Sperre frei, die zuvor auf die Datei im Zusammenhang mit dem Datei-Handle gesetzt wurde.
flush(): Schreibt alle Änderungen, die durch die write()-Methode an der mit dem Handle verbundenen Datei vorgenommen wurden, auf die Festplatte.
getSize(): Gibt die Größe der mit dem Handle verbundenen Datei in Bytes zurück.
read(): Liest den Inhalt der mit dem Handle verbundenen Datei in einen angegebenen Puffer, optional an einem bestimmten Offset.
truncate(): Ändert die Größe der mit dem Handle verbundenen Datei auf eine angegebene Anzahl von Bytes.
write(): Schreibt den Inhalt eines angegebenen Puffers in die mit dem Handle verbundene Datei, optional an einem bestimmten Offset.

Beispiele

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

Wird ein synchroner Datei-Zugriffshandle erstellt.
Die Größe der Datei wird ermittelt und ein ArrayBuffer erstellt, um sie zu enthalten.
Der Dateiinhalte wird in den Puffer gelesen.
Die Nachricht wird codiert und an das Ende der Datei geschrieben.
Die Änderungen werden auf die Festplatte geschrieben und der Zugriffshandle wird geschlossen.

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 # api-filesystemsyncaccesshandle