HTML-Attributwert <input type="file">

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 Attribut value eines Dateieingabefelds enthält eine Zeichenfolge, die den Pfad zu den ausgewählten Dateien darstellt. Wenn noch keine Datei ausgewählt wurde, ist der Wert eine leere Zeichenfolge (""). Wenn Benutzer mehrere Dateien ausgewählt haben, bezieht sich value auf die erste Datei in der Liste der ausgewählten Dateien. Die anderen Dateien lassen sich über die Eigenschaft HTMLInputElement.files des Eingabefelds ermitteln.

Zusätzliche Attribute

Neben den gemeinsamen Attributen aller <input>-Elemente unterstützen Eingabefelder vom Typ file auch die folgenden Attribute.

accept

Der Wert des Attributs accept ist eine Zeichenfolge, die festlegt, welche Dateitypen das Dateieingabefeld akzeptieren soll. Diese Zeichenfolge ist eine durch Kommas getrennte Liste eindeutiger Dateitypbezeichner. Da ein bestimmter Dateityp auf mehr als eine Weise identifiziert werden kann, empfiehlt es sich, mehrere passende Bezeichner anzugeben, wenn Sie Dateien eines bestimmten Formats benötigen.

Microsoft-Word-Dateien lassen sich beispielsweise auf verschiedene Weise identifizieren. Eine Website, die Word-Dateien akzeptiert, könnte daher 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 Attributs capture ist eine Zeichenfolge, die festlegt, welche Kamera zum Aufnehmen von Bild- oder Videodaten verwendet werden soll, sofern das Attribut accept angibt, dass das Eingabefeld einen dieser Typen akzeptieren soll. Der Wert user gibt an, dass die dem Benutzer zugewandte Kamera und/oder das entsprechende Mikrofon verwendet werden soll. Der Wert environment legt fest, dass die nach außen gerichtete Kamera und/oder das entsprechende Mikrofon verwendet werden soll. Fehlt dieses Attribut, kann der User Agent selbst entscheiden, wie er vorgeht. Ist die angeforderte Ausrichtung nicht verfügbar, kann der User Agent auf seinen bevorzugten Standardmodus zurückgreifen.

multiple

Wenn das boolesche Attribut multiple angegeben ist, können Benutzer im Dateieingabefeld mehr als eine Datei auswählen.

webkitdirectory

Das boolesche Attribut webkitdirectory gibt, sofern vorhanden, an, dass in der Dateiauswahl nur Verzeichnisse zur Auswahl stehen sollen. Weitere Informationen und Beispiele finden Sie unter HTMLInputElement.webkitdirectory.

Eindeutige Dateitypbezeichner

Ein eindeutiger Dateitypbezeichner ist eine Zeichenfolge, die einen Dateityp beschreibt, den Benutzer in einem <input>-Element vom Typ file auswählen können. Jeder eindeutige Dateitypbezeichner kann eine der folgenden Formen haben:

• Eine gültige Dateiendung, bei der die Groß- und Kleinschreibung keine Rolle spielt und die mit einem Punkt („.“) beginnt. Zum Beispiel: .jpg, .pdf oder .doc.
• Eine gültige MIME-Typ-Zeichenfolge ohne Erweiterungen.
• Die Zeichenfolge audio/* für „beliebige Audiodatei“.
• Die Zeichenfolge video/* für „beliebige Videodatei“.
• Die Zeichenfolge image/* für „beliebige Bilddatei“.

Das Attribut accept erhält als Wert eine Zeichenfolge mit einem oder mehreren dieser eindeutigen Dateitypbezeichner, die durch Kommas getrennt sind. Eine Dateiauswahl, die Inhalte benötigt, die als Bild dargestellt werden können – einschließlich gängiger Bildformate und PDF-Dateien –, könnte beispielsweise so aussehen:

<input type="file" accept="image/*,.pdf" />

Dateieingabefelder verwenden

Ein einfaches Beispiel

<div>
  <label for="file">Choose file to upload</label>
  <input type="file" id="file" name="file" multiple />
</div>

div {
  margin-bottom: 10px;
}

Dies ergibt die folgende Ausgabe:

Unabhängig vom Gerät oder Betriebssystem der Benutzer stellt das Dateieingabefeld eine Schaltfläche bereit, die ein Dialogfeld zur Dateiauswahl öffnet.

Das oben gezeigte Attribut multiple legt fest, dass mehrere Dateien gleichzeitig ausgewählt werden können. Benutzer können mehrere Dateien auf jede Weise auswählen, die ihre Plattform unterstützt (etwa indem sie Umschalt oder Strg gedrückt halten und dann klicken). Wenn pro <input> nur eine Datei ausgewählt werden soll, lassen Sie das Attribut multiple weg.

Informationen zu ausgewählten Dateien abrufen

Die ausgewählten Dateien werden über die Eigenschaft HTMLInputElement.files des Elements bereitgestellt. Sie enthält ein FileList-Objekt mit einer Liste von File-Objekten. FileList verhält sich wie ein Array; über seine Eigenschaft length können Sie daher die Anzahl der ausgewählten Dateien ermitteln.

Jedes File-Objekt enthält die folgenden Informationen:

name

Den Namen der Datei.

lastModified

Eine Zahl, die angibt, wann die Datei zuletzt geändert wurde, in Millisekunden seit Beginn der UNIX-Epoche (1. Januar 1970 um Mitternacht).

lastModifiedDate

Ein Date-Objekt, das angibt, wann die Datei zuletzt geändert wurde. Diese Eigenschaft ist veraltet und sollte nicht verwendet werden. Verwenden Sie stattdessen lastModified.

size

Die Größe der Datei in Bytes.

type

Den MIME-Typ der Datei.

webkitRelativePath

Eine Zeichenfolge, die den Pfad der Datei relativ zum Basisverzeichnis angibt, das in einer Verzeichnisauswahl ausgewählt wurde (also in einer file-Auswahl mit gesetztem Attribut webkitdirectory). Diese Eigenschaft ist nicht standardisiert und sollte mit Vorsicht verwendet werden.

Akzeptierte Dateitypen einschränken

Häufig sollen Benutzer nicht jeden beliebigen Dateityp auswählen können, sondern Dateien eines oder mehrerer bestimmter Typen. Wenn Benutzer über Ihr Dateieingabefeld beispielsweise ein Profilbild hochladen können, möchten Sie vermutlich, dass sie webkompatible Bildformate wie JPEG oder PNG auswählen.

Zulässige Dateitypen können Sie mit dem Attribut accept festlegen. Es erhält eine durch Kommas getrennte Liste zulässiger Dateiendungen oder MIME-Typen. Einige Beispiele:

• accept="image/png" oder accept=".png" — Akzeptiert PNG-Dateien.
• accept="image/png, image/jpeg" oder accept=".png, .jpg, .jpeg" — Akzeptiert PNG- oder JPEG-Dateien.
• accept="image/*" — Akzeptiert jede Datei mit einem MIME-Typ image/*. (Auf vielen Mobilgeräten können Benutzer damit auch ein Foto mit der Kamera aufnehmen.)
• accept=".doc,.docx,.xml,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" — Akzeptiert Dateien, die als MS-Word-Dokumente infrage kommen.

Sehen wir uns ein ausführlicheres Beispiel an:

<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 {
  margin-bottom: 10px;
}

Dies ergibt eine Ausgabe, die dem vorherigen Beispiel ähnelt:

Das Ergebnis sieht zwar ähnlich aus, doch wenn Sie versuchen, über dieses Eingabefeld eine Datei auszuwählen, werden Sie feststellen, dass die Dateiauswahl nur die im Wert von accept angegebenen Dateitypen auswählen lässt (die genaue Benutzeroberfläche hängt vom Browser und Betriebssystem ab).

Das Attribut accept validiert die Typen der ausgewählten Dateien nicht. Es gibt Browsern lediglich Hinweise, damit diese Benutzer bei der Auswahl der richtigen Dateitypen unterstützen können. In den meisten Fällen können Benutzer in der Dateiauswahl eine Option aktivieren, mit der sie diese Einschränkung umgehen und beliebige Dateien auswählen können – auch solche mit einem falschen Dateityp.

Stellen Sie deshalb sicher, dass das Attribut accept durch eine geeignete serverseitige Validierung ergänzt wird.

Abbrüche erkennen

Das Ereignis cancel wird ausgelöst, wenn Benutzer ihre Auswahl nicht ändern, sondern die zuvor ausgewählten Dateien erneut auswählen. Das Ereignis cancel wird auch ausgelöst, wenn das Dialogfeld zur Dateiauswahl geschlossen oder über die Schaltfläche „Abbrechen“ beziehungsweise die Taste Esc abgebrochen wird.

Der folgende Code schreibt beispielsweise eine Meldung in die Konsole, wenn Benutzer das Dialogfeld schließen, ohne eine Datei auszuwählen:

const elem = document.createElement("input");
elem.type = "file";
elem.addEventListener("cancel", () => {
  console.log("Canceled.");
});
elem.addEventListener("change", () => {
  if (elem.files.length === 1) {
    console.log("File selected: ", elem.files[0]);
  }
});
elem.click();

Hinweise

1. Sie können den Wert einer Dateiauswahl nicht über ein Skript setzen – ein Versuch wie der folgende hat keine Wirkung:

   js

   const input = document.querySelector("input[type=file]");
   input.value = "foo";
   

2. Wenn eine Datei über ein <input type="file"> ausgewählt wird, erscheint der tatsächliche Pfad zur Quelldatei aus naheliegenden Sicherheitsgründen nicht im Attribut value des Eingabefelds. Stattdessen wird der Dateiname mit vorangestelltem C:\fakepath\ angezeigt. Diese Besonderheit hat historische Gründe, wird aber von allen modernen Browsern unterstützt und ist sogar in der Spezifikation definiert.

Beispiele

Vollständiges Dateibeispiel

In diesem Beispiel erstellen wir eine etwas erweiterte Dateiauswahl. Sie nutzt die Dateiinformationen aus der Eigenschaft HTMLInputElement.files und zeigt einige nützliche Kniffe.

HTML

Das HTML sieht so aus:

<div class="file-picker">
  <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 type="button">Submit</button>
  </div>
</div>

html {
  font-family: sans-serif;
}

.file-picker {
  background: #cccccc;
  margin: 0 auto;
  padding: 20px;
  border: 1px solid black;
}

.file-picker ol {
  padding-left: 0;
}

.file-picker li,
div > p {
  background: #eeeeee;
  display: flex;
  justify-content: space-between;
  margin-bottom: 10px;
  list-style-type: none;
  border: 1px solid black;
}

.file-picker img {
  height: 64px;
  order: 1;
}

.file-picker p {
  line-height: 32px;
  padding-left: 10px;
}

.file-picker label,
.file-picker button {
  background-color: #7f9ccb;
  padding: 5px 10px;
  border-radius: 5px;
  border: 1px ridge black;
  font-size: 0.8rem;
  height: auto;
}

.file-picker label:hover,
.file-picker button:hover {
  background-color: #2d5ba3;
  color: white;
}

.file-picker label:active,
.file-picker button:active {
  background-color: #0d3f8f;
  color: white;
}

Dies ähnelt dem, was wir bereits gesehen haben, daher gehen wir nicht näher darauf ein. Das auf das Beispiel angewendete CSS haben wir ebenfalls ausgeblendet, da es für das Verständnis des Dateieingabefelds und des zugehörigen JavaScripts nicht relevant ist.

JavaScript

In den ersten Skriptzeilen holen wir Referenzen auf das Formulareingabefeld selbst und auf das <div>-Element mit der Klasse .preview. Anschließend blenden wir das <input>-Element aus. Dateieingabefelder sind häufig wenig ansprechend, schwer zu gestalten und unterscheiden sich im Design zwischen Browsern. Das input-Element lässt sich durch einen Klick auf sein <label> aktivieren. Daher ist es besser, das input visuell auszublenden und das Label wie eine Schaltfläche zu gestalten. So erkennen Benutzer, womit sie interagieren müssen, um Dateien hochzuladen.

const input = document.querySelector("input");
const preview = document.querySelector(".preview");

input.style.opacity = 0;

Als Nächstes fügen wir dem Eingabefeld einen Event Listener hinzu, der auf Änderungen der Auswahl reagiert (in diesem Fall auf die Auswahl von Dateien). Der Event Listener ruft unsere benutzerdefinierte Funktion updateImageDisplay() auf.

input.addEventListener("change", updateImageDisplay);

Bei jedem Aufruf der Funktion updateImageDisplay() gehen wir wie folgt vor:

• Wir verwenden eine while-Schleife, um den bisherigen Inhalt des Vorschau-<div> zu entfernen.
• Wir holen das FileList-Objekt mit den Informationen zu allen ausgewählten Dateien und speichern es in einer Variablen namens curFiles.
• Wir prüfen anhand von curFiles.length, ob keine Dateien ausgewählt wurden. Ist der Wert gleich 0, geben wir im Vorschau-<div> eine entsprechende Meldung aus.
• Wurden Dateien ausgewählt, durchlaufen wir sie einzeln und geben Informationen zu jeder Datei im Vorschau-<div> aus. Dabei ist Folgendes zu beachten:
  • Mit der benutzerdefinierten Funktion validFileType() prüfen wir, ob die Datei den richtigen Typ hat (etwa einen der im Attribut accept angegebenen Bildtypen).
  • Ist dies der Fall:
    • Wir geben den Namen und die Dateigröße in einem Listeneintrag innerhalb des zuvor genannten <div> aus (aus file.name und file.size). Die benutzerdefinierte Funktion returnFileSize() gibt die Größe formatiert in Bytes/KB/MB zurück (standardmäßig meldet der Browser die Größe als absolute Bytezahl).
    • Wir erzeugen mit URL.createObjectURL(file) ein Vorschaubild. Anschließend fügen wir es ebenfalls in den Listeneintrag ein, indem wir ein neues <img>-Element erstellen und dessen src auf das Vorschaubild setzen.
• Ist der Dateityp ungültig, zeigen wir in einem Listeneintrag eine Meldung an, die Benutzer auffordert, einen anderen Dateityp auszuwählen.

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 Funktion validFileType() nimmt ein File-Objekt als Parameter entgegen. Anschließend prüft sie mit Array.prototype.includes(), ob ein Wert in fileTypes mit der Eigenschaft type der Datei übereinstimmt. Wird eine Übereinstimmung gefunden, gibt die Funktion true zurück, andernfalls false.

// 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 Funktion returnFileSize() nimmt eine Zahl entgegen (die Anzahl der Bytes aus der Eigenschaft size der aktuellen Datei) und wandelt sie in eine formatierte Größenangabe 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`;
}

const button = document.querySelector(".file-picker button");
button.addEventListener("click", () => {
  const para = document.createElement("p");
  para.append("Image uploaded!");
  preview.replaceChildren(para);
});

Ergebnis

Technische Zusammenfassung

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Dateien aus Webanwendungen verwenden — enthält weitere nützliche Beispiele zu <input type="file"> und der File API.