FileSystemHandle.name — Eigenschaft · JavaScript-Referenz

Signatur

FileSystemHandle.name

Beschreibung

Die Eigenschaft name ist auf jedem FileSystemHandle verfügbar, also auch auf FileSystemFileHandle und FileSystemDirectoryHandle. Sie gibt den reinen Eintragsnamen zurück, bei Dateien mit Endung (z. B. "bericht.txt"), bei Verzeichnissen nur den Ordnernamen (z. B. "Dokumente").

Einen vollständigen Pfad liefert name nicht. Das ist so gewollt: Webseiten sollen nichts über die Verzeichnisstruktur des Nutzers erfahren. Brauchst du einen relativen Pfad innerhalb eines freigegebenen Verzeichnisses, nimmst du FileSystemDirectoryHandle.prototype.resolve().

Typische Anwendungsfälle sind der Dateiname in der Titelleiste eines Editors, Verzeichnisbäume beim Durchlaufen mit entries()/values() und das Filtern nach Dateiendungen. Die Eigenschaft ist schreibgeschützt. Umbenennen geht, wo unterstützt, über FileSystemHandle.prototype.move().

Rückgabewert

Typ

string

Beschreibung

Name des Eintrags (Datei mit Endung oder Verzeichnis) ohne Pfadangabe. Beim Wurzelverzeichnis des Origin Private File System (navigator.storage.getDirectory()) ist das ein leerer String "".

Beispiele

Dateinamen nach Auswahl anzeigen

// Nur Chromium-basierte Browser, muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#oeffnen').addEventListener('click', async () => {
  const [fileHandle] = await window.showOpenFilePicker({
    types: [{ description: 'Textdateien', accept: { 'text/plain': ['.txt'] } }]
  });
  document.title = `${fileHandle.name} – Mein Editor`;
  console.log(fileHandle.name, fileHandle.kind);
});

notizen.txt file

Verzeichnisinhalt auflisten und nach Endung filtern

const dirHandle = await window.showDirectoryPicker();
console.log('Ordner:', dirHandle.name);

for await (const handle of dirHandle.values()) {
  if (handle.kind === 'file' && handle.name.endsWith('.json')) {
    console.log('JSON-Datei:', handle.name);
  }
}

Ordner: projekt JSON-Datei: package.json JSON-Datei: tsconfig.json

Namen im Origin Private File System (OPFS)

const root = await navigator.storage.getDirectory();
console.log(JSON.stringify(root.name)); // Wurzel hat keinen Namen

const cache = await root.getDirectoryHandle('cache', { create: true });
const datei = await cache.getFileHandle('daten.bin', { create: true });
console.log(cache.name, datei.name);

// Relativen Pfad ermitteln – name allein liefert keinen Pfad
console.log((await root.resolve(datei)).join('/'));

"" cache daten.bin cache/daten.bin

// Wichtig · Fallstricke

Kein Pfad: name enthält nie Pfadbestandteile. Wenn du eine eindeutige Kennung brauchst, taugt es deshalb nicht. Zwei Handles mit gleichem Namen können auf verschiedene Einträge zeigen. Vergleiche Handles stattdessen mit isSameEntry().
Schreibgeschützt: Zuweisungen an name werden still ignoriert und werfen im Strict Mode einen TypeError. Umbenennen geht über move(), das noch nicht überall unterstützt wird.
Kompatibilität: FileSystemHandle samt name gibt es über das OPFS in allen modernen Browsern. showOpenFilePicker(), showSaveFilePicker() und showDirectoryPicker() gibt es dagegen nur in Chromium-Browsern. Alles funktioniert nur in sicheren Kontexten (HTTPS).
Gespeicherte Handles: Handles, die in IndexedDB abgelegt wurden, behalten ihren name. Vor einem Zugriff muss die Berechtigung aber per queryPermission()/requestPermission() erneut geprüft werden.
Nutzereingaben aus name nicht ungefiltert per innerHTML ausgeben. Dateinamen können HTML-Zeichen enthalten, deshalb textContent verwenden.

Siehe auch

FileSystem.name FileSystemHandle.kind FileSystemEntry.name FileSystem.root FileSystemEntry.isFile