Die File System Access API: vereinfachter Zugriff auf lokale Dateien

Mit der File System Access API können Web-Apps Änderungen direkt in Dateien und Ordnern auf dem Gerät des Nutzers lesen oder speichern.

Pete LePage

Thomas Steiner

Was ist die File System Access API?

Mit der File System Access API können Entwickler leistungsstarke Webanwendungen erstellen, die mit Dateien auf dem lokalen Gerät des Nutzers interagieren, z. B. IDEs, Foto- und Videoeditoren oder Texteditoren. Nachdem ein Nutzer einer Webanwendung Zugriff gewährt hat, kann er mit dieser API Änderungen direkt in Dateien und Ordnern auf seinem Gerät lesen oder speichern. Neben dem Lesen und Schreiben von Dateien bietet die File System Access API die Möglichkeit, ein Verzeichnis zu öffnen und seinen Inhalt aufzulisten.

Wenn Sie schon einmal mit dem Lesen und Schreiben von Dateien gearbeitet haben, ist vieles von dem, was ich gleich erläutern werde, für Sie bereits bekannt. Ich empfehle Ihnen trotzdem, sie zu lesen, da nicht alle Systeme gleich sind.

Die File System Access API wird von den meisten Chromium-Browsern unter Windows, macOS, ChromeOS und Linux unterstützt. Eine bemerkenswerte Ausnahme ist Brave, wo es derzeit nur mit einem Flag verfügbar ist. An der Unterstützung für Android wird im Rahmen von crbug.com/1011535 gearbeitet.

File System Access API verwenden

Um die Leistungsfähigkeit und Nützlichkeit der File System Access API zu demonstrieren, habe ich einen Texteditor für einzelne Dateien geschrieben. Sie können damit eine Textdatei öffnen, bearbeiten, die Änderungen auf dem Laufwerk speichern oder eine neue Datei erstellen und die Änderungen auf dem Laufwerk speichern. Es ist nichts Besonderes, aber es bietet genug, um die Konzepte zu verstehen.

Unterstützte Browser

Funktionserkennung

Wenn Sie wissen möchten, ob die File System Access API unterstützt wird, prüfen Sie, ob die gewünschte Auswahlmethode vorhanden ist.

if ('showOpenFilePicker' in self) {
  // The `showOpenFilePicker()` method of the File System Access API is supported.
}

Ausprobieren

In der Demo für den Texteditor können Sie sich die File System Access API in Aktion ansehen.

Datei aus dem lokalen Dateisystem lesen

Der erste Anwendungsfall, den ich angehen möchte, besteht darin, den Nutzer aufzufordern, eine Datei auszuwählen, und diese Datei dann vom Laufwerk zu öffnen und zu lesen.

Nutzer nach einer Datei zum Lesen fragen

Der Einstiegspunkt in die File System Access API ist window.showOpenFilePicker(). Wenn die Funktion aufgerufen wird, wird ein Dialogfeld für die Dateiauswahl angezeigt und der Nutzer wird aufgefordert, eine Datei auszuwählen. Nachdem eine Datei ausgewählt wurde, gibt die API ein Array von Datei-Handles zurück. Mit einem optionalen options-Parameter können Sie das Verhalten der Dateiauswahl beeinflussen, z. B. indem Sie dem Nutzer erlauben, mehrere Dateien, Verzeichnisse oder verschiedene Dateitypen auszuwählen. Ohne angegebene Optionen kann der Nutzer mit der Dateiauswahl eine einzelne Datei auswählen. Das ist perfekt für einen Texteditor.

Wie viele andere leistungsstarke APIs muss showOpenFilePicker() in einem sicheren Kontext und innerhalb einer Nutzergeste aufgerufen werden.

let fileHandle;
butOpenFile.addEventListener('click', async () => {
  // Destructure the one-element array.
  [fileHandle] = await window.showOpenFilePicker();
  // Do something with the file handle.
});

Sobald der Nutzer eine Datei ausgewählt hat, gibt showOpenFilePicker() ein Array von Handles zurück, in diesem Fall ein Array mit einem Element mit einer FileSystemFileHandle, die die Eigenschaften und Methoden enthält, die für die Interaktion mit der Datei erforderlich sind.

Es ist hilfreich, einen Verweis auf den Dateihandle zu speichern, damit er später verwendet werden kann. Sie müssen Änderungen an der Datei speichern oder andere Dateivorgänge ausführen.

Datei aus dem Dateisystem lesen

Nachdem Sie einen Handle für eine Datei haben, können Sie die Eigenschaften der Datei abrufen oder auf die Datei selbst zugreifen. Ich lese mir den Inhalt jetzt erst einmal durch. Wenn Sie handle.getFile() aufrufen, wird ein File-Objekt zurückgegeben, das einen Blob enthält. Rufen Sie eine der Methoden (slice(), stream(), text() oder arrayBuffer()) auf, um die Daten aus dem Blob abzurufen.

const file = await fileHandle.getFile();
const contents = await file.text();

Das von FileSystemFileHandle.getFile() zurückgegebene File-Objekt ist nur lesbar, solange sich die zugrunde liegende Datei auf dem Laufwerk nicht geändert hat. Wenn die Datei auf dem Laufwerk geändert wird, kann das File-Objekt nicht mehr gelesen werden. Sie müssen getFile() noch einmal aufrufen, um ein neues File-Objekt zu erhalten, mit dem die geänderten Daten gelesen werden können.

Zusammenfassung

Wenn Nutzer auf die Schaltfläche Öffnen klicken, wird im Browser eine Dateiauswahl angezeigt. Nachdem eine Datei ausgewählt wurde, liest die App den Inhalt und speichert ihn in einer <textarea>.

let fileHandle;
butOpenFile.addEventListener('click', async () => {
  [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  const contents = await file.text();
  textArea.value = contents;
});

Datei in das lokale Dateisystem schreiben

Im Texteditor gibt es zwei Möglichkeiten, eine Datei zu speichern: Speichern und Unter diesem Namen speichern. Mit Speichern werden die Änderungen mithilfe des zuvor abgerufenen Dateihandles in die Originaldatei zurückgeschrieben. Mit Als wird jedoch eine neue Datei erstellt, für die ein neuer Dateihandle erforderlich ist.

Neue Datei erstellen

Wenn Sie eine Datei speichern möchten, drücken Sie die Taste showSaveFilePicker(). Daraufhin wird die Dateiauswahl im Modus „Speichern“ angezeigt. Der Nutzer kann dann eine neue Datei auswählen, die gespeichert werden soll. Für den Texteditor wollte ich auch, dass automatisch eine .txt-Erweiterung hinzugefügt wird. Dazu habe ich einige zusätzliche Parameter angegeben.

async function getNewFileHandle() {
  const options = {
    types: [
      {
        description: 'Text Files',
        accept: {
          'text/plain': ['.txt'],
        },
      },
    ],
  };
  const handle = await window.showSaveFilePicker(options);
  return handle;
}

Änderungen auf dem Laufwerk speichern

Den gesamten Code zum Speichern von Änderungen an einer Datei finden Sie in meiner Texteditor-Demo auf GitHub. Die wichtigsten Dateisysteminteraktionen finden Sie unter fs-helpers.js. In seiner einfachsten Form sieht der Prozess so aus: Ich erkläre Ihnen die einzelnen Schritte.

// fileHandle is an instance of FileSystemFileHandle..
async function writeFile(fileHandle, contents) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();
  // Write the contents of the file to the stream.
  await writable.write(contents);
  // Close the file and write the contents to disk.
  await writable.close();
}

Zum Schreiben von Daten auf das Laufwerk wird ein FileSystemWritableFileStream-Objekt verwendet, eine Unterklasse von WritableStream. Erstellen Sie den Stream, indem Sie createWritable() für das Dateihandle-Objekt aufrufen. Wenn createWritable() aufgerufen wird, prüft der Browser zuerst, ob der Nutzer der Datei die Schreibberechtigung erteilt hat. Wenn die Schreibberechtigung nicht gewährt wurde, wird der Nutzer vom Browser um Erlaubnis gebeten. Wenn die Berechtigung nicht gewährt wird, wirft createWritable() eine DOMException aus und die App kann nicht in die Datei schreiben. Im Texteditor werden die DOMException-Objekte in der Methode saveFile() verarbeitet.

Die Methode write() nimmt einen String an, der für einen Texteditor erforderlich ist. Es kann aber auch eine BufferSource oder ein Blob sein. Sie können beispielsweise einen Stream direkt an das Tool weiterleiten:

async function writeURLToFile(fileHandle, url) {
  // Create a FileSystemWritableFileStream to write to.
  const writable = await fileHandle.createWritable();
  // Make an HTTP request for the contents.
  const response = await fetch(url);
  // Stream the response into the file.
  await response.body.pipeTo(writable);
  // pipeTo() closes the destination pipe by default, no need to close it.
}

Du kannst auch seek() oder truncate() im Stream eingeben, um die Datei an einer bestimmten Position zu aktualisieren oder ihre Größe zu ändern.

Vorgeschlagenen Dateinamen und Startverzeichnis angeben

In vielen Fällen möchten Sie, dass Ihre App einen Standarddateinamen oder -speicherort vorschlägt. Ein Texteditor könnte beispielsweise den Standarddateinamen Untitled Text.txt anstelle von Untitled vorschlagen. Dazu übergeben Sie eine suggestedName-Eigenschaft als Teil der showSaveFilePicker-Optionen.

const fileHandle = await self.showSaveFilePicker({
  suggestedName: 'Untitled Text.txt',
  types: [{
    description: 'Text documents',
    accept: {
      'text/plain': ['.txt'],
    },
  }],
});

Dasselbe gilt für das Standardstartverzeichnis. Wenn Sie einen Texteditor erstellen, sollten Sie das Dialogfeld zum Speichern oder Öffnen von Dateien im Standardordner documents starten. Bei einem Bildeditor sollten Sie dagegen den Standardordner pictures verwenden. Sie können ein Standardstartverzeichnis vorschlagen, indem Sie eine startIn-Eigenschaft an die Methoden showSaveFilePicker, showDirectoryPicker() oder showOpenFilePicker übergeben.

const fileHandle = await self.showOpenFilePicker({
  startIn: 'pictures'
});

Die Liste der bekannten Systemverzeichnisse:

• desktop: Das Desktopverzeichnis des Nutzers, sofern vorhanden.
• documents: Verzeichnis, in dem vom Nutzer erstellte Dokumente normalerweise gespeichert werden.
• downloads: Verzeichnis, in dem heruntergeladene Dateien normalerweise gespeichert werden.
• music: Verzeichnis, in dem Audiodateien normalerweise gespeichert werden.
• pictures: Verzeichnis, in dem normalerweise Fotos und andere Standbilder gespeichert werden.
• videos: Verzeichnis, in dem normalerweise Videos oder Filme gespeichert werden.

Neben bekannten Systemverzeichnissen können Sie auch einen vorhandenen Datei- oder Verzeichnis-Handle als Wert für startIn übergeben. Das Dialogfeld wird dann im selben Verzeichnis geöffnet.

// Assume `directoryHandle` is a handle to a previously opened directory.
const fileHandle = await self.showOpenFilePicker({
  startIn: directoryHandle
});

Zweck verschiedener Dateiauswahlen angeben

Manchmal haben Apps unterschiedliche Auswahltools für unterschiedliche Zwecke. Mit einem Rich-Text-Editor können Nutzer beispielsweise Textdateien öffnen, aber auch Bilder importieren. Standardmäßig wird jeder Dateiauswahldialog am zuletzt gespeicherten Speicherort geöffnet. Sie können das Problem umgehen, indem Sie für jede Art von Auswahlliste id-Werte speichern. Wenn eine id angegeben ist, merkt sich die Dateiauswahl ein separates zuletzt verwendetes Verzeichnis für diese id.

const fileHandle1 = await self.showSaveFilePicker({
  id: 'openText',
});

const fileHandle2 = await self.showSaveFilePicker({
  id: 'importImage',
});

Datei- oder Verzeichnis-Handle in IndexedDB speichern

Datei- und Verzeichnis-Handle sind serialisierbar. Das bedeutet, dass Sie einen Datei- oder Verzeichnis-Handle in IndexedDB speichern oder postMessage() aufrufen können, um ihn zwischen demselben Ursprung der obersten Ebene zu senden.

Wenn Sie Datei- oder Verzeichnis-Handle in IndexedDB speichern, können Sie den Status speichern oder sich merken, an welchen Dateien oder Verzeichnissen ein Nutzer gearbeitet hat. So können Sie beispielsweise eine Liste der zuletzt geöffneten oder bearbeiteten Dateien aufbewahren, beim Öffnen der App die letzte Datei wieder öffnen oder das vorherige Arbeitsverzeichnis wiederherstellen. Im Texteditor speichere ich eine Liste der fünf zuletzt geöffneten Dateien des Nutzers, sodass er wieder auf diese Dateien zugreifen kann.

Das folgende Codebeispiel zeigt das Speichern und Abrufen eines Datei- und eines Verzeichnishandles. Hier könnt ihr euch das in Aktion ansehen. (Ich verwende aus Gründen der Übersichtlichkeit die Bibliothek idb-keyval.)

import { get, set } from 'https://unpkg.com/idb-keyval@5.0.2/dist/esm/index.js';

const pre1 = document.querySelector('pre.file');
const pre2 = document.querySelector('pre.directory');
const button1 = document.querySelector('button.file');
const button2 = document.querySelector('button.directory');

// File handle
button1.addEventListener('click', async () => {
  try {
    const fileHandleOrUndefined = await get('file');
    if (fileHandleOrUndefined) {
      pre1.textContent = `Retrieved file handle "${fileHandleOrUndefined.name}" from IndexedDB.`;
      return;
    }
    const [fileHandle] = await window.showOpenFilePicker();
    await set('file', fileHandle);
    pre1.textContent = `Stored file handle for "${fileHandle.name}" in IndexedDB.`;
  } catch (error) {
    alert(error.name, error.message);
  }
});

// Directory handle
button2.addEventListener('click', async () => {
  try {
    const directoryHandleOrUndefined = await get('directory');
    if (directoryHandleOrUndefined) {
      pre2.textContent = `Retrieved directroy handle "${directoryHandleOrUndefined.name}" from IndexedDB.`;
      return;
    }
    const directoryHandle = await window.showDirectoryPicker();
    await set('directory', directoryHandle);
    pre2.textContent = `Stored directory handle for "${directoryHandle.name}" in IndexedDB.`;
  } catch (error) {
    alert(error.name, error.message);
  }
});

Gespeicherte Datei- oder Verzeichnis-Handle und Berechtigungen

Da Berechtigungen nicht immer zwischen Sitzungen beibehalten werden, sollten Sie prüfen, ob der Nutzer der Datei oder dem Verzeichnis mit queryPermission() eine Berechtigung erteilt hat. Falls nicht, rufen Sie requestPermission() an, um ihn (erneut) anzufordern. Das gilt auch für Datei- und Verzeichnis-Handle. Sie müssen fileOrDirectoryHandle.requestPermission(descriptor) bzw. fileOrDirectoryHandle.queryPermission(descriptor) ausführen.

Im Texteditor habe ich eine verifyPermission()-Methode erstellt, die prüft, ob der Nutzer bereits die Berechtigung erteilt hat, und bei Bedarf die Anfrage stellt.

async function verifyPermission(fileHandle, readWrite) {
  const options = {};
  if (readWrite) {
    options.mode = 'readwrite';
  }
  // Check if permission was already granted. If so, return true.
  if ((await fileHandle.queryPermission(options)) === 'granted') {
    return true;
  }
  // Request permission. If the user grants permission, return true.
  if ((await fileHandle.requestPermission(options)) === 'granted') {
    return true;
  }
  // The user didn't grant permission, so return false.
  return false;
}

Durch die gleichzeitige Anforderung der Schreibberechtigung mit der Leseanfrage konnte ich die Anzahl der Berechtigungsaufforderungen reduzieren. Der Nutzer sieht beim Öffnen der Datei nur eine Aufforderung und gewährt die Berechtigung zum Lesen und Schreiben.

Verzeichnis öffnen und Inhalt auflisten

Wenn Sie alle Dateien in einem Verzeichnis auflisten möchten, rufen Sie showDirectoryPicker() auf. Der Nutzer wählt in einer Auswahl ein Verzeichnis aus. Daraufhin wird FileSystemDirectoryHandle zurückgegeben, mit dem Sie die Dateien des Verzeichnisses auflisten und darauf zugreifen können. Standardmäßig haben Sie Lesezugriff auf die Dateien im Verzeichnis. Wenn Sie jedoch Schreibzugriff benötigen, können Sie { mode: 'readwrite' } an die Methode übergeben.

butDir.addEventListener('click', async () => {
  const dirHandle = await window.showDirectoryPicker();
  for await (const entry of dirHandle.values()) {
    console.log(entry.kind, entry.name);
  }
});

Wenn Sie zusätzlich mit getFile() auf jede Datei zugreifen müssen, um beispielsweise die einzelnen Dateigrößen zu erhalten, verwenden Sie await nicht für jedes Ergebnis nacheinander, sondern verarbeiten Sie alle Dateien parallel, z. B. mit Promise.all().

butDir.addEventListener('click', async () => {
  const dirHandle = await window.showDirectoryPicker();
  const promises = [];
  for await (const entry of dirHandle.values()) {
    if (entry.kind !== 'file') {
      continue;
    }
    promises.push(entry.getFile().then((file) => `${file.name} (${file.size})`));
  }
  console.log(await Promise.all(promises));
});

Dateien und Ordner in einem Verzeichnis erstellen oder darauf zugreifen

In einem Verzeichnis können Sie mit der Methode getFileHandle() bzw. getDirectoryHandle() Dateien und Ordner erstellen oder darauf zugreifen. Wenn du ein optionales options-Objekt mit dem Schlüssel create und dem booleschen Wert true oder false übergibst, kannst du festlegen, ob eine neue Datei oder ein neuer Ordner erstellt werden soll, falls sie bzw. er nicht vorhanden ist.

// In an existing directory, create a new directory named "My Documents".
const newDirectoryHandle = await existingDirectoryHandle.getDirectoryHandle('My Documents', {
  create: true,
});
// In this new directory, create a file named "My Notes.txt".
const newFileHandle = await newDirectoryHandle.getFileHandle('My Notes.txt', { create: true });

Pfad eines Elements in einem Verzeichnis auflösen

Wenn Sie mit Dateien oder Ordnern in einem Verzeichnis arbeiten, kann es hilfreich sein, den Pfad des betreffenden Elements aufzulösen. Dazu können Sie die Methode resolve() verwenden. Für die Auflösung kann das Element ein direktes oder indirektes untergeordnetes Element des Verzeichnisses sein.

// Resolve the path of the previously created file called "My Notes.txt".
const path = await newDirectoryHandle.resolve(newFileHandle);
// `path` is now ["My Documents", "My Notes.txt"]

Dateien und Ordner in einem Verzeichnis löschen

Wenn Sie Zugriff auf ein Verzeichnis erhalten haben, können Sie die darin enthaltenen Dateien und Ordner mit der Methode removeEntry() löschen. Bei Ordnern kann das Löschen optional rekursiv erfolgen und alle Unterordner und die darin enthaltenen Dateien umfassen.

// Delete a file.
await directoryHandle.removeEntry('Abandoned Projects.txt');
// Recursively delete a folder.
await directoryHandle.removeEntry('Old Stuff', { recursive: true });

Dateien oder Ordner direkt löschen

Wenn Sie Zugriff auf einen Datei- oder Verzeichnis-Handle haben, rufen Sie remove() auf einem FileSystemFileHandle oder FileSystemDirectoryHandle auf, um ihn zu entfernen.

// Delete a file.
await fileHandle.remove();
// Delete a directory.
await directoryHandle.remove();

Dateien und Ordner umbenennen und verschieben

Dateien und Ordner können umbenannt oder an einen neuen Speicherort verschoben werden, indem Sie auf der Benutzeroberfläche FileSystemHandle move() aufrufen. FileSystemHandle hat die untergeordneten Schnittstellen FileSystemFileHandle und FileSystemDirectoryHandle. Die Methode move() hat einen oder zwei Parameter. Das erste kann entweder ein String mit dem neuen Namen oder ein FileSystemDirectoryHandle zum Zielordner sein. Im letzteren Fall ist der optionale zweite Parameter ein String mit dem neuen Namen. So können Sie das Element in einem Schritt verschieben und umbenennen.

// Rename the file.
await file.move('new_name');
// Move the file to a new directory.
await file.move(directory);
// Move the file to a new directory and rename it.
await file.move(directory, 'newer_name');

Drag-and-drop-Integration

Mit den HTML-Drag-and-drop-Benutzeroberflächen können Webanwendungen per Drag-and-drop abgelegte Dateien auf einer Webseite akzeptieren. Beim Drag-and-drop-Vorgang werden die Datei- und Verzeichniselemente, die Sie verschieben, Datei- bzw. Verzeichniseinträgen zugeordnet. Die Methode DataTransferItem.getAsFileSystemHandle() gibt ein Versprechen mit einem FileSystemFileHandle-Objekt zurück, wenn das gezogene Element eine Datei ist, und ein Versprechen mit einem FileSystemDirectoryHandle-Objekt, wenn es sich um ein Verzeichnis handelt. Im folgenden Listeneintrag wird dies veranschaulicht. Beachten Sie, dass DataTransferItem.kind der Drag-and-drop-Benutzeroberfläche sowohl für Dateien als auch für Verzeichnisse "file" ist, während FileSystemHandle.kind der File System Access API "file" für Dateien und "directory" für Verzeichnisse ist.

elem.addEventListener('dragover', (e) => {
  // Prevent navigation.
  e.preventDefault();
});

elem.addEventListener('drop', async (e) => {
  e.preventDefault();

  const fileHandlesPromises = [...e.dataTransfer.items]
    .filter((item) => item.kind === 'file')
    .map((item) => item.getAsFileSystemHandle());

  for await (const handle of fileHandlesPromises) {
    if (handle.kind === 'directory') {
      console.log(`Directory: ${handle.name}`);
    } else {
      console.log(`File: ${handle.name}`);
    }
  }
});

Auf das private Dateisystem des Ursprungs zugreifen

Das private Dateisystem des Ursprungs ist ein Speicherendpunkt, der, wie der Name schon sagt, nur für den Ursprung der Seite zugänglich ist. In der Regel speichern Browser den Inhalt dieses privaten Dateisystems irgendwo auf dem Laufwerk. Die Inhalte sollen nicht für Nutzer zugänglich sein. Ebenso wird nicht erwartet, dass Dateien oder Verzeichnisse mit Namen vorhanden sind, die mit den Namen der untergeordneten Elemente des ursprünglichen privaten Dateisystems übereinstimmen. Der Browser kann zwar den Anschein erwecken, dass es Dateien gibt, aber da es sich um ein privates Dateisystem des Ursprungs handelt, speichert der Browser diese „Dateien“ möglicherweise in einer Datenbank oder einem anderen Datenstruktur. Wenn Sie diese API verwenden, können Sie nicht davon ausgehen, dass die erstellten Dateien irgendwo auf der Festplatte genau übereinstimmen. Sobald Sie Zugriff auf das Stammverzeichnis FileSystemDirectoryHandle haben, können Sie wie gewohnt mit dem privaten Quelldateisystem arbeiten.

const root = await navigator.storage.getDirectory();
// Create a new file handle.
const fileHandle = await root.getFileHandle('Untitled.txt', { create: true });
// Create a new directory handle.
const dirHandle = await root.getDirectoryHandle('New Folder', { create: true });
// Recursively remove a directory.
await root.removeEntry('Old Stuff', { recursive: true });

Auf leistungsoptimierte Dateien aus dem privaten Quelldateisystem zugreifen

Das private Dateisystem des Ursprungs bietet optionalen Zugriff auf eine spezielle Art von Datei, die für eine hohe Leistung optimiert ist. So wird beispielsweise ein In-Place- und exklusiver Schreibzugriff auf den Inhalt einer Datei gewährt. In Chromium 102 und höher gibt es eine zusätzliche Methode im privaten Dateisystem des Ursprungs, um den Dateizugriff zu vereinfachen: createSyncAccessHandle() (für synchrone Lese- und Schreibvorgänge). Sie ist in FileSystemFileHandle verfügbar, aber ausschließlich in Webworkern.

// (Read and write operations are synchronous,
// but obtaining the handle is asynchronous.)
// Synchronous access exclusively in Worker contexts.
const accessHandle = await fileHandle.createSyncAccessHandle();
const writtenBytes = accessHandle.write(buffer);
const readBytes = accessHandle.read(buffer, { at: 1 });

Polyfilling

Es ist nicht möglich, die Methoden der File System Access API vollständig zu polyfillen.

• Die Methode showOpenFilePicker() kann mit einem <input type="file">-Element approximiert werden.
• Die showSaveFilePicker()-Methode kann mit einem <a download="file_name">-Element simuliert werden. Dadurch wird jedoch ein programmatischer Download ausgelöst und vorhandene Dateien können nicht überschrieben werden.
• Die showDirectoryPicker()-Methode kann mit dem nicht standardmäßigen Element <input type="file" webkitdirectory> in gewisser Weise emuliert werden.

Wir haben die Bibliothek browser-fs-access entwickelt, die nach Möglichkeit die File System Access API verwendet und in allen anderen Fällen auf die nächstbesten Optionen zurückgreift.

Sicherheit und Berechtigungen

Das Chrome-Team hat die File System Access API anhand der in Controlling Access to Powerful Web Platform Features (Zugriff auf leistungsstarke Funktionen der Webplattform steuern) definierten Grundprinzipien entwickelt und implementiert. Dazu gehören Nutzerkontrolle und Transparenz sowie Nutzerfreundlichkeit.

Datei öffnen oder neue Datei speichern

Beim Öffnen einer Datei erteilt der Nutzer über die Dateiauswahl die Berechtigung zum Lesen einer Datei oder eines Verzeichnisses. Die Auswahl der zu öffnenden Datei kann nur durch eine Nutzergeste angezeigt werden, wenn sie aus einem sicheren Kontext bereitgestellt wird. Wenn Nutzer ihre Meinung ändern, können sie die Auswahl in der Dateiauswahl aufheben. Die Website erhält dann keinen Zugriff auf die Dateien. Das entspricht dem Verhalten des <input type="file">-Elements.

Wenn eine Webanwendung eine neue Datei speichern möchte, zeigt der Browser die Dateiauswahl an, über die der Nutzer den Namen und Speicherort der neuen Datei angeben kann. Da eine neue Datei auf dem Gerät gespeichert wird (und keine vorhandene Datei überschrieben wird), gewährt die Dateiauswahl der App die Berechtigung zum Schreiben in die Datei.

Eingeschränkt zugängliche Ordner

Zum Schutz der Nutzer und ihrer Daten kann der Browser die Möglichkeit des Nutzers einschränken, in bestimmten Ordnern zu speichern, z. B. in wichtigen Betriebssystemordnern wie den macOS-Bibliotheksordnern. In diesem Fall wird im Browser eine Aufforderung angezeigt, in der der Nutzer aufgefordert wird, einen anderen Ordner auszuwählen.

Vorhandene Datei oder Verzeichnis ändern

Eine Webanwendung kann eine Datei auf dem Laufwerk nicht ändern, ohne eine ausdrückliche Berechtigung vom Nutzer zu erhalten.

Berechtigungsanfrage

Wenn eine Person Änderungen an einer Datei speichern möchte, für die sie zuvor Lesezugriff gewährt hat, wird im Browser eine Berechtigungsanfrage angezeigt, in der die Website um Erlaubnis zum Schreiben der Änderungen auf die Festplatte gebeten wird. Die Berechtigungsanfrage kann nur durch eine Nutzeraktion ausgelöst werden, z. B. durch Klicken auf eine Schaltfläche zum Speichern.

Alternativ kann eine Webanwendung, die mehrere Dateien bearbeiten kann, wie z. B. eine IDE, beim Öffnen auch um Erlaubnis zum Speichern von Änderungen bitten.

Wenn der Nutzer „Abbrechen“ auswählt und keinen Schreibzugriff gewährt, kann die Webanwendung keine Änderungen an der lokalen Datei speichern. Es sollte eine alternative Methode zum Speichern der Daten für den Nutzer geben, z. B. die Möglichkeit, die Datei herunterzuladen oder Daten in der Cloud zu speichern.

Transparenz

Sobald ein Nutzer einer Webanwendung die Berechtigung zum Speichern einer lokalen Datei erteilt hat, zeigt der Browser ein Symbol in der Adressleiste an. Wenn Sie auf das Symbol klicken, wird ein Pop-up mit einer Liste der Dateien geöffnet, auf die der Nutzer Zugriff gewährt hat. Der Nutzer kann diesen Zugriff jederzeit widerrufen.

Berechtigungsspeicherung

Die Webanwendung kann Änderungen an der Datei so lange speichern, bis alle Tabs für den Ursprung geschlossen sind. Sobald ein Tab geschlossen wird, verliert die Website den Zugriff. Wenn der Nutzer die Webanwendung das nächste Mal verwendet, wird er noch einmal zum Zugriff auf die Dateien aufgefordert.

Feedback

Wir möchten gerne wissen, wie Sie die File System Access API bisher erlebt haben.

Informationen zum API-Design

Funktioniert die API nicht wie erwartet? Oder fehlen Methoden oder Eigenschaften, die Sie zur Implementierung Ihrer Idee benötigen? Haben Sie Fragen oder Kommentare zum Sicherheitsmodell?

• Reichen Sie ein Problem mit der Spezifikation im WICG File System Access GitHub-Repository ein oder fügen Sie Ihre Gedanken zu einem vorhandenen Problem hinzu.

Problem bei der Implementierung?

Haben Sie einen Fehler in der Chrome-Implementierung gefunden? Oder unterscheidet sich die Implementierung von der Spezifikation?

• Melden Sie den Fehler unter https://new.crbug.com. Geben Sie dabei so viele Details wie möglich an, geben Sie eine Anleitung zur Reproduktion an und setzen Sie Components auf Blink>Storage>FileSystem. Glitch eignet sich hervorragend, um schnelle Reproduktionen zu teilen.

Sie möchten die API verwenden?

Sie möchten die File System Access API auf Ihrer Website verwenden? Ihre öffentliche Unterstützung hilft uns, Funktionen zu priorisieren, und zeigt anderen Browseranbietern, wie wichtig es ist, sie zu unterstützen.

• Teilen Sie im WICG-Discourse-Thread mit, wie Sie es verwenden möchten.
• Senden Sie einen Tweet an @ChromiumDev mit dem Hashtag #FileSystemAccess und teilen Sie uns mit, wo und wie Sie ihn verwenden.

Nützliche Links

• Öffentliche Erläuterung
• Spezifikation für den Dateisystemzugriff und Dateispezifikation
• Tracking-Fehler
• Eintrag in ChromeStatus.com
• TypeScript-Definitionen
• File System Access API – Chromium-Sicherheitsmodell
• Blink-Komponente: Blink>Storage>FileSystem

Danksagungen

Die Spezifikation der File System Access API wurde von Marijn Kruisselbrink verfasst.