File.name — Eigenschaft · JavaScript-Referenz

Signatur

File.name

Beschreibung

File.name liefert den Namen der Datei, die ein File-Objekt darstellt, z. B. "bericht.pdf". Der Wert stammt entweder vom Betriebssystem (bei Auswahl über <input type="file"> oder Drag & Drop) oder aus dem zweiten Argument des Konstruktors new File(bits, name).

Aus Datenschutzgründen enthält der Name keinen Pfad: Der Browser gibt nur den reinen Dateinamen weiter. Den relativen Pfad innerhalb eines ausgewählten Ordners (bei webkitdirectory) liefert stattdessen File.webkitRelativePath.

Typische Einsatzzwecke sind die Anzeige ausgewählter Dateien in der Oberfläche, eine erste Prüfung der Dateiendung vor dem Upload und das Setzen des Dateinamens beim Senden per FormData. Die Eigenschaft ist schreibgeschützt; wer einen anderen Namen braucht, erzeugt ein neues File-Objekt.

Rückgabewert

Typ

string

Beschreibung

Der Dateiname ohne Pfad, einschließlich Dateiendung (sofern vorhanden), z. B. "foto.jpg".

Beispiele

Namen ausgewählter Dateien anzeigen

// HTML: <input type="file" id="upload" multiple> <ul id="liste"></ul>
const input = document.querySelector('#upload');
const liste = document.querySelector('#liste');

input.addEventListener('change', () => {
  liste.replaceChildren();
  for (const file of input.files) {
    const li = document.createElement('li');
    // textContent statt innerHTML – Dateinamen sind Benutzereingaben!
    li.textContent = `${file.name} (${(file.size / 1024).toFixed(1)} KB)`;
    liste.append(li);
  }
});

File-Objekt erzeugen und Namen auslesen

const file = new File(['Hallo Welt'], 'gruss.txt', { type: 'text/plain' });
console.log(file.name);
console.log(file.type);

// Schreibversuch wird ignoriert (im Strict Mode: TypeError)
try {
  'use strict';
  file.name = 'anders.txt';
} catch (e) {}
console.log(file.name);

gruss.txt text/plain gruss.txt

Dateiendung prüfen und Datei umbenennen

const erlaubt = ['png', 'jpg', 'jpeg', 'webp'];

const endung = (name) => {
  const i = name.lastIndexOf('.');
  return i > 0 ? name.slice(i + 1).toLowerCase() : '';
};

const umbenennen = (file, neuerName) =>
  new File([file], neuerName, { type: file.type, lastModified: file.lastModified });

const original = new File(['...'], 'Urlaub.JPG', { type: 'image/jpeg' });
console.log(erlaubt.includes(endung(original.name)));

const kopie = umbenennen(original, `avatar-${Date.now()}.jpg`);
console.log(kopie.name.startsWith('avatar-'));

true true

Dateinamen beim Upload mit FormData mitsenden

const hochladen = async (file) => {
  const daten = new FormData();
  // Drittes Argument überschreibt optional den Namen; hier bleibt file.name
  daten.append('dokument', file, file.name);
  const res = await fetch('/api/upload', { method: 'POST', body: daten });
  if (!res.ok) throw new Error(`Upload von ${file.name} fehlgeschlagen`);
  return res.json();
};

// Wichtig · Fallstricke

Sicherheit: Der Dateiname ist eine unkontrollierte Benutzereingabe. Nie per innerHTML ausgeben (XSS-Gefahr, z. B. bei <img src=x onerror=alert(1)>.png), sondern textContent nutzen. Serverseitig den Namen bereinigen (Pfad-Traversal wie ../, Sonderzeichen) oder besser einen eigenen Namen vergeben.
Die Endung in name sagt nichts Verlässliches über den Inhalt aus. File.type wird ebenfalls meist aus der Endung abgeleitet – echte Prüfung nur serverseitig (z. B. über Magic Bytes).
Die Eigenschaft ist schreibgeschützt: Zuweisungen werden still ignoriert bzw. werfen im Strict Mode einen TypeError. Zum Umbenennen ein neues File erzeugen.
Kein Pfad enthalten; für Ordner-Uploads webkitRelativePath verwenden. Bei Dateien aus der Zwischenablage vergeben Browser oft generische Namen wie image.png.
Unicode-Namen können je nach Betriebssystem unterschiedlich normalisiert sein (macOS: NFD). Für Vergleiche name.normalize('NFC') nutzen.
Kompatibilität: in allen modernen Browsern verfügbar; in Node.js ist File ab Version 20 global (vorher über buffer).

Siehe auch

File Blob.type Blob.size File.lastModified File.lastModifiedDate