FileSystemFileHandle

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: Dieses Feature ist verfügbar in Web Workers.

Die FileSystemFileHandle-Schnittstelle der File System API repräsentiert einen Verweis auf einen Dateisystemeintrag. Auf die Schnittstelle wird über die Methode window.showOpenFilePicker() zugegriffen.

Beachten Sie, dass Lese- und Schreiboperationen von Dateizugriffsberechtigungen abhängen, die nach einem Neuladen der Seite nicht mehr bestehen, wenn keine anderen Tabs für diesen Ursprung geöffnet bleiben. Die queryPermission-Methode der FileSystemHandle-Schnittstelle kann verwendet werden, um den Berechtigungsstatus zu überprüfen, bevor auf eine Datei zugegriffen wird.

FileSystemHandle FileSystemFileHandle

Instanz-Eigenschaften

Erbt Eigenschaften von ihrem Elternteil, FileSystemHandle.

Instanz-Methoden

Erbt Methoden von ihrem Elternteil, FileSystemHandle.

getFile()

Gibt ein Promise zurück, das sich zu einem File Objekt auflöst, welches den Zustand auf der Festplatte des durch den Handle dargestellten Eintrags darstellt.

createSyncAccessHandle()

Gibt ein Promise zurück, das sich zu einem FileSystemSyncAccessHandle Objekt auflöst, welches verwendet werden kann, um synchron von einer Datei zu lesen und in eine Datei zu schreiben. Die synchrone Natur dieser Methode bietet Leistungsvorteile, ist jedoch nur innerhalb dedizierter Web Workers nutzbar.

createWritable()

Gibt ein Promise zurück, das sich zu einem neu erstellten FileSystemWritableFileStream Objekt auflöst, welches verwendet werden kann, um in eine Datei zu schreiben.

Beispiele

Eine Datei lesen

Die folgende asynchrone Funktion präsentiert einen Dateiauswähler und sobald eine Datei ausgewählt wurde, wird die getFile() Methode verwendet, um den Inhalt abzurufen.

js
async function getTheFile() {
  const pickerOpts = {
    types: [
      {
        description: "Images",
        accept: {
          "image/*": [".png", ".gif", ".jpeg", ".jpg"],
        },
      },
    ],
    excludeAcceptAllOption: true,
    multiple: false,
  };

  // open file picker
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
  // get file contents
  const fileData = await fileHandle.getFile();
  return fileData;
}

Eine Datei schreiben

Die folgende asynchrone Funktion schreibt die gegebenen Inhalte auf den Datei-Handle und damit auf die Festplatte.

js
async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();

  // Write the contents of the file to the stream.
  await writable.write(contents);

  // Close the file and write the contents to disk.
  await writable.close();
}

Synchrones Lesen und Schreiben einer Datei

Die folgende asynchrone Ereignis-Handler-Funktion ist in einem Web Worker enthalten. Beim Empfang einer Nachricht vom Hauptthread:

  • Erstellt einen synchronen Datei-Zugriffs-Handle.
  • Ermittelt die Größe der Datei und erstellt ein ArrayBuffer, um diese zu enthalten.
  • Liest den Dateiinhalte in den Puffer.
  • Kodiert die Nachricht und schreibt sie ans Ende der Datei.
  • Speichert die Änderungen auf der Festplatte und schließt den Zugriffs-Handle.
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();
};

Hinweis: In früheren Versionen der Spezifikation wurden 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.

Spezifikationen

Specification
File System Standard
# api-filesystemfilehandle

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch