File System API

Konzepte und Verwendung

Diese API ermglicht die Interaktion mit Dateien auf dem lokalen Gert eines Benutzers oder in einem fr den Benutzer zugnglichen Netzwerkdateisystem. Zu den Kernfunktionen dieser API gehren das Lesen von Dateien, das Schreiben oder Speichern von Dateien sowie der Zugriff auf die Verzeichnisstruktur.

Der grte Teil der Interaktion mit Dateien und Verzeichnissen erfolgt ber Handles. Eine bergeordnete Klasse FileSystemHandle hilft bei der Definition zweier untergeordneter Klassen: FileSystemFileHandle und FileSystemDirectoryHandle, jeweils fr Dateien und Verzeichnisse.

Die Handles reprsentieren eine Datei oder ein Verzeichnis auf dem System des Benutzers. Sie knnen zunchst Zugriff darauf erhalten, indem Sie dem Benutzer mithilfe von Methoden wie window.showOpenFilePicker() und window.showDirectoryPicker() eine Datei- oder Verzeichnisauswahl anzeigen. Nach deren Aufruf wird die Dateiauswahl angezeigt, und der Benutzer whlt entweder eine Datei oder ein Verzeichnis aus. Wenn dies erfolgreich erfolgt, wird ein Handle zurckgegeben.

Sie knnen auch ber Folgendes Zugriff auf Datei-Handles erhalten:

• Die Methode DataTransferItem.getAsFileSystemHandle() der HTML Drag and Drop API.
• Die File Handling API.

Jedes Handle stellt eigene Funktionen bereit, und je nachdem, welches Sie verwenden, gibt es einige Unterschiede (siehe den Abschnitt Interfaces fr spezifische Details). Anschlieend knnen Sie auf Dateidaten oder Informationen (einschlielich untergeordneter Eintrge) des ausgewhlten Verzeichnisses zugreifen. Diese API erffnet potenzielle Funktionen, die dem Web bisher fehlten. Dennoch war Sicherheit bei der Entwicklung der API von grter Bedeutung, und der Zugriff auf Datei-/Verzeichnisdaten ist nicht erlaubt, sofern der Benutzer ihn nicht ausdrcklich gestattet (beachten Sie, dass dies beim origin private file system nicht der Fall ist, da es fr den Benutzer nicht sichtbar ist).

Origin private file system

Das origin private file system (OPFS) ist ein als Teil der File System API bereitgestellter Speicherendpunkt, der fr den Ursprung der Seite privat und im Gegensatz zum regulren Dateisystem fr den Benutzer nicht sichtbar ist. Es bietet Zugriff auf eine besondere Art von Datei, die stark auf Leistung optimiert ist und direkten Schreibzugriff auf ihren Inhalt ermglicht.

Im Folgenden finden Sie einige mgliche Anwendungsflle:

• Apps mit dauerhaftem Uploader

  • Wenn eine Datei oder ein Verzeichnis zum Hochladen ausgewhlt wird, knnen Sie die Datei in eine lokale Sandbox kopieren und jeweils einen Chunk hochladen.
  • Die App kann Uploads nach einer Unterbrechung fortsetzen, etwa wenn der Browser geschlossen wird oder abstrzt, die Verbindung unterbrochen wird oder der Computer heruntergefahren wird.

• Videospiele oder andere Apps mit vielen Medien-Assets

  • Die App ldt ein oder mehrere groe Tarballs herunter und entpackt sie lokal in eine Verzeichnisstruktur.
  • Die App ruft Assets im Hintergrund vorab ab, sodass der Benutzer zur nchsten Aufgabe oder Spielebene wechseln kann, ohne auf einen Download warten zu mssen.

• Audio- oder Fotoeditor mit Offlinezugriff oder lokalem Cache (hervorragend fr Leistung und Geschwindigkeit)

  • Die App kann direkt in Dateien schreiben (beispielsweise nur die ID3-/EXIF-Tags und nicht die gesamte Datei berschreiben).

• Offline-Videobetrachter

  • Die App kann groe Dateien (>1GB) zum spteren Ansehen herunterladen.
  • Die App kann auf teilweise heruntergeladene Dateien zugreifen (sodass Sie das erste Kapitel Ihrer DVD ansehen knnen, auch wenn die App den Rest des Inhalts noch herunterldt oder den Download nicht abgeschlossen hat, weil Sie loslaufen mussten, um einen Zug zu erreichen).

• Offline-Webmail-Client

  • Der Client ldt Anhnge herunter und speichert sie lokal.
  • Der Client speichert Anhnge fr einen spteren Upload im Cache.

Lesen Sie unseren Artikel zum Origin private file system, um Anweisungen zur Verwendung zu erhalten.

Dateien speichern

• Bei asynchronen Handles verwenden Sie das Interface FileSystemWritableFileStream. Sobald die Daten, die Sie speichern mchten, im Format eines Blob, eines String-Objekts, eines String-Literals oder eines buffer vorliegen, knnen Sie einen Stream ffnen und die Daten in einer Datei speichern. Dies kann die vorhandene Datei oder eine neue Datei sein.
• Beim synchronen FileSystemSyncAccessHandle schreiben Sie nderungen mithilfe der Methode write() in eine Datei. Optional knnen Sie auch flush() aufrufen, wenn die nderungen zu einem bestimmten Zeitpunkt auf den Datentrger geschrieben werden mssen (andernfalls knnen Sie dies dem zugrunde liegenden Betriebssystem berlassen, wenn es dies fr angebracht hlt, was in den meisten Fllen in Ordnung sein sollte).

Interfaces

FileSystemChangeRecord

Enthlt Details zu einer einzelnen nderung, die von einem FileSystemObserver beobachtet wurde.

FileSystemHandle

Ein Objekt, das einen Datei- oder Verzeichniseintrag reprsentiert. Mehrere Handles knnen denselben Eintrag reprsentieren. Meistens arbeiten Sie nicht direkt mit FileSystemHandle, sondern mit dessen untergeordneten Interfaces FileSystemFileHandle und FileSystemDirectoryHandle.

FileSystemFileHandle

Stellt ein Handle fr einen Dateisystemeintrag bereit.

FileSystemDirectoryHandle

Stellt ein Handle fr ein Dateisystemverzeichnis bereit.

FileSystemObserver

Stellt einen Mechanismus bereit, um nderungen an ausgewhlten Dateien oder Verzeichnissen zu beobachten.

FileSystemSyncAccessHandle

Stellt ein synchrones Handle fr einen Dateisystemeintrag bereit, das direkt mit einer einzelnen Datei auf dem Datentrger arbeitet. Die synchrone Natur der Datei-Lese- und -Schreibvorgnge ermglicht eine hhere Leistung fr kritische Methoden in Kontexten, in denen asynchrone Operationen einen hohen Overhead verursachen, z. B. WebAssembly. Diese Klasse ist nur innerhalb dedizierter Web Workers fr Dateien im origin private file system zugnglich.

FileSystemWritableFileStream

Ein WritableStream-Objekt mit zustzlichen Komfortmethoden, das mit einer einzelnen Datei auf dem Datentrger arbeitet.

Erweiterungen anderer Interfaces

Window.showDirectoryPicker()

Zeigt eine Verzeichnisauswahl an, mit der der Benutzer ein Verzeichnis auswhlen kann.

Window.showOpenFilePicker()

Zeigt eine Dateiauswahl an, mit der ein Benutzer eine oder mehrere Dateien auswhlen kann.

Window.showSaveFilePicker()

Zeigt eine Dateiauswahl an, mit der ein Benutzer eine Datei speichern kann.

DataTransferItem.getAsFileSystemHandle()

Gibt ein Promise zurck, das mit einem FileSystemFileHandle erfllt wird, wenn das gezogene Element eine Datei ist, oder mit einem FileSystemDirectoryHandle, wenn das gezogene Element ein Verzeichnis ist.

StorageManager.getDirectory()

Wird verwendet, um eine Referenz auf ein FileSystemDirectoryHandle-Objekt zu erhalten, das Zugriff auf ein Verzeichnis und dessen Inhalt ermglicht, welche im origin private file system gespeichert sind. Gibt ein Promise zurck, das mit einem FileSystemDirectoryHandle-Objekt erfllt wird.

Beispiele

Zugriff auf Dateien

Der folgende Code ermglicht dem Benutzer, eine Datei ber die Dateiauswahl auszuwhlen.

async function getFile() {
  // Open file picker and destructure the result the first handle
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  return file;
}

Die folgende asynchrone Funktion zeigt eine Dateiauswahl an und verwendet nach der Auswahl einer Datei die Methode getFile(), um den Inhalt abzurufen.

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

async function getTheFile() {
  // Open file picker and destructure the result the first handle
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // get file contents
  const fileData = await fileHandle.getFile();
}

Zugriff auf Verzeichnisse

Das folgende Beispiel gibt ein Verzeichnis-Handle mit dem angegebenen Namen zurck. Wenn das Verzeichnis nicht existiert, wird es erstellt.

const dirName = "directoryToGetName";

// assuming we have a directory handle: 'currentDirHandle'
const subDir = await currentDirHandle.getDirectoryHandle(dirName, {
  create: true,
});

Die folgende asynchrone Funktion verwendet resolve(), um den Pfad zu einer ausgewhlten Datei relativ zu einem angegebenen Verzeichnis-Handle zu ermitteln.

async function returnPathDirectories(directoryHandle) {
  // Get a file handle by showing a file picker:
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // User canceled, or otherwise failed to open a file.
    return;
  }

  // Check if handle exists inside our directory handle
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // Not inside directory handle
  } else {
    // relativePaths is an array of names, giving the relative path

    for (const name of relativePaths) {
      // log each entry
      console.log(name);
    }
  }
}

In Dateien schreiben

Die folgende asynchrone Funktion ffnet die Dateiauswahl zum Speichern, die nach Auswahl einer Datei ein FileSystemFileHandle zurckgibt. Anschlieend wird mithilfe der Methode FileSystemFileHandle.createWritable() ein beschreibbarer Stream erstellt.

Ein benutzerdefinierter Blob wird dann in den Stream geschrieben, der anschlieend geschlossen wird.

async function saveFile() {
  // create a new handle
  const newHandle = await window.showSaveFilePicker();

  // create a FileSystemWritableFileStream to write to
  const writableStream = await newHandle.createWritable();

  // write our file
  await writableStream.write(imgBlob);

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

Im Folgenden werden verschiedene Beispiele fr Optionen gezeigt, die an die Methode write() bergeben werden knnen.

// just pass in the data (no options)
writableStream.write(data);

// writes the data to the stream from the determined position
writableStream.write({ type: "write", position, data });

// updates the current file cursor offset to the position specified
writableStream.write({ type: "seek", position });

// resizes the file to be size bytes long
writableStream.write({ type: "truncate", size });

Dateien im OPFS synchron lesen und schreiben

Dieses Beispiel liest und schreibt eine Datei synchron in das origin private file system.

Die folgende asynchrone Event-Handler-Funktion befindet sich in einem Web Worker. Beim Empfang einer Nachricht vom Haupt-Thread fhrt sie Folgendes aus:

• Sie erstellt ein synchrones Datei-Zugriffs-Handle.
• Sie ermittelt die Gre der Datei und erstellt einen ArrayBuffer, um sie aufzunehmen.
• Sie liest den Dateiinhalt in den Buffer.
• Sie kodiert die Nachricht und schreibt sie an das Ende der Datei.
• Sie schreibt die nderungen dauerhaft auf den Datentrger und schliet das Zugriffs-Handle.

onmessage = async (e) => {
  // retrieve message sent to work from main script
  const message = e.data;

  // Get handle to draft file in OPFS
  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

Browser-Kompatibilitt

api.FileSystemHandle

api.FileSystemFileHandle

api.FileSystemDirectoryHandle

api.FileSystemWritableFileStream

api.FileSystemSyncAccessHandle

Siehe auch

• Die File System Access API: Zugriff auf lokale Dateien vereinfachen
• Das origin private file system