<input type="file">
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.
<input>
-Elemente mit type="file"
ermöglichen es dem Benutzer, eine oder mehrere Dateien aus dem Gerätespeicher auszuwählen. Sobald die Dateien ausgewählt sind, können sie über die Formularübermittlung an einen Server hochgeladen oder mit JavaScript-Code und der File API bearbeitet werden.
Probieren Sie es aus
<label for="avatar">Choose a profile picture:</label>
<input type="file" id="avatar" name="avatar" accept="image/png, image/jpeg" />
label {
display: block;
font:
1rem "Fira Sans",
sans-serif;
}
input,
label {
margin: 0.4rem 0;
}
Wert
Das value
-Attribut eines Datei-Inputs enthält einen String, der den Pfad zu den ausgewählten Dateien darstellt. Wenn noch keine Datei ausgewählt ist, ist der Wert ein leerer String (""
). Wenn der Benutzer mehrere Dateien ausgewählt hat, repräsentiert der value
die erste Datei in der Liste der ausgewählten Dateien. Die anderen Dateien können mithilfe der HTMLInputElement.files
-Eigenschaft des Eingabefelds identifiziert werden.
Hinweis:
Der Wert ist immer der Dateiname, der mit C:\fakepath\
präfixiert ist, was nicht der echte Pfad der Datei ist. Dies dient dazu, bösartige Software davon abzuhalten, die Dateistruktur des Benutzers zu erraten.
Zusätzliche Attribute
Zusätzlich zu den gemeinsamen Attributen, die alle <input>
-Elemente teilen, unterstützen Eingaben vom Typ file
auch die folgenden Attribute.
accept
Der Wert des accept
-Attributs ist ein String, der die Dateitypen definiert, die das Datei-Input akzeptieren soll. Dieser String ist eine kommagetrennte Liste von eindeutigen Dateityp-Spezifizierern. Da ein bestimmter Dateityp auf mehr als eine Weise identifiziert werden kann, ist es nützlich, eine umfassende Menge von Typ-Spezifizierern bereitzustellen, wenn Dateien eines bestimmten Formats benötigt werden.
Zum Beispiel gibt es mehrere Möglichkeiten, Microsoft Word-Dateien zu identifizieren, daher könnte eine Seite, die Word-Dateien akzeptiert, ein <input>
wie dieses verwenden:
<input
type="file"
id="docpicker"
accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" />
capture
Der Wert des capture
-Attributs ist ein String, der angibt, welche Kamera für die Erfassung von Bild- oder Videodaten verwendet werden soll, wenn das accept
-Attribut angibt, dass die Eingabe eine dieser Typen sein soll. Ein Wert von user
gibt an, dass die benutzerseitige Kamera und/oder das Mikrofon verwendet werden soll. Ein Wert von environment
gibt an, dass die nach außen gerichtete Kamera und/oder das Mikrofon verwendet werden soll. Wenn dieses Attribut fehlt, ist der User-Agent frei zu entscheiden, was er tun soll. Wenn der angeforderte Augenrichtung-Modus nicht verfügbar ist, kann der User-Agent auf seinen bevorzugten Standardmodus zurückgreifen.
Hinweis:
capture
war zuvor ein Boolesches Attribut, das, wenn vorhanden, verlangte, dass das Medienaufnahmegerät des Geräts wie Kamera oder Mikrofon anstelle des Datei-Inputs verwendet wird.
multiple
Wenn das multiple
-Boolesche-Attribut angegeben ist, erlaubt der Datei-Input dem Benutzer, mehr als eine Datei auszuwählen.
Nicht standardisierte Attribute
Zusätzlich zu den oben aufgeführten Attributen stehen die folgenden nicht standardisierten Attribute in einigen Browsern zur Verfügung. Sie sollten versuchen, deren Verwendung zu vermeiden, da dies die Fähigkeit Ihres Codes einschränkt, in Browsern zu funktionieren, die sie nicht implementieren.
webkitdirectory
Das Boolesche webkitdirectory
-Attribut, falls es vorhanden ist, zeigt an, dass nur Verzeichnisse vom Benutzer in der Datei-Auswahloberfläche ausgewählt werden können. Weitere Details und Beispiele finden Sie unter HTMLInputElement.webkitdirectory
.
Eindeutige Dateityp-Spezifizierer
Ein eindeutiger Dateityp-Spezifizierer ist ein String, der einen Dateityp beschreibt, der vom Benutzer in einem <input>
-Element vom Typ file
ausgewählt werden kann. Jeder eindeutige Dateitypspezifizierer kann eine der folgenden Formen annehmen:
- Eine gültige, nicht zwischen Groß- und Kleinschreibung unterscheidende Dateinamenserweiterung, beginnend mit einem Punkt (".") Zeichen. Zum Beispiel:
.jpg
,.pdf
oder.doc
. - Ein gültiger MIME-Type-String, ohne Erweiterungen.
- Der String
audio/*
, was "jede Audiodatei" bedeutet. - Der String
video/*
, was "jede Videodatei" bedeutet. - Der String
image/*
, was "jede Bilddatei" bedeutet.
Das accept
-Attribut nimmt einen String, der einen oder mehrere dieser eindeutigen Dateityp-Spezifizierer als Wert enthält, durch Kommas getrennt. Zum Beispiel könnte ein Dateiauswahldialog, der Inhalte benötigt, die als Bild präsentiert werden können, sowohl Standardbildformate als auch PDF-Dateien, so aussehen:
<input type="file" accept="image/*,.pdf" />
Verwendung von Datei-Inputs
Ein einfaches Beispiel
<form method="post" enctype="multipart/form-data">
<div>
<label for="file">Choose file to upload</label>
<input type="file" id="file" name="file" multiple />
</div>
<div>
<button>Submit</button>
</div>
</form>
Dies ergibt die folgende Ausgabe:
Hinweis: Sie können dieses Beispiel auch auf GitHub finden — sehen Sie den Quellcode an, und sehen Sie es auch live laufen.
Unabhängig vom Gerät oder Betriebssystem des Benutzers bietet der Datei-Input einen Button, der einen Dateiauswahldialog öffnet, der es dem Benutzer ermöglicht, eine Datei auszuwählen.
Das Einfügen des multiple
-Attributs, wie oben gezeigt, spezifiziert, dass mehrere Dateien auf einmal ausgewählt werden können. Der Benutzer kann mehrere Dateien aus der Dateiauswahl auswählen, auf eine Weise, die seine gewählte Plattform erlaubt (z.B. durch Halten der Shift oder Control-Taste und dann Klicken). Wenn Sie möchten, dass der Benutzer nur eine einzelne Datei pro <input>
auswählt, lassen Sie das multiple
-Attribut weg.
Informationen zu ausgewählten Dateien erhalten
Die ausgewählten Dateien werden von der HTMLInputElement.files
-Eigenschaft des Elements zurückgegeben, die ein FileList
-Objekt ist, das eine Liste von File
-Objekten enthält. Das FileList
verhält sich wie ein Array, daher können Sie seine length
-Eigenschaft überprüfen, um die Anzahl der ausgewählten Dateien zu erhalten.
Jedes File
-Objekt enthält die folgenden Informationen:
name
-
Der Name der Datei.
lastModified
-
Eine Nummer, die das Datum und die Uhrzeit angibt, zu der die Datei zuletzt bearbeitet wurde, in Millisekunden seit dem UNIX-Epoch (1. Januar 1970, um Mitternacht).
lastModifiedDate
Veraltet-
Ein
Date
-Objekt, das das Datum und die Uhrzeit angibt, zu der die Datei zuletzt bearbeitet wurde. Dies ist veraltet und sollte nicht verwendet werden. Verwenden Sie stattdessenlastModified
. size
-
Die Größe der Datei in Bytes.
type
-
Der MIME-Typ der Datei.
webkitRelativePath
Nicht standardisiert-
Ein String, der den Pfad der Datei relativ zum Basisverzeichnis angibt, das in einem Verzeichnisauswahldialog ausgewählt wurde (das heißt, einem
file
-Picker, in dem daswebkitdirectory
-Attribut gesetzt ist). Dies ist nicht standardisiert und sollte mit Vorsicht verwendet werden.
Akzeptierte Dateitypen einschränken
Oftmals möchten Sie nicht, dass der Benutzer jeden beliebigen Dateityp auswählen kann; stattdessen möchten Sie ihn oft dazu bringen, Dateien eines bestimmten Typs oder bestimmter Typen auszuwählen. Beispielsweise, wenn Ihr Datei-Input Benutzern erlaubt, ein Profilbild hochzuladen, möchten Sie wahrscheinlich, dass sie webkompatible Bildformate auswählen, wie JPEG oder PNG.
Akzeptable Dateitypen können mit dem accept
-Attribut spezifiziert werden, das eine kommagetrennte Liste von erlaubten Dateierweiterungen oder MIME-Typen nimmt. Einige Beispiele:
accept="image/png"
oderaccept=".png"
— Akzeptiert PNG-Dateien.accept="image/png, image/jpeg"
oderaccept=".png, .jpg, .jpeg"
— Akzeptiert PNG oder JPEG-Dateien.accept="image/*"
— Akzeptiert jede Datei mit einemimage/*
-MIME-Typ. (Viele mobile Geräte erlauben dem Benutzer auch, ein Bild mit der Kamera aufzunehmen, wenn dies verwendet wird.)accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document"
— Akzeptiert alles, was nach einem MS Word-Dokument riecht.
Sehen wir uns ein umfassenderes Beispiel an:
<form method="post" enctype="multipart/form-data">
<div>
<label for="profile_pic">Choose file to upload</label>
<input
type="file"
id="profile_pic"
name="profile_pic"
accept=".jpg, .jpeg, .png" />
</div>
<div>
<button>Submit</button>
</div>
</form>
Dies ergibt eine ähnliche Ausgabe wie das vorherige Beispiel:
Hinweis: Sie können dieses Beispiel auch auf GitHub finden — sehen Sie den Quellcode an, und sehen Sie es auch live laufen.
Es mag ähnlich aussehen, aber wenn Sie versuchen, mit diesem Input eine Datei auszuwählen, werden Sie feststellen, dass der Dateiauswahldialog es Ihnen nur erlaubt, die Dateitypen auszuwählen, die im accept
-Wert angegeben sind (die genaue Benutzeroberfläche unterscheidet sich je nach Browser und Betriebssystem).
Das accept
-Attribut validiert die Typen der ausgewählten Dateien nicht; es gibt Hinweise für Browser, um Benutzer zur Auswahl der richtigen Dateitypen zu führen. Es ist immer noch möglich (in den meisten Fällen) für Benutzer, eine Option im Dateiauswahldialog umzuschalten, die es ermöglicht, dies zu überschreiben und jede gewünschte Datei auszuwählen, und dann inkorrekte Dateitypen auszuwählen.
Aus diesem Grund sollten Sie sicherstellen, dass das accept
-Attribut durch geeignete serverseitige Validierung unterstützt wird.
Erkennen von Abbrüchen
Das cancel
-Ereignis wird ausgelöst, wenn der Benutzer seine Auswahl nicht ändert und die zuvor ausgewählten Dateien erneut auswählt. Das cancel
-Ereignis wird auch ausgelöst, wenn der Dateiauswahldialog über die "Abbrechen"-Taste oder die Escape-Taste geschlossen oder abgebrochen wird.
Zum Beispiel wird der folgende Code eine Nachricht in die Konsole protokollieren, wenn der Benutzer das Popup schließt, ohne eine Datei auszuwählen:
const elem = document.createElement("input");
elem.type = "file";
elem.addEventListener("cancel", () => {
console.log("Cancelled.");
});
elem.addEventListener("change", () => {
if (elem.files.length === 1) {
console.log("File selected: ", elem.files[0]);
}
});
elem.click();
Hinweise
-
Sie können den Wert eines Dateiauswahldialogs nicht über ein Skript setzen — so etwas wie das Folgende hat keine Wirkung:
jsconst input = document.querySelector("input[type=file]"); input.value = "foo";
-
Wenn eine Datei mit einem
<input type="file">
ausgewählt wird, wird der echte Pfad zur Quelldatei aus offensichtlichen Sicherheitsgründen nicht imvalue
-Attribut des Inputs angezeigt. Stattdessen wird der Dateiname angezeigt, mitC:\fakepath\
davor. Es gibt einige historische Gründe für diese Eigenart, aber sie wird in allen modernen Browsern unterstützt und ist in der Tat im Standard definiert.
Beispiele
In diesem Beispiel werden wir einen etwas fortgeschritteneren Dateiauswahldialog präsentieren, der die im HTMLInputElement.files
-Eigenschaft verfügbaren Datei-Informationen nutzt und einige clevere Tricks zeigt.
Hinweis: Sie können den vollständigen Quellcode für dieses Beispiel auf GitHub sehen — file-example.html (sehen Sie es auch live). Wir werden das CSS nicht erklären; der Schwerpunkt liegt auf dem JavaScript.
Zuerst schauen wir uns das HTML an:
<form method="post" enctype="multipart/form-data">
<div>
<label for="image_uploads">Choose images to upload (PNG, JPG)</label>
<input
type="file"
id="image_uploads"
name="image_uploads"
accept=".jpg, .jpeg, .png"
multiple />
</div>
<div class="preview">
<p>No files currently selected for upload</p>
</div>
<div>
<button>Submit</button>
</div>
</form>
Dies ähnelt dem, was wir zuvor gesehen haben — nichts Besonderes zu kommentieren.
Als Nächstes gehen wir das JavaScript durch.
In den ersten Zeilen des Skripts holen wir Referenzen auf das Formulareingabefeld selbst und das <div>
-Element mit der Klasse .preview
. Als nächstes verstecken wir das <input>
-Element — das tun wir, weil Datei-Inputs dazu neigen, hässlich, schwer zu stylen und inkonsistent im Design zwischen Browsern zu sein. Sie können das input
-Element aktivieren, indem Sie auf sein <label>
klicken, daher ist es besser, das input
visuell zu verstecken und das Label wie einen Button zu stylen, damit der Benutzer weiß, dass er damit interagieren soll, wenn er Dateien hochladen möchte.
const input = document.querySelector("input");
const preview = document.querySelector(".preview");
input.style.opacity = 0;
Hinweis:
opacity
wird verwendet, um das Datei-Input zu verstecken, anstatt visibility: hidden
oder display: none
, weil assistierende Technologien die beiden letzteren Stile so interpretieren, dass das Datei-Input nicht interaktiv ist.
Als nächstes fügen wir einen Ereignis-Listener zum Input hinzu, um auf Änderungen seines ausgewählten Wertes (in diesem Fall, wenn Dateien ausgewählt werden) zu hören. Der Ereignis-Listener ruft unsere benutzerdefinierte updateImageDisplay()
-Funktion auf.
input.addEventListener("change", updateImageDisplay);
Wann immer die updateImageDisplay()
-Funktion aufgerufen wird, führen wir Folgendes durch:
-
Verwenden Sie eine
while
-Schleife, um den vorherigen Inhalt des Preview-<div>
zu leeren. -
Holen Sie das
FileList
-Objekt, das die Informationen zu allen ausgewählten Dateien enthält, und speichern Sie es in einer Variable namenscurFiles
. -
Prüfen Sie, ob keine Dateien ausgewählt wurden, indem Sie prüfen, ob
curFiles.length
gleich 0 ist. Wenn ja, geben Sie eine Nachricht in das Preview-<div>
aus, die aussagt, dass keine Dateien ausgewählt wurden. -
Wenn Dateien ausgewählt wurden, durchlaufen wir jede einzelne davon und geben Informationen darüber in das Preview-
<div>
aus. Zu beachtende Punkte: -
Wir verwenden die benutzerdefinierte
validFileType()
-Funktion, um zu überprüfen, ob die Datei den korrekten Typ aufweist (z.B. die in demaccept
-Attribut angegebenen Bildtypen). -
Wenn sie es tut, dann:
- Drucken Sie ihren Namen und die Dateigröße in ein Listenelement innerhalb des vorherigen
<div>
(erhalten vonfile.name
undfile.size
). Die benutzerdefiniertereturnFileSize()
-Funktion gibt eine schön formatierte Version der Größe in Bytes/KB/MB zurück (standardmäßig meldet der Browser die Größe in absoluten Bytes). - Erstellen Sie eine Vorschaubild des Bildes, indem Sie
URL.createObjectURL(file)
aufrufen. Dann fügen Sie das Bild ebenfalls in das Listenelement ein, indem Sie ein neues<img>
-Element erstellen und seinsrc
auf das Vorschaubild setzen.
- Drucken Sie ihren Namen und die Dateigröße in ein Listenelement innerhalb des vorherigen
-
Wenn der Dateityp ungültig ist, zeigen wir eine Nachricht innerhalb eines Listenelements an, dass der Benutzer einen anderen Dateityp auswählen muss.
function updateImageDisplay() {
while (preview.firstChild) {
preview.removeChild(preview.firstChild);
}
const curFiles = input.files;
if (curFiles.length === 0) {
const para = document.createElement("p");
para.textContent = "No files currently selected for upload";
preview.appendChild(para);
} else {
const list = document.createElement("ol");
preview.appendChild(list);
for (const file of curFiles) {
const listItem = document.createElement("li");
const para = document.createElement("p");
if (validFileType(file)) {
para.textContent = `File name ${file.name}, file size ${returnFileSize(
file.size,
)}.`;
const image = document.createElement("img");
image.src = URL.createObjectURL(file);
image.alt = image.title = file.name;
listItem.appendChild(image);
listItem.appendChild(para);
} else {
para.textContent = `File name ${file.name}: Not a valid file type. Update your selection.`;
listItem.appendChild(para);
}
list.appendChild(listItem);
}
}
}
Die benutzerdefinierte validFileType()
-Funktion nimmt ein File
-Objekt als Parameter, dann verwendet sie Array.prototype.includes()
, um zu überprüfen, ob irgendein Wert in den fileTypes
den type
-Eigenschaftenwert der Datei entspricht. Wenn ein Treffer gefunden wird, gibt die Funktion true
zurück. Wenn kein Treffer gefunden wird, gibt sie false
zurück.
// https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Image_types
const fileTypes = [
"image/apng",
"image/bmp",
"image/gif",
"image/jpeg",
"image/pjpeg",
"image/png",
"image/svg+xml",
"image/tiff",
"image/webp",
"image/x-icon",
];
function validFileType(file) {
return fileTypes.includes(file.type);
}
Die returnFileSize()
-Funktion nimmt eine Zahl (in Bytes, genommen von der size
-Eigenschaft der aktuellen Datei) und wandelt sie in eine schön formatierte Größe in Bytes/KB/MB um.
function returnFileSize(number) {
if (number < 1e3) {
return `${number} bytes`;
} else if (number >= 1e3 && number < 1e6) {
return `${(number / 1e3).toFixed(1)} KB`;
}
return `${(number / 1e6).toFixed(1)} MB`;
}
Hinweis:
Die "KB"- und "MB"-Einheiten hier verwenden die SI-Einheitenpräfixe Konvention von 1KB = 1000B, ähnlich wie macOS. Verschiedene Systeme repräsentieren Dateigrößen unterschiedlich — zum Beispiel verwendet Ubuntu IEC-Präfixe, wo 1KiB = 1024B, während RAM-Spezifikationen oft SI-Prefixe verwenden, um Zweierpotenzen darzustellen (1KB = 1024B). Aus diesem Grund haben wir 1e3
(1000
) und 1e6
(1000000
) anstelle von 1024
und 1048576
verwendet. In Ihrer Anwendung sollten Sie das Einheitensystem Ihren Benutzern klar kommunizieren, wenn die genaue Größe wichtig ist.
Das Beispiel sieht so aus; probieren Sie es aus:
Technische Zusammenfassung
Wert | Ein String, der den Pfad zur ausgewählten Datei darstellt. |
Ereignisse | [`change`](/de/docs/Web/API/HTMLElement/change_event), [`input`](/de/docs/Web/API/Element/input_event) und [`cancel`](/de/docs/Web/API/HTMLInputElement/cancel_event) |
Unterstützte allgemeine Attribute | required |
Zusätzliche Attribute |
accept ,
capture ,
multiple
|
IDL-Attribute | files und value |
DOM-Schnittstelle | [`HTMLInputElement`](/de/docs/Web/API/HTMLInputElement) |
Methoden | [`select()`](/de/docs/Web/API/HTMLInputElement/select) |
Implizite ARIA-Rolle | keine entsprechende Rolle |
Spezifikationen
Specification |
---|
HTML # file-upload-state-(type=file) |
Browser-Kompatibilität
Siehe auch
- Verwenden von Dateien aus Webanwendungen — enthält eine Reihe anderer nützlicher Beispiele im Zusammenhang mit
<input type="file">
und der File API.