<input type="file"> HTML-Attributwert

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 Dateieingabefelds enthält eine Zeichenkette, die den Pfad zu den ausgewählten Dateien repräsentiert. Wenn noch keine Datei ausgewählt ist, ist der Wert eine leere Zeichenkette (""). 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 über die Eigenschaft HTMLInputElement.files des Eingabefeldes identifiziert werden.

Zusätzliche Attribute

Zusätzlich zu den allgemeinen Attributen, die alle <input>-Elemente teilen, unterstützen Eingaben vom Typ file auch die folgenden Attribute.

accept

Der Wert des accept-Attributs ist eine Zeichenkette, die die Dateitypen definiert, die die Dateieingabe akzeptieren soll. Diese Zeichenkette ist eine durch Kommas getrennte Liste von einzigartigen Dateitypspezifizierern. Da ein gegebener Dateityp auf mehr als eine Weise identifiziert werden kann, ist es nützlich, eine umfassende Menge von Typenspezifizierern bereitzustellen, wenn Dateien eines bestimmten Formats benötigt werden.

Zum Beispiel gibt es verschiedene Möglichkeiten, Microsoft Word-Dateien zu identifizieren. Eine Seite, die Word-Dateien akzeptiert, könnte ein <input> wie folgt 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 eine Zeichenkette, die angibt, welche Kamera zur Aufnahme von Bild- oder Videodaten verwendet werden soll, wenn das accept-Attribut angibt, dass die Eingabe einer dieser Typen sein sollte. Ein Wert von user gibt an, dass die benutzerorientierte 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, kann der User Agent selbst entscheiden, was zu tun ist. Wenn der angeforderte Modus nicht verfügbar ist, kann der User Agent auf seinen bevorzugten Standardmodus zurückgreifen.

multiple

Wenn das multiple Boolean-Attribut angegeben ist, erlaubt das Dateieingabefeld dem Benutzer, mehr als eine Datei auszuwählen.

Nicht-standardisierte Attribute

Zusätzlich zu den oben aufgelisteten Attributen sind die folgenden nicht-standardisierten Attribute in einigen Browsern verfügbar. Sie sollten versuchen, ihre Verwendung zu vermeiden, da es die Fähigkeit Ihres Codes einschränkt, in Browsern, die sie nicht implementieren, zu funktionieren.

webkitdirectory

Das Boolean-Attribut webkitdirectory, falls vorhanden, gibt an, dass der Benutzer in der Dateiauswahloberfläche nur Verzeichnisse auswählen kann. Weitere Details und Beispiele finden Sie unter HTMLInputElement.webkitdirectory.

Einzigartige Dateitypspezifizierer

Ein einzigartiger Dateitypspezifizierer ist eine Zeichenkette, die eine Art von Datei beschreibt, die vom Benutzer in einem <input>-Element des Typs file ausgewählt werden kann. Jeder einzigartige Dateitypspezifizierer kann eine der folgenden Formen annehmen:

• Eine gültige, nicht auf Groß-/Kleinschreibung achtende Dateierweiterung, die mit einem Punkt (".") beginnt. Zum Beispiel: .jpg, .pdf, oder .doc.
• Eine gültige MIME-Typ-Zeichenkette, ohne Erweiterungen.
• Die Zeichenkette audio/*, was "jede Audiodatei" bedeutet.
• Die Zeichenkette video/*, was "jede Videodatei" bedeutet.
• Die Zeichenkette image/*, was "jede Bilddatei" bedeutet.

Das accept-Attribut nimmt eine Zeichenkette, die einen oder mehrere dieser einzigartigen Dateitypspezifizierer als ihren Wert enthält, getrennt durch Kommas. Zum Beispiel könnte ein Dateiauswahldialog, der Inhalte benötigt, die als Bild präsentiert werden können, einschließlich sowohl Standard-Bildformate als auch PDF-Dateien, so aussehen:

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

Verwendung von Dateieingaben

Ein grundlegendes 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>

div {
  margin-bottom: 10px;
}

Dies erzeugt die folgende Ausgabe:

Unabhängig vom Gerät oder Betriebssystem des Benutzers bietet die Dateieingabe eine Schaltfläche, die einen Datei-Auswahldialog ö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 dem Dateiauswahldialog auf jede Weise auswählen, die ihre gewählte Plattform zulässt (z.B. durch Drücken der Shift oder Steuerung-Taste und dann Klicken). Wenn Sie nur möchten, dass der Benutzer 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, welches ein FileList-Objekt ist, das eine Liste von File-Objekten enthält. Die FileList verhält sich wie ein Array, sodass Sie ihre length-Eigenschaft überprüfen können, um die Anzahl der ausgewählten Dateien zu erhalten.

Jedes File-Objekt enthält die folgenden Informationen:

name

Der Name der Datei.

lastModified

Eine Zahl, die das Datum und die Uhrzeit angibt, zu der die Datei zuletzt geändert wurde, in Millisekunden seit dem UNIX-Epoch-Zeitstempel (1. Januar 1970, Mitternacht).

lastModifiedDate

Ein Date-Objekt, das das Datum und die Uhrzeit angibt, zu der die Datei zuletzt geändert wurde. Dies ist veraltet und sollte nicht verwendet werden. Verwenden Sie stattdessen lastModified.

size

Die Größe der Datei in Bytes.

type

Der MIME-Typ der Datei.

webkitRelativePath

Eine Zeichenkette, die den Pfad der Datei relativ zum Basispfad im ausgewählten Verzeichnisauswahldialog angibt (d.h. einem file-Auswahldialog, in dem das webkitdirectory-Attribut gesetzt ist). Dies ist nicht standardisiert und sollte mit Vorsicht verwendet werden.

Akzeptierte Dateitypen beschränken

Oft möchten Sie nicht, dass der Benutzer einen beliebigen Dateityp auswählt; stattdessen möchten Sie oft, dass er Dateien eines spezifischen Typs oder Typs auswählt. Beispielsweise, wenn Ihre Dateieingabe es Benutzern ermöglicht, ein Profilbild hochzuladen, möchten Sie wahrscheinlich, dass sie web-kompatible Bildformate auswählen, wie JPEG oder PNG.

Akzeptable Dateitypen können mit dem accept-Attribut spezifiziert werden, das eine durch Kommas getrennte Liste von erlaubten Dateierweiterungen oder MIME-Typen annimmt. 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 image/*-MIME-Typ. (Viele Mobilgeräte lassen den Benutzer auch ein Bild mit der Kamera aufnehmen, 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.

Schauen wir uns ein etwas vollständigeres 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>

div {
  margin-bottom: 10px;
}

Dies erzeugt eine ähnlich aussehende Ausgabe wie das vorherige Beispiel:

Es sieht vielleicht ähnlich aus, aber wenn Sie versuchen, mit dieser Eingabe eine Datei auszuwählen, werden Sie sehen, dass der Dateiauswahl-Dialog mit dem accept-Wert nur die Dateitypen zulässt, die im accept-Wert spezifiziert sind (die genaue Schnittstelle unterscheidet sich je nach Browser und Betriebssystem).

Das accept-Attribut validiert nicht die Typen der ausgewählten Dateien; es bietet Hinweise für Browser, um Benutzer dazu zu bringen, die richtigen Dateitypen auszuwählen. Es ist (in den meisten Fällen) immer noch möglich, dass Benutzer in der Dateiauswahl eine Option umschalten können, die dies ermöglicht und sie dann falsche Dateitypen auswählen können.

Aus diesem Grund sollten Sie sicherstellen, dass das accept-Attribut durch geeignete serverseitige Validierung gestützt wird.

Stornierungen erkennen

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 geschlossen oder über die "Abbrechen"-Schaltfläche oder die escape-Taste abgebrochen wird.

Zum Beispiel wird der folgende Code in der 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();

Notizen

1. Sie können den Wert eines Datei-Auswahlfelds nicht über ein Script setzen – etwas wie das Folgende hat keinen Effekt:

   js

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

2. Wenn eine Datei mit einer <input type="file"> ausgewählt wird, wird der tatsächliche Pfad zur Quelldatei aus offensichtlichen Sicherheitsgründen nicht im value-Attribut der Eingabe angezeigt. Stattdessen wird der Dateiname angezeigt, dem C:\fakepath\ vorangestellt wird. Es gibt einige historische Gründe für diese Besonderheit, aber sie wird in allen modernen Browsern unterstützt und ist tatsächlich in der Spezifikation definiert.

Beispiele

In diesem Beispiel werden wir einen etwas fortgeschritteneren Datei-Auswahl-Dialog vorstellen, der die in der HTMLInputElement.files-Eigenschaft verfügbaren Dateiinformationen nutzt und einige clevere Tricks vorführt.

Zuerst lassen Sie uns das HTML ansehen:

<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>

html {
  font-family: sans-serif;
}

form {
  background: #cccccc;
  margin: 0 auto;
  padding: 20px;
  border: 1px solid black;
}

form ol {
  padding-left: 0;
}

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

form img {
  height: 64px;
  order: 1;
}

form p {
  line-height: 32px;
  padding-left: 10px;
}

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

form label:hover,
form button:hover {
  background-color: #2d5ba3;
  color: white;
}

form label:active,
form button:active {
  background-color: #0d3f8f;
  color: white;
}

Dies ähnelt dem, was wir zuvor gesehen haben – nichts Besonderes zu erwähnen.

Als nächstes gehen wir durch das JavaScript.

In den ersten Skriptzeilen erhalten wir Referenzen zum Formulareingabefeld selbst und zum <div>-Element mit der Klasse .preview. Als nächstes verbergen wir das <input>-Element – wir tun dies, weil Datei-Eingaben dazu neigen, hässlich, schwer zu stylen und inkonsistent im Design über Browser hinweg 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 eine Schaltfläche zu stylen, damit der Benutzer weiß, dass er es anklicken soll, wenn er Dateien hochladen möchte.

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

input.style.opacity = 0;

Als nächstes fügen wir einen Ereignis-Listener zur Eingabe hinzu, um auf Änderungen ihrer ausgewählten Werte zu hören (in diesem Fall, wenn Dateien ausgewählt werden). Der Ereignis-Listener ruft unsere benutzerdefinierte updateImageDisplay()-Funktion auf.

input.addEventListener("change", updateImageDisplay);

Wann immer die updateImageDisplay()-Funktion aufgerufen wird, tun wir Folgendes:

• Verwenden Sie eine while-Schleife, um den vorherigen Inhalt des Vorschau-<div> zu leeren.

• Holen Sie das FileList-Objekt, das die Informationen zu allen ausgewählten Dateien enthält, und speichern Sie es in einer Variablen namens curFiles.

• Überprüfen Sie, ob keine Dateien ausgewählt wurden, indem Sie überprüfen, ob curFiles.length gleich 0 ist. Wenn ja, drucken Sie eine Nachricht in das Vorschau-<div>, dass keine Dateien ausgewählt wurden.

• Wenn Dateien ausgewählt wurden, durchlaufen wir jede einzelne und drucken Informationen darüber in das Vorschau-<div>. Zu beachtende Punkte sind:

• Wir verwenden die benutzerdefinierte validFileType()-Funktion, um zu überprüfen, ob die Datei vom korrekten Typ ist (z.B. die Bildtypen, die im accept-Attribut spezifiziert sind).

• Falls ja, dann:

  • Drucken wir den Namen und die Dateigröße in einem Listenelement innerhalb des vorherigen <div> aus (erhalten von file.name und file.size). Die benutzerdefinierte returnFileSize()-Funktion gibt eine schön formatierte Version der Größe in Bytes/KB/MB zurück (standardmäßig gibt der Browser die Größe in absoluten Bytes an).
  • Erstellen Sie eine Miniaturansicht des Bildes, indem URL.createObjectURL(file) aufgerufen wird. Fügen Sie dann das Bild ebenfalls in das Listenelement ein, indem eine neue <img> erstellt und ihr src auf die Miniaturansicht gesetzt wird.

• Wenn der Dateityp ungültig ist, wird eine Nachricht in einem Listenelement angezeigt, die den Benutzer darüber informiert, dass er 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 und verwendet Array.prototype.includes(), um zu überprüfen, ob ein Wert in fileTypes dem type-Eigenschaft der Datei entspricht. Wenn ein Übereinstimmung gefunden wird, gibt die Funktion true zurück. Wenn keine Übereinstimmung 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 (von Bytes, entnommen aus der aktuellen size-Eigenschaft der 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`;
}

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

Das Beispiel sieht so aus; probieren Sie es aus:

Technische Zusammenfassung

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Verwendung von Dateien aus Webanwendungen — enthält eine Reihe weiterer nützlicher Beispiele im Zusammenhang mit <input type="file"> und der File API.