Content-Disposition header

Syntax

Als Antwort-Header für den Hauptteil

Der erste Parameter im HTTP-Kontext ist entweder inline (Standardwert, der anzeigt, dass es innerhalb der Webseite oder als die Webseite angezeigt werden kann) oder attachment (was anzeigt, dass es heruntergeladen werden sollte; die meisten Browser präsentieren einen 'Speichern unter'-Dialog, vorab ausgefüllt mit dem Wert der filename-Parameter, wenn vorhanden).

Content-Disposition: inline
Content-Disposition: attachment
Content-Disposition: attachment; filename="file name.jpg"
Content-Disposition: attachment; filename*=UTF-8''file%20name.jpg

Die Anführungszeichen um den Dateinamen sind optional, aber notwendig, wenn Sie Sonderzeichen im Dateinamen verwenden, wie z.B. Leerzeichen.

Die Parameter filename und filename* unterscheiden sich nur darin, dass filename* die in RFC 5987, Abschnitt 3.2 definierte Kodierung verwendet. Wenn sowohl filename als auch filename* in einem einzelnen Header-Feldwert vorhanden sind, wird filename* bevorzugt, wenn beide verstanden werden. Es wird empfohlen, beide zur maximalen Kompatibilität einzuschließen, und Sie können filename* in filename umwandeln, indem Sie nicht-ASCII-Zeichen durch ASCII-Äquivalente ersetzen (wie das Ersetzen von é durch e). Sie sollten vermeiden, Prozent-Escape-Sequenzen in filename zu verwenden, da diese in verschiedenen Browsern unterschiedlich behandelt werden. (Firefox und Chrome dekodieren sie, während Safari dies nicht tut.)

Browser können Transformationen anwenden, um den Dateisystemanforderungen zu entsprechen, wie zum Beispiel das Konvertieren von Pfadtrennzeichen (/ und \) in Unterstriche (_).

Als Header für einen Multipart-Body

Ein multipart/form-data Body erfordert einen Content-Disposition Header, um Informationen über jeden Teilbereich des Formulars bereitzustellen (z.B. für jedes Formularfeld und alle Dateien, die Teil der Felddaten sind). Die erste Direktive ist immer form-data, und der Header muss auch einen name-Parameter enthalten, um das relevante Feld zu identifizieren. Zusätzliche Direktiven sind nicht groß-/kleinschreibungsempfindlich. Der Wert aller Argumente (nach dem =-Zeichen) kann entweder ein Zeichen oder ein in Anführungszeichen gesetzter String sein. In Anführungszeichen gesetzte Strings werden empfohlen, und viele Serverimplementierungen erfordern, dass die Werte in Anführungszeichen gesetzt werden. Dies liegt daran, dass ein Zeichen US-ASCII sein muss für MIME-Typ-Header wie Content-Disposition, und US-ASCII erlaubt keine Zeichen, die in Dateinamen und anderen Werten häufig vorkommen. Mehrere Parameter werden durch ein Semikolon (;) getrennt.

Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"

Direktiven

name

Wird von einem String gefolgt, der den Namen des HTML-Feldes im Formular enthält, auf das sich der Inhalt dieses Teilbereichs bezieht. Beim Umgang mit mehreren Dateien im selben Feld (zum Beispiel dem multiple Attribut eines <input type="file"> Elements), kann es mehrere Teilbereiche mit demselben Namen geben.

Ein name mit einem Wert von '_charset_' zeigt an, dass der Teil nicht ein HTML-Feld ist, sondern der Standardzeichensatz, der für Teile ohne explizite Zeichensatzinformationen verwendet werden soll.

filename

Wird von einem String gefolgt, der den ursprünglichen Namen der übertragenen Datei enthält. Dieser Parameter bietet hauptsächlich indikative Informationen. Die Vorschläge in RFC2183 gelten:

• Bevorzugen Sie wenn möglich ASCII-Zeichen (der Client kann sie prozentual kodieren, solange die Server-Implementierung sie dekodiert).
• Jegliche Pfadinformationen sollten entfernt werden, indem zum Beispiel / durch _ ersetzt wird.
• Beim Speichern auf der Festplatte sollte keine vorhandene Datei überschrieben werden.
• Vermeiden Sie die Erstellung spezieller Dateien mit Sicherheitsimplikationen, wie das Erstellen einer Datei im Suchpfad der Befehle.
• Erfüllen Sie andere Dateisystemanforderungen, wie eingeschränkte Zeichen und Längenbeschränkungen.

Beachten Sie, dass der Anfragen-Header nicht den filename* Parameter hat und keine RFC 5987 Kodierung erlaubt.

Beispiele

Herunterladen-Dialog für eine Ressource auslösen

Die folgende Antwort löst das "Speichern unter"-Dialogfeld im Browser aus:

200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="cool.html"
Content-Length: 21

<HTML>Save me!</HTML>

Die HTML-Datei wird heruntergeladen, anstatt im Browser angezeigt zu werden. Die meisten Browser werden die Benutzer auffordern, sie standardmäßig unter dem Dateinamen cool.html zu speichern (wie im filename-Parameter angegeben).

HTML-Formular mit multipart/form-data Inhaltstyp

Das folgende Beispiel zeigt ein HTML-Formular, das mit multipart/form-data unter Verwendung des Content-Disposition Headers gesendet wird. In der Praxis wäre der Grenzwert delimiter123 ein vom Browser generierter String wie ----8721656041911415653955004498:

POST /test.html HTTP/1.1
Host: example.org
Content-Type: multipart/form-data;boundary="delimiter123"

--delimiter123
Content-Disposition: form-data; name="field1"

value1
--delimiter123
Content-Disposition: form-data; name="field2"; filename="example.txt"

value2
--delimiter123--

Spezifikationen

Browser-Kompatibilität

Siehe auch

• HTML-Formulare
• Der Content-Type, der die Grenze des Multipart-Bodys definiert.
• Die FormData Schnittstelle, die verwendet wird, um Formulardaten für die Verwendung in den fetch() oder XMLHttpRequest APIs vorzubereiten.