FileSystemDirectoryHandle.removeEntry() — Methode · JavaScript-Referenz

Signatur

FileSystemDirectoryHandle.prototype.removeEntry(name, options)

Beschreibung

Mit removeEntry() löschen Sie einen direkten Eintrag eines Verzeichnisses, also eine Datei oder ein Unterverzeichnis. Den Eintrag geben Sie über seinen Namen an, nicht über einen Handle oder einen Pfad. Die Methode arbeitet asynchron und gibt ein Promise zurück, das nach erfolgreichem Löschen mit undefined erfüllt wird.

Gebraucht wird die Methode vor allem beim Origin Private File System (OPFS), das Sie über navigator.storage.getDirectory() erreichen. Dort räumen Sie damit Caches, temporäre Dateien oder veraltete Datenbank-Dateien auf. Sie funktioniert auch mit Verzeichnissen, die der Nutzer über window.showDirectoryPicker() freigegeben hat. Dann ist allerdings eine Schreibberechtigung (readwrite) nötig.

Ein Verzeichnis, das nicht leer ist, lässt sich nur mit der Option { recursive: true } löschen. Ohne diese Option schlägt der Aufruf mit einer InvalidModificationError-DOMException fehl. Wenn der Eintrag nicht existiert, wird das Promise mit einem NotFoundError abgelehnt. Die Methode legt also nichts an und ignoriert fehlende Einträge nicht stillschweigend.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string		Name des zu löschenden Eintrags im aktuellen Verzeichnis. Das muss ein gültiger Dateiname sein. Pfadtrenner wie `/` sowie `.` und `..` sind nicht erlaubt (führt zu `TypeError`).
$options	object	{}	Optionales Objekt mit Einstellungen für den Löschvorgang.
$options.recursive	boolean	false	Bei `true` wird ein Verzeichnis samt Inhalt rekursiv gelöscht. Für Dateien hat die Option keine Wirkung.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Eintrag gelöscht ist. Im Fehlerfall wird es mit einer DOMException oder einem TypeError abgelehnt.

Beispiele

Temporäre Datei im OPFS löschen

const root = await navigator.storage.getDirectory();

// Datei anlegen und beschreiben
const fileHandle = await root.getFileHandle('temp.txt', { create: true });
const writable = await fileHandle.createWritable();
await writable.write('Zwischenstand');
await writable.close();

// Datei wieder entfernen
await root.removeEntry('temp.txt');
console.log('temp.txt gelöscht');

temp.txt gelöscht

Nicht leeres Cache-Verzeichnis rekursiv entfernen

const root = await navigator.storage.getDirectory();
const cache = await root.getDirectoryHandle('cache', { create: true });
await cache.getFileHandle('a.json', { create: true });
await cache.getFileHandle('b.json', { create: true });

try {
  await root.removeEntry('cache'); // schlägt fehl: Verzeichnis nicht leer
} catch (err) {
  console.log(err.name);
}

await root.removeEntry('cache', { recursive: true });
console.log('Cache geleert');

InvalidModificationError Cache geleert

Sicheres Löschen mit Fehlerbehandlung

const deleteIfExists = async (dirHandle, name) => {
  try {
    await dirHandle.removeEntry(name, { recursive: true });
    return true;
  } catch (err) {
    if (err.name === 'NotFoundError') return false; // existierte nicht
    throw err; // z. B. NotAllowedError, NoModificationAllowedError
  }
};

const root = await navigator.storage.getDirectory();
console.log(await deleteIfExists(root, 'gibt-es-nicht.log'));

false

Alle .tmp-Dateien eines Verzeichnisses aufräumen

const root = await navigator.storage.getDirectory();

// Erst Namen sammeln, dann löschen: nicht während der Iteration verändern
const toDelete = [];
for await (const [name, handle] of root.entries()) {
  if (handle.kind === 'file' && name.endsWith('.tmp')) toDelete.push(name);
}

await Promise.all(toDelete.map((name) => root.removeEntry(name)));
console.log(`${toDelete.length} temporäre Dateien entfernt`);

3 temporäre Dateien entfernt

// Wichtig · Fallstricke

Fehlerarten: NotFoundError bedeutet, dass der Eintrag nicht existiert. InvalidModificationError tritt auf, wenn ein Verzeichnis nicht leer ist und recursive fehlt. NotAllowedError heißt, dass keine Schreibberechtigung vorliegt. NoModificationAllowedError kommt, wenn der Eintrag gesperrt ist, etwa durch ein offenes FileSystemSyncAccessHandle oder einen aktiven Schreib-Stream. Ein TypeError wird bei ungültigem Namen geworfen.
Nur direkte Kinder: Pfade wie 'ordner/datei.txt' funktionieren nicht. Holen Sie sich zuerst mit getDirectoryHandle() den Handle des Elternverzeichnisses.
Endgültig: Gelöschte Einträge landen nicht im Papierkorb. Das gilt besonders für vom Nutzer freigegebene Verzeichnisse. Fragen Sie vor rekursivem Löschen dort nach einer Bestätigung.
Berechtigung: Bei Handles aus showDirectoryPicker() prüfen Sie vorher mit queryPermission({ mode: 'readwrite' }) bzw. requestPermission(), ob Schreibzugriff besteht. Im OPFS ist der Zugriff immer erlaubt.
Kompatibilität: Die Methode ist nur in sicheren Kontexten (HTTPS) verfügbar. Im OPFS funktioniert sie in allen aktuellen Browsern. showDirectoryPicker() gibt es dagegen nur in Chromium-Browsern. Als Alternative zum Löschen eines Handles, den Sie schon besitzen, bietet Chromium das nicht standardisierte FileSystemHandle.remove().
Verändern Sie ein Verzeichnis nicht, während Sie mit entries()/values() darüber iterieren. Sammeln Sie die Namen zuerst.

Siehe auch

FileSystemDirectoryHandle.resolve() FileSystemDirectoryHandle.entries() FileSystemDirectoryHandle.getFileHandle() FileSystemDirectoryHandle.keys() FileSystemDirectoryHandle.values()