DiecreateSyncAccessHandle() Methode desFileSystemFileHandle Interfaces gibt einPromise zurück, das in einFileSystemSyncAccessHandle Objekt aufgelöst wird, das verwendet werden kann, um synchron auf eine Datei zuzugreifen und sie zu bearbeiten. Die synchrone Natur dieser Methode bringt Leistungsverbesserungen, ist jedoch nur innerhalb dedizierterWeb Worker für Dateien imorigin private file system nutzbar.

Das Erstellen einesFileSystemSyncAccessHandle nimmt eine exklusive Sperre auf die Datei ein, die mit dem Dateihandle verbunden ist. Dies verhindert die Erstellung weitererFileSystemSyncAccessHandles oderFileSystemWritableFileStreams für die Datei, bis das bestehende Zugriffshandle geschlossen wird.

Syntax

createSyncAccessHandle()createSyncAccessHandle(options)

Parameter

optionsOptional

Ein Objekt mit den folgenden Eigenschaften:

modeOptionalNicht standardisiert

Ein String, der den Sperrmodus für das Zugriffshandle angibt. Der Standardwert ist"readwrite". Mögliche Werte sind:

"read-only"

MehrereFileSystemSyncAccessHandle Objekte können gleichzeitig auf eine Datei geöffnet werden (zum Beispiel bei der Verwendung der gleichen Anwendung in mehreren Tabs), vorausgesetzt, sie werden alle im Modus"read-only" geöffnet. Sobald geöffnet, können leseähnliche Methoden auf den Handles aufgerufen werden —read(),getSize(), undclose().

"readwrite"

Nur einFileSystemSyncAccessHandle Objekt kann auf eine Datei geöffnet werden. Der Versuch, weitere Handles zu öffnen, bevor das erste Handle geschlossen ist, führt zu einerNoModificationAllowedError Ausnahme. Sobald geöffnet, kann jede verfügbare Methode auf dem Handle aufgerufen werden.

"readwrite-unsafe"

MehrereFileSystemSyncAccessHandle Objekte können gleichzeitig auf eine Datei geöffnet werden, vorausgesetzt, sie werden alle im Modus"readwrite-unsafe" geöffnet. Sobald geöffnet, kann jede verfügbare Methode auf den Handles aufgerufen werden.

Rückgabewert

EinPromise das in einFileSystemSyncAccessHandle Objekt aufgelöst wird.

Ausnahmen

NotAllowedErrorDOMException

Wird ausgelöst, wenn derPermissionStatus.state für das Handle nichtgranted imreadwrite Modus ist.

InvalidStateErrorDOMException

Wird ausgelöst, wenn dasFileSystemSyncAccessHandle Objekt keine Datei imorigin private file system darstellt.

NotFoundErrorDOMException

Wird ausgelöst, wenn der aktuelle Eintrag nicht gefunden wird.

NoModificationAllowedErrorDOMException

Wird ausgelöst, wenn der Browser keine Sperre auf die mit dem Dateihandle verbundene Datei erwerben kann. Dies könnte der Fall sein, weilmode aufreadwrite gesetzt ist und versucht wird, mehrere Handles gleichzeitig zu öffnen.

Beispiele

Grundlegende Verwendung

Der folgende asynchrone Ereignis-Handler ist in einem Web Worker enthalten. Der darin enthaltene Code erstellt ein synchrones Dateizugriffshandle.

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();  // …  // Always close FileSystemSyncAccessHandle if done.  accessHandle.close();};

Komplettes Beispiel mitmode Option

UnsercreateSyncAccessHandle() Modus Test Beispiel (sehen Sie sich denQuellcode an) stellt ein<input> Feld bereit, um Text einzugeben, und zwei Tasten — eine, um eingegebenen Text an das Ende einer Datei im origin private file system zu schreiben, und eine, um die Datei zu leeren, wenn sie zu voll wird.

Versuchen Sie, das oben stehende Demo zu erkunden, während die Entwicklertools des Browsers geöffnet sind, damit Sie sehen, was passiert. Wenn Sie versuchen, das Demo in mehreren Browser-Tabs zu öffnen, werden Sie feststellen, dass mehrere Handles gleichzeitig geöffnet werden können, um gleichzeitig in die Datei zu schreiben. Dies liegt daran, dassmode: "readwrite-unsafe" auf dencreateSyncAccessHandle() Aufrufen gesetzt ist.

Nachfolgend werden wir den Code untersuchen.

HTML

Die zwei<button> Elemente und das Text<input> Feld sehen so aus:

<ol>  <li>    <label for="file-text">Enter text to write to the file:</label>    <input type="text" name="file-text" />  </li>  <li>    Write your text to the file: <button>Write text</button>  </li>  <li>    Empty the file if it gets too full:    <button>Empty file</button>  </li></ol>

Haupt-JavaScript

Das Haupt-JavaScript im HTML-Dokument ist unten gezeigt. Wir holen Verweise auf die Schreib-Taste, die Datei-Leer-Taste und das Texteingabefeld, dann erstellen wir einen neuen Web Worker mit demWorker() Konstruktor. Wir definieren dann zwei Funktionen und legen sie als Ereignis-Handler für die Tasten fest:

• writeToOPFS() wird ausgeführt, wenn die Schreib-Taste geklickt wird. Diese Funktion sendet den eingegebenen Wert des Textfeldes innerhalb eines Objekts an den Worker mit derWorker.postMessage() Methode, dann leert sie das Textfeld, um für die nächste Eingabe bereit zu sein. Beachten Sie, dass das gesendete Objekt auch einecommand: "write" Eigenschaft enthält, um anzugeben, dass wir mit dieser Nachricht eine Schreibaktion auslösen möchten.
• emptyOPFS() wird ausgeführt, wenn die Datei-Leer-Taste geklickt wird. Dies sendet ein Objekt, das einecommand: "empty" Eigenschaft enthält, an den Worker, der angibt, dass die Datei geleert werden soll.

const writeBtn = document.querySelector(".write");const emptyBtn = document.querySelector(".empty");const fileText = document.querySelector("#file-text");const opfsWorker = new Worker("worker.js");function writeToOPFS() {  opfsWorker.postMessage({    command: "write",    content: fileText.value,  });  console.log("Main script: Text posted to worker");  fileText.value = "";}function emptyOPFS() {  opfsWorker.postMessage({    command: "empty",  });}writeBtn.addEventListener("click", writeToOPFS);emptyBtn.addEventListener("click", emptyOPFS);

Worker JavaScript

Das Worker-JavaScript wird unten gezeigt.

Zuerst führen wir eine Funktion namensinitOPFS() aus, die eine Referenz auf das OPFS-Root-Verzeichnis mitStorageManager.getDirectory() erhält, eine Datei erstellt und ihr Handle mitFileSystemDirectoryHandle.getFileHandle() zurückgibt, und dann einFileSystemSyncAccessHandle mitcreateSyncAccessHandle() zurückgibt. Dieser Aufruf beinhaltet diemode: "readwrite-unsafe" Eigenschaft, die es mehreren Handles erlaubt, gleichzeitig auf die gleiche Datei zuzugreifen.

let accessHandle;async function initOPFS() {  const opfsRoot = await navigator.storage.getDirectory();  const fileHandle = await opfsRoot.getFileHandle("file.txt", { create: true });  accessHandle = await fileHandle.createSyncAccessHandle({    mode: "readwrite-unsafe",  });}initOPFS();

Innerhalb dermessage event-Handler-Funktion des Workers erhalten wir zuerst die Größe der Datei mitgetSize(). Dann überprüfen wir, ob die mit der Nachricht gesendeten Daten einecommand Eigenschaft mit dem Wert"empty" enthalten. Wenn ja, leeren wir die Datei mittruncate() mit einem Wert von0 und aktualisieren die Dateigröße in dersize Variablen.

Wenn die Nachrichtendaten etwas anderes sind, tun wir Folgendes:

• Wir erstellen einen neuenTextEncoder undTextDecoder, um später den Textinhalt zu kodieren und zu dekodieren.
• Wir kodieren die Nachrichtendaten und schreiben das Ergebnis ans Ende der Datei mitwrite(), dann aktualisieren wir die Dateigröße in dersize Variablen.
• Wir erstellen eineDataView, um den Dateiinhalten Raum zu geben, und lesen den Inhalt in sie hinein mitread().
• Wir dekodieren denDataView Inhalt und protokollieren ihn in die Konsole.

onmessage = function (e) {  console.log("Worker: Message received from main script");  // Get the current size of the file  let size = accessHandle.getSize();  if (e.data.command === "empty") {    // Truncate the file to 0 bytes    accessHandle.truncate(0);    // Get the current size of the file    size = accessHandle.getSize();  } else {    const textEncoder = new TextEncoder();    const textDecoder = new TextDecoder();    // Encode content to write to the file    const content = textEncoder.encode(e.data.content);    // Write the content at the end of the file    accessHandle.write(content, { at: size });    // Get the current size of the file    size = accessHandle.getSize();    // Prepare a data view of the length of the file    const dataView = new DataView(new ArrayBuffer(size));    // Read the entire file into the data view    accessHandle.read(dataView, { at: 0 });    // Log the current file contents to the console    console.log(`File contents: ${textDecoder.decode(dataView)}`);    // Flush the changes    accessHandle.flush();  }  // Log the size of the file to the console  console.log(`Size: ${size}`);};

Spezifikationen

Browser-Kompatibilität

Siehe auch

• File System API
• The File System Access API: simplifying access to local files