FileSystemDirectoryHandle.keys() — Methode · JavaScript-Referenz

Signatur

FileSystemDirectoryHandle.prototype.keys()

Beschreibung

Die Methode keys() liefert einen asynchronen Iterator, der nacheinander die Namen aller Dateien und Unterverzeichnisse im Verzeichnis liefert, jeweils als string. Sie funktioniert wie Map.prototype.keys(), nur asynchron. Deshalb durchläuft man sie mit for await...of.

Nimm keys(), wenn du nur die Namen der Einträge brauchst, etwa für eine Dateiliste, um zu prüfen, ob ein Name schon vergeben ist, oder um einen freien Dateinamen zu erzeugen. Brauchst du zusätzlich die Handles (zum Lesen oder um zwischen Datei und Ordner zu unterscheiden), sind entries() oder values() besser geeignet.

Die Iteration ist nicht rekursiv: Du bekommst nur die direkten Kinder des Verzeichnisses. Die Reihenfolge ist nicht festgelegt und hängt vom Browser bzw. Dateisystem ab. Die Methode gibt es sowohl im Origin Private File System (navigator.storage.getDirectory()) als auch bei Verzeichnissen, die der Nutzer über window.showDirectoryPicker() freigegeben hat.

Rückgabewert

Typ

AsyncIterableIterator<string>

Beschreibung

Ein neuer asynchroner Iterator. Jeder Aufruf von next() gibt ein Promise zurück, das zu { value: string, done: boolean } aufgelöst wird. value ist der Name eines Eintrags.

Beispiele

Alle Einträge im Origin Private File System auflisten

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

// Testdateien anlegen
await root.getFileHandle('notizen.txt', { create: true });
await root.getDirectoryHandle('bilder', { create: true });

for await (const name of root.keys()) {
  console.log(name);
}

notizen.txt bilder (Reihenfolge nicht garantiert)

Namen in ein Array sammeln und sortieren

const listNames = async (dirHandle) => {
  const names = [];
  for await (const name of dirHandle.keys()) {
    names.push(name);
  }
  return names.sort((a, b) => a.localeCompare(b, 'de'));
};

const root = await navigator.storage.getDirectory();
console.log(await listNames(root));

// Alternative (ES2024+): Array.fromAsync
// const names = await Array.fromAsync(root.keys());

["bilder", "notizen.txt"]

Freien Dateinamen finden (z. B. „bericht (2).txt“)

const findFreeName = async (dirHandle, base, ext) => {
  const existing = new Set();
  for await (const name of dirHandle.keys()) existing.add(name);

  let candidate = `${base}.${ext}`;
  let i = 2;
  while (existing.has(candidate)) {
    candidate = `${base} (${i++}).${ext}`;
  }
  return candidate;
};

const dir = await window.showDirectoryPicker();
const name = await findFreeName(dir, 'bericht', 'txt');
const fileHandle = await dir.getFileHandle(name, { create: true });
console.log('Angelegt:', fileHandle.name);

Angelegt: bericht (2).txt

// Wichtig · Fallstricke

Nur mit for await...of: Ein normales for...of oder der Spread-Operator ([...dir.keys()]) wirft einen TypeError, weil der Iterator asynchron ist. Nimm stattdessen Array.fromAsync() (ES2024) oder eine Schleife.
Nicht rekursiv: Unterverzeichnisse musst du selbst über getDirectoryHandle() bzw. entries() weiter durchlaufen.
Keine Typinformation: keys() liefert nur Namen. Ob ein Eintrag eine Datei oder ein Ordner ist, erfährst du nur über entries()/values() (handle.kind).
Berechtigungen: Bei Verzeichnissen aus showDirectoryPicker() braucht man mindestens Leserechte. Fehlen sie, wird ein NotAllowedError geworfen. Wurde das Verzeichnis inzwischen gelöscht, kommt ein NotFoundError. Die Berechtigung lässt sich mit queryPermission()/requestPermission() prüfen bzw. anfordern (nur in Chromium).
Kompatibilität: Das OPFS (navigator.storage.getDirectory()) funktioniert in allen modernen Browsern. showDirectoryPicker() gibt es dagegen nur in Chromium-Browsern, nicht in Firefox und Safari. Die API steht nur in sicheren Kontexten (HTTPS) zur Verfügung. In Web Workern ist sie ebenfalls verfügbar.
Wenn sich das Verzeichnis während der Iteration ändert, ist nicht festgelegt, ob neue oder gelöschte Einträge noch berücksichtigt werden.

Siehe auch

for await...of FileSystemDirectoryEntry.getFile() FileSystemDirectoryHandle.values() FileSystemDirectoryHandle.entries() FileSystemDirectoryHandle.resolve()