FileSystemEntry.getMetadata() — Methode · JavaScript-Referenz

Signatur

FileSystemEntry.prototype.getMetadata(successCallback, errorCallback)

Beschreibung

Die Methode getMetadata() gehört zum Interface FileSystemEntry der File and Directory Entries API. Sie fragt asynchron Metadaten zu einer Datei oder einem Verzeichnis ab und übergibt das Ergebnis als Metadata-Objekt an einen Callback. Dieses Objekt hat zwei Eigenschaften: modificationTime (ein Date mit dem Zeitpunkt der letzten Änderung) und size (Größe in Byte; bei Verzeichnissen meist 0).

Einträge vom Typ FileSystemEntry bekommt man vor allem beim Drag-and-Drop über DataTransferItem.webkitGetAsEntry() oder aus HTMLInputElement.webkitEntries bei einem <input type="file" webkitdirectory>. Mit getMetadata() lassen sich Größe und Änderungsdatum abfragen, ohne dass man die Datei erst als File-Objekt öffnen muss.

Die Methode arbeitet nur mit Callbacks und gibt kein Promise zurück. In moderner Codebasis packt man sie deshalb meist in ein Promise ein, damit man async/await verwenden kann. Wichtig: getMetadata() ist veraltet und wurde nie in den Standard aufgenommen. Für Dateien ist FileSystemFileEntry.file() die zuverlässigere Lösung, denn das zurückgegebene File liefert size und lastModified in allen Browsern.

Parameter

Name	Typ	Default	Beschreibung
$successCallback Pflicht	(metadata: Metadata) => void		Wird bei Erfolg aufgerufen und erhält ein `Metadata`-Objekt mit den Eigenschaften `modificationTime` (`Date`) und `size` (`number`, in Byte).
$errorCallback	(error: DOMException) => void		Wird bei einem Fehler aufgerufen, z. B. mit `NotFoundError`, wenn der Eintrag nicht mehr existiert, oder mit `SecurityError`, wenn der Zugriff verweigert wird.

Rückgabewert

Typ

undefined

Beschreibung

Gibt nichts zurück. Das Ergebnis kommt ausschließlich über successCallback bzw. errorCallback.

Beispiele

Metadaten einer per Drag-and-Drop abgelegten Datei auslesen

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

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

dropZone.addEventListener('drop', (event) => {
  event.preventDefault();
  for (const item of event.dataTransfer.items) {
    const entry = item.webkitGetAsEntry();
    if (!entry) continue;

    entry.getMetadata(
      (metadata) => {
        console.log(`${entry.name}: ${metadata.size} Byte, geändert am ${metadata.modificationTime.toLocaleString('de-DE')}`);
      },
      (error) => console.error(`Metadaten für ${entry.name} nicht lesbar:`, error.name)
    );
  }
});

bericht.pdf: 248311 Byte, geändert am 12.3.2024, 14:05:22

Callback-API in ein Promise einpacken (mit Ersatzweg)

const getMetadataAsync = (entry) =>
  new Promise((resolve, reject) => {
    if (typeof entry.getMetadata === 'function') {
      entry.getMetadata(resolve, reject);
    } else if (entry.isFile) {
      // Ersatzweg für Browser ohne getMetadata()
      entry.file(
        (file) => resolve({ size: file.size, modificationTime: new Date(file.lastModified) }),
        reject
      );
    } else {
      reject(new Error('Metadaten für Verzeichnisse nicht verfügbar'));
    }
  });

// Verwendung im Drop-Handler
document.addEventListener('drop', async (event) => {
  event.preventDefault();
  const entry = event.dataTransfer.items[0]?.webkitGetAsEntry();
  if (!entry) return;
  try {
    const { size, modificationTime } = await getMetadataAsync(entry);
    console.log({ name: entry.name, size, modificationTime });
  } catch (err) {
    console.warn('Fehler:', err.message ?? err.name);
  }
});

{ name: 'foto.jpg', size: 1834221, modificationTime: Date }

Zu große Dateien vor dem Hochladen herausfiltern

const MAX_BYTES = 5 * 1024 * 1024; // 5 MB

const checkSize = (entry) =>
  new Promise((resolve, reject) => entry.getMetadata(resolve, reject))
    .then(({ size }) => ({ entry, ok: size <= MAX_BYTES, size }));

document.addEventListener('drop', async (event) => {
  event.preventDefault();
  const entries = [...event.dataTransfer.items]
    .map((item) => item.webkitGetAsEntry())
    .filter((e) => e?.isFile);

  const results = await Promise.all(entries.map(checkSize));
  for (const { entry, ok, size } of results) {
    console.log(`${entry.name}: ${ok ? 'OK' : 'zu groß'} (${(size / 1024).toFixed(1)} KB)`);
  }
});

notizen.txt: OK (3.2 KB) video.mp4: zu groß (48213.7 KB)

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: getMetadata() steht nicht in der aktuellen Spezifikation der File and Directory Entries API. Nur Chromium-basierte Browser unterstützen sie; Firefox und Safari kennen sie nicht. Prüfe deshalb immer vorher mit typeof entry.getMetadata === 'function', ob die Methode vorhanden ist.
Empfohlene Alternative: Für Dateien FileSystemFileEntry.file() verwenden. Das File-Objekt liefert size und lastModified in allen Browsern. Für neue Projekte ist die File System Access API (FileSystemHandle, getFile()) zukunftssicherer.
Nur Callbacks: Es gibt keinen Promise-Rückgabewert. await entry.getMetadata() liefert undefined und ist ein häufiger Fehler.
Nur solange das Ereignis läuft: DataTransferItem-Objekte sind nur während des drop-Ereignisses gültig. Rufe webkitGetAsEntry() deshalb gleich im Handler auf, bevor du irgendetwas mit await abwartest. Das Entry-Objekt selbst bleibt danach nutzbar.
Verzeichnisse: Bei FileSystemDirectoryEntry ist size in der Regel 0 und damit nicht aussagekräftig.
Nur in einem sicheren Kontext (HTTPS) und nur für Dateien, die der Nutzer selbst ausgewählt oder abgelegt hat. Ein freier Zugriff auf das Dateisystem ist nicht möglich.

Siehe auch

File FileSystemDirectoryHandle.keys() FileSystemEntry.getParent() FileSystemEntry.moveTo() FileSystemEntry.remove()