Content-Disposition header

Syntax

Als Antwort-Header für den Hauptteil

Der erste Parameter im HTTP-Kontext ist entweder inline (Standardwert, der angibt, dass er innerhalb der Webseite oder als die Webseite angezeigt werden kann) oder attachment (was angibt, dass er heruntergeladen werden sollte; die meisten Browser zeigen ein 'Speichern unter'-Dialogfenster an, das mit dem Wert der filename-Parameter vorausgefüllt ist, falls 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 Codierung verwendet. Wenn sowohl filename als auch filename* in einem einzigen Headerfeldwert vorhanden sind, wird filename* gegenüber 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 (z. B. é durch e ersetzen). Es kann sinnvoll sein, Prozent-Escape-Sequenzen in filename zu vermeiden, da diese in Browsern unterschiedlich behandelt werden. (Firefox und Chrome dekodieren sie, während Safari dies nicht tut.)

Browser können Transformationen anwenden, um den Anforderungen des Dateisystems zu entsprechen, z. B. Pfadtrenner (/ und \) in Unterstriche (_) umwandeln.

Als Header für einen multipart-Body

Ein multipart/form-data-Body erfordert einen Content-Disposition-Header, um Informationen über jeden Unterabschnitt 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 case-sensitiv. Der Wert von Argumenten (nach dem =-Zeichen) kann entweder ein Token oder eine Zeichenkette in Anführungszeichen sein. Zeichenketten in Anführungszeichen werden empfohlen, und viele Serverimplementierungen erfordern die Werte in Anführungszeichen. Der Grund dafür ist, dass ein Token für MIME-Typ-Header wie Content-Disposition US-ASCII sein muss, und US-ASCII erlaubt einige Zeichen nicht, die in Dateinamen und anderen Werten üblich sind. 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 einer Zeichenkette gefolgt, die den Namen des HTML-Feldes im Formular enthält, auf das sich der Inhalt dieses Unterabschnitts bezieht. Beim Umgang mit mehreren Dateien im gleichen Feld (zum Beispiel das multiple-Attribut eines <input type="file">-Elements) können mehrere Unterabschnitte mit demselben Namen existieren.

Ein name mit dem Wert '_charset_' gibt an, dass der Teil kein HTML-Feld ist, sondern der Standard-Zeichensatz, der für Teile ohne explizite Zeichensatzinformationen verwendet werden soll.

filename

Wird von einer Zeichenkette gefolgt, die den ursprünglichen Namen der übermittelten Datei enthält. Dieser Parameter liefert hauptsächlich Hinweisinformationen. Die Vorschläge in RFC2183 gelten:

• Bevorzugen Sie ASCII-Zeichen, wenn möglich (der Client kann sie percent-kodieren, solange die Server-Implementierung sie dekodiert).
• Alle Pfadinformationen sollten entfernt werden, z. B. durch Ersetzen von / mit _.
• Beim Schreiben auf die Festplatte sollte keine vorhandene Datei überschrieben werden.
• Vermeiden Sie das Erstellen spezieller Dateien mit Sicherheitsimplikationen, wie das Erstellen einer Datei im Befehls-Suchpfad.
• Erfüllen Sie andere Dateisystemanforderungen, wie eingeschränkte Zeichen und Längenbeschränkungen.

Beachten Sie, dass der Anfrage-Header den Parameter filename* nicht hat und keine RFC 5987-Codierung zulässt.

Beispiele

Auslösen der Download-Aufforderung für eine Ressource

Die folgende Antwort löst das "Speichern unter"-Dialog in einem 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 Benutzer standardmäßig auffordern, sie mit dem Dateinamen cool.html zu speichern (wie in der filename-Direktive angegeben).

HTML-Posting mit multipart/form-data-Inhaltstyp

Das folgende Beispiel zeigt ein HTML-Formular, das mithilfe von multipart/form-data unter Verwendung des Content-Disposition-Headers gesendet wurde. In der Praxis wäre der boundary-Wert delimiter123 eine browsergenerierte Zeichenkette 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-Körpers definiert.
• Die FormData-Schnittstelle, die verwendet wird, um Formulardaten für die Verwendung in den fetch()- oder XMLHttpRequest-APIs vorzubereiten.