File System API

Diese API ermöglicht die Interaktion mit Dateien auf einem lokalen Gerät des Benutzers oder auf einem benutzerzugänglichen Netzwerkdateisystem. Die Kernfunktionalität 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 wird durch Handles erreicht. Eine übergeordnete Klasse FileSystemHandle hilft, zwei untergeordnete Klassen zu definieren: FileSystemFileHandle und FileSystemDirectoryHandle, für Dateien bzw. Verzeichnisse.

Die Handles repräsentieren eine Datei oder ein Verzeichnis auf dem System des Benutzers. Sie können zunächst auf sie zugreifen, indem Sie dem Benutzer mithilfe von Methoden wie window.showOpenFilePicker() und window.showDirectoryPicker() einen Datei- oder Verzeichnisauswähler anzeigen. Sobald diese aufgerufen werden, präsentiert sich der Dateiauswähler und der Benutzer wählt entweder eine Datei oder ein Verzeichnis aus. Wenn dies erfolgreich geschieht, wird ein Handle zurückgegeben.

Sie können auch über folgende Wege 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, abhängig davon, welches Sie verwenden (siehe den Abschnitt Schnittstellen für spezifische Details). Danach können Sie auf Datei-Daten oder Informationen (einschließlich Kinder) des ausgewählten Verzeichnisses zugreifen. Diese API eröffnet potenziell fehlende Funktionalitäten im Web. Dennoch war Sicherheit bei der Gestaltung der API von größter Bedeutung, und der Zugriff auf Datei-/Verzeichnisdaten ist nur dann erlaubt, wenn der Benutzer dies ausdrücklich zulässt (beachten Sie, dass dies nicht der Fall beim origin private file system ist, da es für den Benutzer nicht sichtbar ist).

Das Origin Private File System (OPFS) ist ein Speichermedium, das als Teil der File System API bereitgestellt wird, das nur dem Ursprung der Seite zugeordnet und für den Benutzer nicht sichtbar ist, wie das reguläre Dateisystem. Es bietet Zugang zu einer speziellen Art von Datei, die hochgradig auf Leistung optimiert ist und einen direkten Schreibzugriff auf ihre Inhalte ermöglicht.

Die folgenden sind einige mögliche Anwendungsfälle:

• Apps mit dauerhaftem Uploader

  • Wenn eine Datei oder ein Verzeichnis zum Hochladen ausgewählt wird, können Sie die Datei in ein lokales Sandbox kopieren und stückweise hochladen.
  • Die App kann Uploads nach einer Unterbrechung neu starten, z.B. wenn der Browser geschlossen oder abgestürzt ist, die Verbindung unterbrochen wurde oder der Computer heruntergefahren wurde.

• Video- oder andere Apps mit vielen Mediendateien

  • Die App lädt ein oder mehrere große Tarballs herunter und entpackt sie lokal in eine Verzeichnisstruktur.
  • Die App ruft im Hintergrund Assets vorab ab, damit der Benutzer zur nächsten Aufgabe oder Spielebene übergehen kann, ohne auf einen Download zu warten.

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

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

• Offline-Video-Viewer

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

• Offline-Webmail-Client

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

Lesen Sie unseren 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 eine Datei mit der write()-Methode. Optional können Sie auch flush() aufrufen, wenn Sie möchten, dass die Änderungen zu einem bestimmten Zeitpunkt auf die Festplatte geschrieben werden (andernfalls können Sie dem zugrunde liegenden Betriebssystem überlassen, dies zu tun, wenn es dies für angemessen hält, was in den meisten Fällen in Ordnung sein sollte).

FileSystemHandle

Ein Objekt, das einen Datei- oder Verzeichniseintrag repräsentiert. Mehrere Handles können denselben Eintrag repräsentieren. Zum größten Teil arbeiten Sie nicht direkt mit FileSystemHandle, sondern vielmehr mit den untergeordneten Schnittstellen FileSystemFileHandle und FileSystemDirectoryHandle.

FileSystemFileHandle

Bietet einen Handle zu einem Dateisystemeintrag.

FileSystemDirectoryHandle

Bietet einen Handle zu einem Verzeichnis des Dateisystems.

FileSystemSyncAccessHandle

Bietet einen synchronen Handle zu einem Dateisystemeintrag, der direkt auf eine einzelne Datei auf der Festplatte arbeitet. Die synchrone Natur des Lesens und Schreibens ermöglicht eine höhere Leistung für kritische Methoden in Kontexten, in denen asynchrone Operationen mit hohem Overhead verbunden sind, z.B. WebAssembly. Diese Klasse ist nur in dedizierten Web Workers für Dateien innerhalb des origins private file system zugänglich.

FileSystemWritableFileStream

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

Window.showDirectoryPicker()

Zeigt einen Verzeichnisauswähler an, mit dem der Benutzer ein Verzeichnis auswählen kann.

Window.showOpenFilePicker()

Zeigt einen Dateiauswähler an, mit dem ein Benutzer eine oder mehrere Dateien auswählen kann.

Window.showSaveFilePicker()

Zeigt einen Dateiauswähler an, mit dem ein Benutzer eine Datei speichern kann.

DataTransferItem.getAsFileSystemHandle()

Gibt ein FileSystemFileHandle zurück, wenn das gezogene Element eine Datei ist, oder ein FileSystemDirectoryHandle, wenn das gezogene Element ein Verzeichnis ist.

StorageManager.getDirectory()

Wird verwendet, um eine Referenz zu einem FileSystemDirectoryHandle-Objekt zu erhalten, das 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 folgende Code ermöglicht dem Benutzer, eine Datei aus dem Dateiauswähler 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 Dateiauswähler und verwendet, sobald eine Datei ausgewählt ist, die getFile()-Methode, um die Inhalte 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 Dateispeicherauswähler, der ein FileSystemFileHandle zurückgibt, sobald eine Datei ausgewählt wurde. Ein beschreibbarer 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 in 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 synchron eine Datei im origin private file system.

Die folgende asynchrone Ereignis-Handlerfunktion ist innerhalb eines Web Workers enthalten. Beim Empfang einer Nachricht von dem Haupt-Thread:

• Erstellt einen synchronen Datei-Zugriffshandle.
• Bestimmt die Größe der Datei und erstellt einen ArrayBuffer, um den Inhalt aufzunehmen.
• Liest den Dateiinhalt in den Puffer.
• Codiert die Nachricht und schreibt sie an das Ende der Datei.
• Speichert 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();
};

• The File System Access API: simplifying access to local files
• The origin private file system