Content-Disposition header

Syntax

Als Antwort-Header für den Hauptteil

Der erste Parameter im HTTP-Kontext ist entweder inline (Standardwert, was bedeutet, dass er innerhalb der Webseite angezeigt werden kann, oder als die Webseite) oder attachment (was bedeutet, dass er heruntergeladen werden sollte; die meisten Browser zeigen einen 'Speichern unter'-Dialog an, der, wenn vorhanden, mit dem Wert der filename-Parameter vorausgefüllt ist).

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 spezielle Zeichen im Dateinamen verwenden, wie Leerzeichen.

Die Parameter filename und filename* unterscheiden sich nur dadurch, dass filename* die in RFC 5987, Abschnitt 3.2 definierte Kodierung verwendet. Wenn sowohl filename als auch filename* in einem einzelnen Header-Feld vorhanden sind, wird filename* bevorzugt, wenn beide verstanden werden. Es wird empfohlen, beide für maximale Kompatibilität einzuschließen, und Sie können filename* zu filename konvertieren, indem Sie nicht-ASCII-Zeichen durch ASCII-Äquivalente ersetzen (wie z.B. é zu e). Es wird empfohlen, Prozent-Escape-Sequenzen in filename zu vermeiden, da sie in verschiedenen Browsern uneinheitlich 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, wie z.B. das Ersetzen von Pfadtrennzeichen (/ und \) durch Unterstriche (_).

Als Header für einen Multipart-Body

Ein multipart/form-data-Body erfordert einen Content-Disposition-Header, um Informationen über jede Untereinheit 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 entsprechende Feld zu identifizieren. Zusätzliche Direktiven sind nicht case-sensitive. Der Wert von Argumenten (nach dem = Zeichen) kann entweder ein Token oder eine zitierte Zeichenkette sein. Zitierte Zeichenfolgen werden empfohlen, und viele Serverimplementierungen erfordern, dass die Werte zitiert werden. Dies liegt daran, dass ein Token für MIME-Type-Header wie Content-Disposition US-ASCII sein muss, und US-ASCII erlaubt einige in Dateinamen und anderen Werten häufig vorkommende Zeichen nicht. 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 dieser Untereinheit bezieht. Wenn Sie mit mehreren Dateien im selben Feld arbeiten (zum Beispiel das multiple-Attribut eines <input type="file">-Elements), kann es mehrere Untereinheiten mit dem gleichen Namen geben.

Ein name mit einem Wert von '_charset_' zeigt an, dass der Teil kein HTML-Feld ist, sondern den Standard-Charset angibt, der für Teile ohne explizite Charset-Informationen verwendet wird.

filename

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

• Bevorzugen Sie nach Möglichkeit ASCII-Zeichen (der Client kann es codieren, solange die Server-Implementierung es dekodiert).
• Alle Pfadinformationen sollten entfernt werden, z.B. durch Ersetzen von / durch _.
• Beim Speichern auf der Festplatte sollte keine vorhandene Datei überschrieben werden.
• Vermeiden Sie es, spezielle Dateien mit Sicherheitsimplikationen zu erstellen, z.B. eine Datei im Befehls-Suchpfad zu erstellen.
• Erfüllen Sie andere Dateisystemanforderungen, wie z.B. eingeschränkte Zeichen und Längenbeschränkungen.

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

Beispiele

Auslösen eines Download-Dialogs für eine Ressource

Die folgende Antwort löst den "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 den Benutzern standardmäßig vorschlagen, sie mit dem Dateinamen cool.html zu speichern (wie in der filename-Direktive angegeben).

HTML-Formular das multipart/form-data Content-Type postet

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 Boundary-Wert delimiter123 eine vom Browser generierte 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-Bodys definiert.
• Das FormData-Interface, das zur Vorbereitung von Formulardaten für die Verwendung in den fetch()- oder XMLHttpRequest-APIs verwendet wird.