File System API

Konzepte und Nutzung

Diese API ermöglicht die Interaktion mit Dateien auf einem lokalen Gerät des Nutzers oder auf einem benutzerzugänglichen Netzwerk-Dateisystem. Die Kernfunktionen dieser API umfassen 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 definiert zwei Kindklassen: FileSystemFileHandle und FileSystemDirectoryHandle für Dateien beziehungsweise Verzeichnisse.

Die Handles repräsentieren eine Datei oder ein Verzeichnis auf dem System des Nutzers. Sie können zunächst auf sie zugreifen, indem Sie dem Nutzer einen Datei- oder Verzeichnisauswahldialog anzeigen, wobei Methoden wie window.showOpenFilePicker() und window.showDirectoryPicker() verwendet werden. Sobald diese aufgerufen werden, erscheint der Dateiauswahldialog, und der Nutzer wählt entweder eine Datei oder ein Verzeichnis aus. Nach erfolgreicher Auswahl wird ein Handle zurückgegeben.

Sie können auch durch 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 Funktionalität, und es gibt einige Unterschiede je nachdem, welches verwendet wird (siehe den Abschnitt Interfaces für spezifische Details). Sie können dann auf Dateidaten oder Informationen (einschließlich der Kinder) des ausgewählten Verzeichnisses zugreifen. Diese API eröffnet potenzielle Funktionen, die dem Web bisher gefehlt haben. Dennoch war die Sicherheit bei der Gestaltung der API von größter Bedeutung, und der Zugriff auf Datei-/Verzeichnisdaten ist nicht erlaubt, es sei denn, der Nutzer genehmigt ihn ausdrücklich (beachten Sie, dass dies nicht der Fall beim Origin-private Dateisystem ist, da es für den Nutzer nicht sichtbar ist).

Origin-private Dateisystem

Das Origin-private Dateisystem (OPFS) ist ein Speicherendpunkt, der als Teil der File System API bereitgestellt wird, der exklusiv für den Ursprung der Seite ist und dem Nutzer nicht sichtbar ist wie das reguläre Dateisystem. Es bietet Zugriff auf eine spezielle Art von Datei, die für Leistung hochoptimiert ist und unmittelbaren Schreibzugriff auf ihren Inhalt bietet.

Folgende Anwendungsfälle sind möglich:

• Apps mit persistentem Uploader

  • Wenn eine Datei oder ein Verzeichnis zum Hochladen ausgewählt wird, können Sie die Datei in ein lokales Sandbox kopieren und Stück für Stück hochladen.
  • Die App kann Uploads nach einer Unterbrechung, wie dem Schließen des Browsers oder einem Absturz, einer unterbrochenen Verbindung oder dem Herunterfahren des Computers, neu starten.

• Videospiel- oder andere Apps mit vielen Medienressourcen

  • Die App lädt ein oder mehrere große Tarballs herunter und entpackt sie lokal in eine Verzeichnisstruktur.
  • Die App lädt Ressourcen im Hintergrund vor, sodass der Nutzer ohne Wartezeiten zur nächsten Aufgabe oder Spielebene wechseln kann.

• Audio- oder Fotoeditor mit Offline-Zugriff oder lokalem Cache (ideal für Leistung und Geschwindigkeit)

  • Die App kann In-Place in Dateien schreiben (zum Beispiel nur die ID3-/EXIF-Tags überschreiben und nicht die gesamte Datei).

• Offline-Videobetrachter

  • Die App kann große Dateien (>1GB) für die spätere Ansicht herunterladen.
  • Die App kann auf teilweise heruntergeladene Dateien zugreifen (sodass Sie das erste Kapitel Ihrer DVD ansehen können, selbst wenn die App den Rest der Inhalte noch herunterlädt oder der Download nicht abgeschlossen wurde, weil Sie einen Zug erwischen mussten).

• Offline-Webmail-Client

  • Der Client lädt Anhänge herunter und speichert sie lokal.
  • Der Client cached Anhänge für späteren Upload.

Lesen Sie unseren Origin-private Dateisystem für Anleitungen, wie es verwendet wird.

Dateien speichern

• Im Fall von asynchronen Handles verwenden Sie die FileSystemWritableFileStream-Schnittstelle. Sobald die Daten, die Sie speichern möchten, in einem Format wie Blob, String, Zeichenfolgenliteral oder buffer vorliegen, können Sie einen Stream öffnen und die Daten in eine 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(). Sie können optional auch flush() aufrufen, wenn Sie die Änderungen zu einem bestimmten Zeitpunkt auf die Festplatte übertragen möchten (ansonsten können Sie das zugrunde liegende Betriebssystem dies verwalten lassen, wenn es dafür vorgesehen ist, was in den meisten Fällen in Ordnung sein sollte).

Schnittstellen

FileSystemChangeRecord

Enthält Details zu einer einzelnen Änderung, die von einem FileSystemObserver beobachtet wurde.

FileSystemHandle

Ein Objekt, das einen Datei- oder Verzeichniseintrag repräsentiert. Mehrere Handles können denselben Eintrag repräsentieren. In der Regel arbeiten Sie nicht direkt mit FileSystemHandle, sondern mit dessen Kind-Schnittstellen FileSystemFileHandle und FileSystemDirectoryHandle.

FileSystemFileHandle

Bietet ein Handle zu einem Dateisystemeintrag.

FileSystemDirectoryHandle

Bietet ein Handle zu einem Dateisystemverzeichnis.

FileSystemObserver

Bietet einen Mechanismus zur Beobachtung von Änderungen an ausgewählten Dateien oder Verzeichnissen.

FileSystemSyncAccessHandle

Bietet ein synchrones Handle zu einem Dateisystemeintrag, das In-Place auf eine einzelne Datei auf der Festplatte arbeitet. Die synchrone Natur der Datei-Reads und -Writes ermöglicht eine höhere Leistung für kritische Methoden in Kontexte, wo asynchrone Operationen mit hohem Overhead verbunden sind, zum Beispiel WebAssembly. Diese Klasse ist nur innerhalb dedizierter Web Workers für Dateien im origin private file system zugänglich.

FileSystemWritableFileStream

Ein WritableStream-Objekt mit zusätzlichen Komfortmethoden, das auf eine einzelne Datei auf der Festplatte arbeitet.

Erweiterungen zu anderen Schnittstellen

Window.showDirectoryPicker()

Zeigt einen Verzeichnisauswahldialog an, der dem Nutzer die Auswahl eines Verzeichnisses ermöglicht.

Window.showOpenFilePicker()

Zeigt einen Dateiauswahldialog an, der einem Nutzer die Auswahl einer oder mehrerer Dateien ermöglicht.

Window.showSaveFilePicker()

Zeigt einen Dateiauswahldialog an, der einem Nutzer das Speichern einer Datei ermöglicht.

DataTransferItem.getAsFileSystemHandle()

Gibt ein Promise zurück, das mit einem FileSystemFileHandle erfüllt wird, wenn das gezogene Element eine Datei ist, oder mit einem FileSystemDirectoryHandle erfüllt wird, wenn das gezogene Element ein Verzeichnis ist.

StorageManager.getDirectory()

Wird verwendet, um einen Verweis auf ein FileSystemDirectoryHandle-Objekt zu erhalten, das den Zugriff auf ein Verzeichnis und dessen Inhalte ermöglicht, die im origin private file system gespeichert sind. Gibt ein Promise zurück, das mit einem FileSystemDirectoryHandle-Objekt erfüllt wird.

Beispiele

Zugriff auf Dateien

Der folgende Code erlaubt es dem Nutzer, eine Datei aus dem Dateiauswahldialog zu wählen.

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 einen Dateiauswahldialog an und verwendet, sobald eine Datei ausgewählt ist, die getFile()-Methode, 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 einen Verzeichnishandle mit dem angegebenen Namen zurück. 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 gewählten 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 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);
    }
  }
}

Schreiben in Dateien

Die folgende asynchrone Funktion öffnet den Speicherauswahldialog, der ein FileSystemFileHandle zurückgibt, sobald eine Datei ausgewählt wird. Ein beschreibbarer Stream wird dann mithilfe der FileSystemFileHandle.createWritable()-Methode erstellt.

Ein vom Nutzer definiertes Blob wird dann in den Stream geschrieben, der anschließend 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 zeigen verschiedene Beispiele von Optionen, die an die write()-Methode übergeben werden können.

// 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 in OPFS

Dieses Beispiel liest und schreibt synchron eine Datei im Origin-private Dateisystem.

Die folgende asynchrone Ereignishandlerfunktion ist innerhalb eines Web Workers enthalten. Beim Empfang einer Nachricht vom Haupt-Thread:

• Erstellt es einen synchronen Datei-Zugriffshandle.
• Ermittelt die Größe der Datei und erstellt einen ArrayBuffer, um diese zu enthalten.
• Liest den Dateiinhalte in den Puffer.
• Kodiert die Nachricht und schreibt sie ans Ende der Datei.
• Sichert die Änderungen auf der Festplatte und schließt 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-Kompatibilität

api.FileSystemHandle

api.FileSystemFileHandle

api.FileSystemDirectoryHandle

api.FileSystemWritableFileStream

api.FileSystemSyncAccessHandle

Siehe auch

• Die File System Access API: Vereinfachung des Zugriffs auf lokale Dateien
• Das origin-private Dateisystem