File System API

Konzepte und Nutzung

Diese API ermglicht die Interaktion mit Dateien auf einem lokalen Gert des Benutzers oder auf einem vom Benutzer zugnglichen Netzwerkdateisystem. Die Kernfunktionalitt dieser API umfasst das Lesen von Dateien, das Schreiben oder Speichern von Dateien und den Zugriff auf die Verzeichnisstruktur.

Die meiste Interaktion mit Dateien und Verzeichnissen erfolgt ber Handles. Eine bergeordnete Klasse FileSystemHandle hilft bei der Definition von zwei abgeleiteten Klassen: FileSystemFileHandle und FileSystemDirectoryHandle, fr Dateien bzw. Verzeichnisse.

Die Handles reprsentieren eine Datei oder ein Verzeichnis auf dem System des Benutzers. Sie knnen zuerst auf sie zugreifen, indem Sie dem Benutzer einen Datei- oder Verzeichnisauswahldialog mit Methoden wie window.showOpenFilePicker() und window.showDirectoryPicker() anzeigen. Sobald diese aufgerufen werden, prsentiert sich der Dateiauswahldialog und der Benutzer kann entweder eine Datei oder ein Verzeichnis auswhlen. Nachdem dies erfolgreich passiert ist, wird ein Handle zurckgegeben.

Sie knnen auch ber folgende Methoden auf Datei-Handles zugreifen:

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

Jedes Handle bietet seine eigene Funktionalitt, und es gibt einige Unterschiede, je nachdem welches verwendet wird (siehe den Abschnitt Schnittstellen fr spezifische Details). Sie knnen dann auf Dateidaten oder Informationen (einschlielich untergeordneter Elemente) des ausgewhlten Verzeichnisses zugreifen. Diese API erffnet Funktionalitten, die dem Web bisher fehlten. Dennoch stand die Sicherheit bei der Gestaltung der API im Vordergrund, und der Zugriff auf die Datei-/Verzeichnisedaten ist nur mglich, wenn der Benutzer dies ausdrcklich gestattet (zu beachten ist, dass dies nicht auf das Origin private file system zutrifft, da es fr den Benutzer nicht sichtbar ist).

Origin private file system

Das Origin private file system (OPFS) ist ein Speicherendpunkt, der als Teil der File System API bereitgestellt wird. Es ist der Herkunft der Seite privat und nicht wie das regulre Dateisystem fr den Benutzer sichtbar. Es bietet Zugriff auf eine spezielle Art von Datei, die hochoptimiert fr Leistung ist und einen direkten Schreibzugriff auf ihren Inhalt ermglicht.

Die folgenden Anwendungsflle sind mglich:

• Apps mit persistentem Uploader

  • Wenn eine Datei oder ein Verzeichnis zum Hochladen ausgewhlt wird, knnen Sie die Datei in einen lokalen Sandkasten kopieren und stckweise hochladen.
  • Die App kann Uploads nach einer Unterbrechung neu starten, z.B. wenn der Browser geschlossen wird oder abstrzt, die Verbindung unterbrochen wird oder der Computer heruntergefahren wird.

• Videospiel oder andere Apps mit vielen Medienressourcen

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

• Audio- oder Fotobearbeitungs-Apps mit Offline-Zugriff oder lokaler Cache (ideal fr Leistung und Geschwindigkeit)

  • Die App kann Dateien direkt speichern (z.B. nur die ID3/EXIF-Tags berschreiben und nicht die gesamte Datei).

• Offline-Videoanzeiger

  • Die App kann groe Dateien (>1GB) fr die sptere Anzeige herunterladen.
  • Die App kann auf teilweise heruntergeladene Dateien zugreifen (damit Sie das erste Kapitel Ihrer DVD ansehen knnen, selbst wenn die App den Rest des Inhalts noch herunterldt oder den Download nicht abgeschlossen hat, weil Sie zum Zugrennen mussten).

• Offline-Webmail-Client

  • Der Client ldt Anhnge herunter und speichert sie lokal.
  • Der Client cached Anhnge fr den spteren Upload.

Lesen Sie unseren Origin private file system fr Anleitungen zur Nutzung.

Dateien speichern

• Im Fall von asynchronen Handles verwenden Sie die FileSystemWritableFileStream-Schnittstelle. Sobald die Daten, die Sie speichern mchten, im Format eines Blob, String-Objekts, Zeichenfolgenliterals oder buffer vorliegen, knnen Sie einen Stream ffnen und die Daten in einer Datei speichern. Dies kann die bestehende Datei oder eine neue Datei sein.
• Im Fall des synchronen FileSystemSyncAccessHandle schreiben Sie nderungen an einer Datei mit der Methode write(). Optional knnen Sie auch flush() aufrufen, wenn Sie mchten, dass die nderungen zu einem bestimmten Zeitpunkt auf die Festplatte geschrieben werden (anderenfalls knnen Sie dies dem zugrundeliegenden Betriebssystem berlassen, das dies nach Bedarf bernimmt, was in den meisten Fllen in Ordnung sein sollte).

Schnittstellen

FileSystemChangeRecord

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

FileSystemHandle

Ein Objekt, das einen Datei- oder Verzeichniseintrag darstellt. Mehrere Handles knnen denselben Eintrag reprsentieren. Meistens arbeiten Sie nicht direkt mit FileSystemHandle, sondern eher mit seinen abgeleiteten Schnittstellen FileSystemFileHandle und FileSystemDirectoryHandle.

FileSystemFileHandle

Bietet einen Handle zu einem Dateisystemeintrag.

FileSystemDirectoryHandle

Bietet einen Handle zu einem Dateisystemverzeichnis.

FileSystemObserver

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

FileSystemSyncAccessHandle

Bietet einen synchronen Handle zu einem Dateisystemeintrag, der vor Ort auf einer einzelnen Datei auf der Festplatte arbeitet. Die synchrone Natur der Dateioperationen ermglicht eine hhere Leistung fr kritische Methoden in Kontexten, in denen asynchrone Operationen mit hohem Overhead verbunden sind, z.B. WebAssembly. Diese Klasse ist nur innerhalb dedizierter Web Workers fr Dateien innerhalb des origin private file system zugnglich.

FileSystemWritableFileStream

Ein WritableStream-Objekt mit zustzlichen Komfortmethoden, das auf einer einzelnen Datei auf der Festplatte arbeitet.

Erweiterungen zu anderen Schnittstellen

Window.showDirectoryPicker()

Zeigt einen Verzeichnisauswahldialog an, der es dem Benutzer erlaubt, ein Verzeichnis auszuwhlen.

Window.showOpenFilePicker()

Zeigt einen Dateiauswahldialog an, der es dem Benutzer erlaubt, eine oder mehrere Dateien auszuwhlen.

Window.showSaveFilePicker()

Zeigt einen Dateiauswahldialog an, der es dem Benutzer erlaubt, eine Datei zu speichern.

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 Element ein Verzeichnis ist.

StorageManager.getDirectory()

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

Beispiele

Zugriff auf Dateien

Der untenstehende Code erlaubt es dem Benutzer, eine Datei aus dem Dateiauswahldialog 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 prsentiert einen Dateiauswahldialog und verwendet nach der Auswahl einer Datei die Methode getFile(), um den Inhalt zu erhalten.

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 Verzeichnishandle mit dem angegebenen Namen zurck. Falls 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 Verzeichnishandle zu finden.

async function returnPathDirectories(directoryHandle) {
  // Get a file handle by showing a file picker:
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // User cancelled, 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);
    }
  }
}

Schreiben in Dateien

Die folgende asynchrone Funktion ffnet den Datei-Speicher-Dialog, der ein FileSystemFileHandle zurckgibt, sobald eine Datei ausgewhlt wird. Anschlieend wird ein schreibbarer Stream mit der Methode FileSystemFileHandle.createWritable() 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();
}

Die folgenden Beispiele zeigen verschiedene Optionen, die in 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 });

Synchrones Lesen und Schreiben von Dateien im OPFS

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

Der folgende asynchrone Ereignishandler befindet sich in einem Web Worker. Beim Empfang einer Nachricht vom Hauptthread:

• Erstellt er einen synchronen Dateizugriffshandle.
• Ermittelt die Gre der Datei und erstellt einen ArrayBuffer, um sie zu enthalten.
• Liest den Dateiinhalte in den Puffer.
• Codiert die Nachricht und schreibt sie an das Ende der Datei.
• Speichert die nderungen auf der Festplatte und schliet den Zugriffshandle.

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: Vereinfachter Zugriff auf lokale Dateien
• Das origin private file system