Signatur
Beschreibung
Die Methode values() eines FileSystemDirectoryHandle liefert einen asynchronen Iterator über alle direkten Einträge des Verzeichnisses. Jeder gelieferte Wert ist ein Handle, also entweder ein FileSystemFileHandle (Datei) oder ein FileSystemDirectoryHandle (Unterverzeichnis). Anhand der Eigenschaft kind ("file" oder "directory") unterscheidet man die beiden Fälle, der Name steht in handle.name.
Da der Iterator asynchron ist, verwendet man ihn mit for await...of. Die Methode ist das Gegenstück zu keys() (nur Namen) und entries() (Paare [name, handle]). Das Verzeichnis-Handle selbst ist ebenfalls asynchron iterierbar; for await (const x of dirHandle) entspricht dabei entries(), nicht values().
Typische Einsatzgebiete sind das Auflisten von Dateien im Origin Private File System (OPFS, über navigator.storage.getDirectory()) oder in einem vom Benutzer per window.showDirectoryPicker() ausgewählten Ordner, etwa für Dateibrowser, Editoren oder Import-Funktionen. Es werden nur die direkten Kinder geliefert; für rekursives Durchlaufen muss man bei Unterverzeichnissen selbst erneut values() aufrufen.
Rückgabewert
next() ein Promise auf { value, done } liefert; value ist jeweils das Handle eines Eintrags.Beispiele
Einträge des Origin Private File System auflisten
const root = await navigator.storage.getDirectory();
// Testdaten anlegen
await root.getFileHandle('notizen.txt', { create: true });
await root.getDirectoryHandle('bilder', { create: true });
for await (const handle of root.values()) {
console.log(`${handle.kind}: ${handle.name}`);
}Nur Dateien eines gewählten Ordners samt Größe ausgeben
const dir = await window.showDirectoryPicker();
for await (const handle of dir.values()) {
if (handle.kind !== 'file') continue;
const file = await handle.getFile();
console.log(`${file.name} – ${file.size} Bytes`);
}Verzeichnisbaum rekursiv durchlaufen
const walk = async (dirHandle, pfad = '') => {
const dateien = [];
for await (const handle of dirHandle.values()) {
const aktuellerPfad = `${pfad}/${handle.name}`;
if (handle.kind === 'directory') {
dateien.push(...await walk(handle, aktuellerPfad));
} else {
dateien.push(aktuellerPfad);
}
}
return dateien;
};
const root = await navigator.storage.getDirectory();
console.log(await walk(root));Iterator in ein Array umwandeln
const root = await navigator.storage.getDirectory();
// Array.fromAsync (ES2024) oder manuelle Schleife als Fallback
const handles = Array.fromAsync
? await Array.fromAsync(root.values())
: await (async () => {
const arr = [];
for await (const h of root.values()) arr.push(h);
return arr;
})();
console.log(handles.map((h) => h.name).sort());// Wichtig · Fallstricke
- Keine feste Reihenfolge: Die Einträge kommen in einer vom Browser bzw. Dateisystem abhängigen Reihenfolge. Bei Bedarf nach dem Einsammeln selbst sortieren.
- Nur direkte Kinder: Unterverzeichnisse werden nicht automatisch durchlaufen – Rekursion ist Handarbeit. Bei großen Bäumen auf Performance und Speicher achten.
- Änderungen während der Iteration: Legt man Einträge an oder löscht sie, während man iteriert, ist das Verhalten nicht klar festgelegt. Besser erst alle Handles einsammeln und danach ändern.
- Berechtigungen: Bei per
showDirectoryPicker()gewählten Ordnern ist eine Leseberechtigung nötig; ist sie verfallen, wirft die Iteration einenNotAllowedError. MitqueryPermission()/requestPermission()vorher prüfen. Wurde das Verzeichnis entfernt, gibt es einenNotFoundError. - 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. Nur in sicheren Kontexten (HTTPS) verfügbar, auch in Web Workern. - Asynchrone Iteratoren sind kein Array: Methoden wie
map()gehen erst nach einer Umwandlung, etwa mitArray.fromAsync().