FileSystem.root — Eigenschaft · JavaScript-Referenz

Signatur

FileSystem.root

Beschreibung

Über FileSystem.root kommen Sie an das oberste Verzeichnis eines Dateisystems, das die File and Directory Entries API bereitstellt. Der Wert ist ein FileSystemDirectoryEntry mit dem fullPath "/". Von dort aus können Sie mit createReader() den Inhalt auflisten oder mit getFile() bzw. getDirectory() über relative oder absolute Pfade auf einzelne Einträge zugreifen.

Ein FileSystem-Objekt erzeugen Sie nicht selbst. Sie bekommen es über die Eigenschaft filesystem eines beliebigen FileSystemEntry. In der Praxis stammt dieser Eintrag meist aus einer Drag-and-Drop-Operation (DataTransferItem.webkitGetAsEntry()) oder aus einem Dateieingabefeld (HTMLInputElement.webkitEntries). Die Einträge, die der Browser für eine abgelegte Auswahl anlegt, erscheinen dabei als direkte Kinder dieses virtuellen Stammverzeichnisses.

Brauchbar ist die Eigenschaft vor allem, wenn Sie in einem abgelegten Ordner absolute Pfade auflösen wollen, etwa /projekt/src/index.js, statt sich vom aktuellen Eintrag aus relativ durchzuhangeln. Die Eigenschaft ist schreibgeschützt. Ob ein Schreibzugriff im Dateisystem selbst möglich ist, hängt davon ab, woher es stammt. Dateisysteme aus Drag and Drop oder aus Dateiauswahlen sind nur lesbar.

Rückgabewert

Typ

FileSystemDirectoryEntry

Beschreibung

Ein FileSystemDirectoryEntry für das Stammverzeichnis des Dateisystems. Sein fullPath ist "/", isDirectory ist true.

Beispiele

Stammverzeichnis nach Drag and Drop ermitteln

const dropZone = document.querySelector('#drop-zone');

dropZone.addEventListener('dragover', (event) => event.preventDefault());

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();
  // webkitGetAsEntry() muss synchron im drop-Handler aufgerufen werden
  const entry = event.dataTransfer.items[0]?.webkitGetAsEntry();
  if (!entry) return;

  const root = entry.filesystem.root;
  console.log('Dateisystem:', entry.filesystem.name);
  console.log('Root-Pfad:', root.fullPath);
  console.log('Ist Verzeichnis:', root.isDirectory);
  console.log('Eintrag-Pfad:', entry.fullPath);
});

Dateisystem: blob:https://example.com/3f2a… Root-Pfad: / Ist Verzeichnis: true Eintrag-Pfad: /mein-ordner

Inhalt des Stammverzeichnisses mit async/await auflisten

// readEntries() liefert Ergebnisse stückweise, also so lange aufrufen, bis ein leeres Array kommt
const readAllEntries = (dirEntry) => new Promise((resolve, reject) => {
  const reader = dirEntry.createReader();
  const result = [];
  const readBatch = () => {
    reader.readEntries((batch) => {
      if (batch.length === 0) return resolve(result);
      result.push(...batch);
      readBatch();
    }, reject);
  };
  readBatch();
});

document.querySelector('#drop-zone').addEventListener('drop', async (event) => {
  event.preventDefault();
  const entry = event.dataTransfer.items[0]?.webkitGetAsEntry();
  if (!entry) return;

  const entries = await readAllEntries(entry.filesystem.root);
  for (const e of entries) {
    console.log(`${e.isDirectory ? '📁' : '📄'} ${e.fullPath}`);
  }
});

📁 /mein-ordner

Datei über absoluten Pfad vom Root aus öffnen

// getFile() mit Promise umhüllen
const getFileEntry = (root, path) => new Promise((resolve, reject) => {
  root.getFile(path, {}, resolve, reject);
});

const readText = (fileEntry) => new Promise((resolve, reject) => {
  fileEntry.file((file) => file.text().then(resolve, reject), reject);
});

document.querySelector('#drop-zone').addEventListener('drop', async (event) => {
  event.preventDefault();
  const entry = event.dataTransfer.items[0]?.webkitGetAsEntry();
  if (!entry?.isDirectory) return;

  try {
    const root = entry.filesystem.root;
    const pkg = await getFileEntry(root, `${entry.fullPath}/package.json`);
    const json = JSON.parse(await readText(pkg));
    console.log('Projektname:', json.name);
  } catch (err) {
    console.error('package.json nicht gefunden:', err.name);
  }
});

Projektname: mein-projekt

// Wichtig · Fallstricke

Nur Browser: Die File and Directory Entries API ist eine reine Web-API. In Node.js gibt es sie nicht.
Nur lesbar: Dateisysteme aus Drag and Drop oder aus <input type="file"> lassen sich nicht beschreiben. getFile(path, { create: true }) schlägt dort mit einem Fehler fehl. Wenn Sie wirklich Dateien schreiben wollen, nehmen Sie das Origin Private File System über navigator.storage.getDirectory() (File System API).
Zeitpunkt beachten: webkitGetAsEntry() müssen Sie synchron im drop-Handler aufrufen. Nach einem await ist die DataTransferItemList bereits geleert. Die Einträge selbst dürfen Sie danach aber asynchron verarbeiten.
Callback-API: Methoden wie getFile() und readEntries() arbeiten mit Callbacks statt mit Promises, deshalb lohnt es sich, sie in Promises zu verpacken. readEntries() liefert pro Aufruf nur einen Teil der Einträge (in Chrome höchstens 100), also wiederholt aufrufen.
Veraltetes Gegenstück: Das Chrome-spezifische window.webkitRequestFileSystem() (Sandbox-Dateisystem) ist veraltet und nicht standardisiert. Neuer Code sollte darauf nicht aufbauen.
Trotz des webkit-Präfixes bei webkitGetAsEntry() und webkitEntries unterstützen alle modernen Browser diese Methoden.

Siehe auch

FileSystem.name FileReader.error TreeWalker.root Element.role Element.slot