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.

* Some parts of this feature may have varying levels of support.

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

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

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

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
FileSystemFileHandle
createSyncAccessHandle
mode option
ExperimentalNon-standard
createWritable
mode option
ExperimentalNon-standard
getFile

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.
Non-standard. Check cross-browser support before using.
See implementation notes.

Siehe auch