new File() — Methode · JavaScript-Referenz

Signatur

new File(fileBits, fileName, options)

Beschreibung

Mit new File() erzeugst du ein File-Objekt direkt in JavaScript, ohne dass der Nutzer eine Datei über <input type="file"> oder per Drag & Drop auswählen muss. File erbt von Blob und hat zusätzlich die Eigenschaften name und lastModified.

Typische Einsatzfälle sind: generierte Inhalte (CSV, JSON, Bilder aus einem <canvas>) als echte Datei per FormData an einen Server hochladen, Dateien für die Web Share API vorbereiten, Upload-Logik in Tests mit künstlichen Dateien prüfen oder einen vorhandenen Blob nachträglich mit Namen versehen.

Der erste Parameter ist immer ein Array (genauer: ein iterierbares Objekt) aus Teilstücken. Strings werden als UTF-8 kodiert, ArrayBuffer, typisierte Arrays, DataView und Blobs werden unverändert hintereinandergehängt. Der MIME-Typ wird nicht aus der Dateiendung abgeleitet, du musst ihn über options.type selbst angeben.

Parameter

Name	Typ	Default	Beschreibung
$fileBits Pflicht	Iterable<string \| ArrayBuffer \| TypedArray \| DataView \| Blob>		Iterierbare Liste von Teilstücken (meist ein Array), die zum Dateiinhalt zusammengesetzt werden. Strings werden als UTF-8 kodiert.
$fileName Pflicht	string		Dateiname, landet in `file.name`. Wird beim Upload per `FormData` als Dateiname übertragen. Es ist ein reiner Name ohne Pfad.
$options	object	{}	Optionales Objekt mit folgenden Feldern: `type` (string, MIME-Typ, Standard `""`), `lastModified` (number, Zeitstempel in Millisekunden, Standard `Date.now()`) und `endings` (`"transparent"` \| `"native"`, Umgang mit Zeilenumbrüchen in Strings, Standard `"transparent"`).

Rückgabewert

Typ

File

Beschreibung

Ein neues File-Objekt mit den Eigenschaften name, size, type und lastModified sowie allen Blob-Methoden (text(), arrayBuffer(), stream(), slice()).

Beispiele

Textdatei erzeugen und Eigenschaften prüfen

const file = new File(['Hallo Welt!\n', 'Zweite Zeile'], 'notiz.txt', {
  type: 'text/plain',
  lastModified: new Date('2024-01-15T10:00:00Z').getTime()
});

console.log(file.name);
console.log(file.size);
console.log(file.type);
console.log(new Date(file.lastModified).toISOString());
console.log(await file.text());

notiz.txt 24 text/plain 2024-01-15T10:00:00.000Z Hallo Welt! Zweite Zeile

Generierte CSV-Datei per FormData hochladen

const rows = [['Name', 'Punkte'], ['Anna', 42], ['Ben', 37]];
const csv = rows.map((r) => r.join(';')).join('\r\n');

const file = new File([csv], 'export.csv', { type: 'text/csv;charset=utf-8' });

const formData = new FormData();
formData.append('upload', file); // Dateiname wird automatisch übernommen

const response = await fetch('/api/upload', { method: 'POST', body: formData });
console.log(response.ok ? 'Upload erfolgreich' : `Fehler: ${response.status}`);

Upload erfolgreich

Canvas-Inhalt als PNG-Datei teilen

const canvas = document.querySelector('canvas');

const blob = await new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));
const file = new File([blob], 'zeichnung.png', { type: 'image/png' });

if (navigator.canShare?.({ files: [file] })) {
  await navigator.share({ files: [file], title: 'Meine Zeichnung' });
} else {
  console.log('Teilen von Dateien wird nicht unterstützt');
}

Datei in einem Test einem input-Element zuweisen

const input = document.querySelector('input[type="file"]');
const file = new File([JSON.stringify({ id: 1 })], 'daten.json', { type: 'application/json' });

// input.files ist schreibgeschützt, daher über DataTransfer setzen
const dt = new DataTransfer();
dt.items.add(file);
input.files = dt.files;

input.dispatchEvent(new Event('change', { bubbles: true }));
console.log(input.files[0].name);

daten.json

// Wichtig · Fallstricke

Häufigster Fehler: new File('text', 'a.txt') ohne Array. Ein String ist zwar iterierbar und wird Zeichen für Zeichen übernommen, andere Werte (z. B. ein einzelner ArrayBuffer) lösen aber einen TypeError aus. Übergib den Inhalt deshalb immer als [daten].
Der type wird nicht geprüft und nicht aus dem Dateinamen abgeleitet. Ohne Angabe ist er "", und der Server bekommt dann oft application/octet-stream. Nicht-ASCII-Zeichen machen den Typ ebenfalls zu "", Großbuchstaben werden in Kleinbuchstaben umgewandelt.
Die Teilstücke werden beim Erzeugen kopiert. Spätere Änderungen an einem übergebenen ArrayBuffer wirken sich nicht auf die Datei aus. Bei sehr großen Datenmengen im Speicher bedeutet das zusätzlichen Speicherverbrauch.
Ein selbst erzeugtes File hat keinen Bezug zum Dateisystem. webkitRelativePath ist leer. Speichern ist nur über einen Download-Link (URL.createObjectURL) oder die File System Access API möglich. Erzeugte Object-URLs danach mit URL.revokeObjectURL wieder freigeben.
Kompatibilität: Wird in allen modernen Browsern unterstützt, auch in Web Workern. Der alte Internet Explorer und das alte Edge (EdgeHTML) kennen den Konstruktor nicht, dort war new Blob() der Ausweg. In Node.js ist File ab Version 20 global verfügbar, davor über require('node:buffer').File (ab 19.2).
Der Dateiname wird nicht bereinigt. Serverseitig musst du ihn immer validieren (Path Traversal wie ../, gefährliche Endungen), denn Clients können beliebige Namen senden.

Siehe auch

File Blob new Blob() FormData FileReader URL.createObjectURL() DataTransfer HTMLCanvasElement.toBlob()