File System API

Diese API ermöglicht die Interaktion mit Dateien auf dem lokalen Gerät eines Benutzers oder auf einem benutzerzugänglichen Netzwerk-Dateisystem. Die Hauptfunktionen dieser API beinhalten das Lesen von Dateien, das Schreiben oder Speichern von Dateien und den Zugriff auf die Verzeichnisstruktur.

Der Großteil der Interaktion mit Dateien und Verzeichnissen erfolgt über Handles. Eine übergeordnete FileSystemHandle Klasse definiert zwei untergeordnete Klassen: FileSystemFileHandle und FileSystemDirectoryHandle, für Dateien beziehungsweise Verzeichnisse.

Die Handles repräsentieren eine Datei oder ein Verzeichnis auf dem System des Benutzers. Sie können zuerst auf diese zugreifen, indem Sie dem Benutzer einen Datei- oder Verzeichnisauswahldialog anzeigen, indem Sie Methoden wie window.showOpenFilePicker() und window.showDirectoryPicker() verwenden. Sobald diese aufgerufen werden, präsentiert sich der Dateiauswahldialog, und der Benutzer wählt entweder eine Datei oder ein Verzeichnis aus. Sobald dies erfolgreich ist, wird ein Handle zurückgegeben.

Sie können auch über die folgenden 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 Sie verwenden (siehe den Abschnitt Schnittstellen für spezifische Details). Sie können dann auf Datei-Daten oder Informationen (einschließlich untergeordneter Elemente) des ausgewählten Verzeichnisses zugreifen. Diese API eröffnet potenzielle Funktionalitäten, die dem Web bislang fehlen. Dennoch stand Sicherheit bei der Gestaltung der API an oberster Stelle, und der Zugriff auf Datei-/Verzeichnisdaten ist untersagt, es sei denn, der Benutzer erlaubt es ausdrücklich (beachten Sie, dass dies nicht für das Origin private file system gilt, da es für den Benutzer nicht sichtbar ist).

Das Origin private file system (OPFS) ist ein Speichersystem, das als Teil der File System API bereitgestellt wird und privat für den Ursprung der Seite ist und für den Benutzer nicht sichtbar ist wie das reguläre Dateisystem. Es bietet Zugang zu einer speziellen Art von Datei, die hochoptimiert für Leistung ist und In-Place-Schreibzugriff auf ihren Inhalt bietet.

Die folgenden sind einige mögliche Anwendungsfälle:

• Apps mit persistentem Uploader

  • Wenn eine Datei oder ein Verzeichnis zum Hochladen ausgewählt wird, können Sie die Datei in einen lokalen Sandbox kopieren und datenweise hochladen.
  • Die App kann den Upload nach einer Unterbrechung wie dem Schließen oder Abstürzen des Browsers, Verbindungsunterbrechungen 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 expandiert diese lokal in eine Verzeichnisstruktur.
  • Die App lädt Ressourcen im Hintergrund vor, sodass der Benutzer zur nächsten Aufgabe oder Spielebene übergehen kann, ohne auf einen Download warten zu müssen.

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

  • Die App kann Dateien direkt bearbeiten (zum Beispiel nur die ID3-/EXIF-Tags überschreiben und nicht die gesamte Datei).

• Offline-Video-Viewer

  • 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 noch den Rest des Inhalts herunterlädt oder den Download nicht abgeschlossen hat, weil Sie zu einem Zug laufen mussten).

• Offline-E-Mail-Client

  • Der Client lädt Anhänge herunter und speichert sie lokal.
  • Der Client zwischenspeichert Anhänge für späteres Hochladen.

Lesen Sie unser Origin private file system für Anweisungen zur Nutzung.

• Im Fall der asynchronen Handles verwenden Sie die FileSystemWritableFileStream Schnittstelle. Sobald die Daten, die Sie speichern möchten, im Format von Blob, String Objekt, String literal 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 write() Methode. Sie können optional auch flush() aufrufen, wenn Sie die Änderungen zu einem bestimmten Zeitpunkt auf der Festplatte festgeschrieben haben möchten (ansonsten können Sie das zugrunde liegende Betriebssystem dies verwalten lassen, wenn es dies für angebracht hält, was in den meisten Fällen in Ordnung sein sollte).

FileSystemChangeRecord Experimentell

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

FileSystemHandle

Ein Objekt, das einen Datei- oder Verzeichniseintrag darstellt. Mehrere Handles können denselben Eintrag repräsentieren. In den meisten Fällen arbeiten Sie nicht direkt mit FileSystemHandle, sondern eher mit seinen untergeordneten Schnittstellen FileSystemFileHandle und FileSystemDirectoryHandle.

FileSystemFileHandle

Bietet ein Handle zu einem Dateisystemeintrag.

FileSystemDirectoryHandle

Bietet ein Handle zu einem Dateisystemverzeichnis.

FileSystemObserver Experimentell

Bietet einen Mechanismus zum Beobachten von Änderungen an ausgewählten Dateien oder Verzeichnissen.

FileSystemSyncAccessHandle

Bietet einen synchronen Handle zu einem Dateisystemeintrag, der direkt auf einer einzelnen Datei auf der Festplatte operiert. Die synchrone Natur der Datei-Lese- und Schreibvorgänge bietet eine höhere Leistung für kritische Methoden in Kontexte, in denen asynchrone Operationen mit hohem Aufwand verbunden sind, z.B. 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 komfortablen Methoden, das auf einer einzelnen Datei auf der Festplatte operiert.

Window.showDirectoryPicker()

Zeigt einen Verzeichniswähler an, der es dem Benutzer ermöglicht, ein Verzeichnis auszuwählen.

Window.showOpenFilePicker()

Zeigt einen Dateiauswahldialog an, der es einem Benutzer ermöglicht, eine Datei oder mehrere Dateien auszuwählen.

Window.showSaveFilePicker()

Zeigt einen Dateiauswahldialog an, der es einem Benutzer ermöglicht, eine Datei zu speichern.

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 eine Referenz zu einem FileSystemDirectoryHandle Objekt zu erhalten, das den Zugriff auf ein Verzeichnis und dessen Inhalt im origin private file system ermöglicht. Gibt ein Promise zurück, das mit einem FileSystemDirectoryHandle Objekt erfüllt wird.

Der untenstehende Code ermöglicht es dem Benutzer, eine Datei aus dem Dateiauswahldialog auszuwä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 präsentiert einen Dateiauswahldialog und verwendet, sobald eine Datei ausgewählt ist, die Methode getFile(), um deren 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();
}

Das folgende Beispiel gibt ein Verzeichnishandle mit dem angegebenen Namen zurück. Wenn das Verzeichnis nicht existiert, wird es erstellt.

const dirName = "directoryToGetName";

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

Die folgende asynchrone Funktion verwendet resolve(), um den Pfad zu einer ausgewä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 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);
    }
  }
}

Die folgende asynchrone Funktion öffnet den Dialog zum Speichern einer Datei, der ein FileSystemFileHandle zurückgibt, sobald eine Datei ausgewählt wurde. Ein schreibbarer Stream wird dann mithilfe der Methode FileSystemFileHandle.createWritable() erstellt.

Ein benutzerdefinierter 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 Beispiele zeigen verschiedene 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 });

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

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

• Erstellt sie ein synchrones Datei-Zugriffshandle.
• Erfasst sie die Größe der Datei und erstellt ein ArrayBuffer, um sie zu enthalten.
• Liest sie den Dateiinhalte in den Puffer.
• Kodiert sie die Nachricht und schreibt sie ans Ende der Datei.
• Sichert sie die Änderungen auf der Festplatte und schließt das 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();
};

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