Content-Disposition header

Syntax

Als Response-Header für den Hauptkörper

Der erste Parameter im HTTP-Kontext ist entweder inline (Standardwert, der angibt, dass es innerhalb der Webseite oder als Webseite angezeigt werden kann) oder attachment (was darauf hinweist, dass es heruntergeladen werden sollte; die meisten Browser zeigen einen 'Speichern unter'-Dialog an, vorausgefüllt mit dem Wert der filename-Parameter, 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 beispielsweise 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, hat filename* Vorrang vor filename, wenn beide verstanden werden. Es wird empfohlen, beide für maximale Kompatibilität einzuschließen, und Sie können filename* in filename konvertieren, indem Sie nicht-ASCII-Zeichen durch ASCII-Äquivalente ersetzen (z. B. é zu e). Sie sollten Prozent-Escape-Sequenzen in filename vermeiden, da sie in verschiedenen 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. das Konvertieren von Pfadtrennzeichen (/ und \) zu Unterstrichen (_).

Als Header für einen multipart-Body

Ein multipart/form-data-Body erfordert einen Content-Disposition-Header, um Informationen über jeden Teil 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 jedes Arguments (nach dem =-Zeichen) kann entweder ein Token oder ein umschlossener String sein. Umschlossene Strings werden empfohlen, und viele Serverimplementierungen erfordern, dass die Werte umschlossen sind. Dies liegt daran, 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 gefolgt von einem String, der den Namen des HTML-Feldes im Formular enthält, auf das sich der Inhalt dieses Teils bezieht. Wenn Sie mit mehreren Dateien im selben Feld arbeiten (zum Beispiel das multiple-Attribut eines <input type="file">-Elements), kann es mehrere Teile mit demselben Namen geben.

Ein name mit dem Wert '_charset_' zeigt an, dass der Teil kein HTML-Feld ist, sondern die Standardzeichencodierung, die für Teile ohne explizite Zeichenkodierungsinformation verwendet wird.

filename

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

• Bevorzugen Sie nach Möglichkeit ASCII-Zeichen (der Client kann es prozentkodieren, solange die Serverimplementierung es dekodiert).
• Jede Pfadinformation sollte entfernt werden, indem z. B. / durch _ ersetzt wird.
• Beim Schreiben auf die Festplatte sollte keine vorhandene Datei überschrieben werden.
• Vermeiden Sie das Erstellen von speziellen Dateien mit Sicherheitsimplikationen, wie das Erstellen einer Datei im Befehlssuchpfad.
• Erfüllen Sie andere Anforderungen des Dateisystems, wie eingeschränkte Zeichen und Längenbeschränkungen.

Beachten Sie, dass der Request-Header keinen filename*-Parameter hat und keine RFC 5987-Kodierung erlaubt.

Beispiele

Herunterladen-Eingabeaufforderung für eine Ressource auslösen

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

HTML-Formular, das einen Content-Type multipart/form-data sendet

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 Begrenzungswert delimiter123 eine vom Browser generierte Zeichenfolge 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 Begrenzung des multipart-Bodys definiert.
• Das FormData-Interface, das zur Vorbereitung von Formulardaten für die Nutzung in den APIs fetch() oder XMLHttpRequest genutzt wird.