Content-Disposition

Verwendung

In einer Standard-HTTP-Antwort steuert der Content-Disposition-Header, wie der Browser dem Nutzer Inhalte präsentiert. Der Wert inline weist den Browser an, den Inhalt direkt zu rendern. Der Wert attachment löst stattdessen einen Download-Dialog aus.

Dieser Header spielt auch bei multipart/form-data-Antworten und Formularübermittlungen eine Rolle. Jeder Teil eines Multipart-Bodys enthält ein eigenes Content-Disposition-Feld, das den Formularfeldnamen und bei hochgeladenen Dateien einen optionalen Dateinamen angibt. Die Begrenzung der Teile wird im Content-Type-Header definiert.

inline

Die Direktive inline weist den Browser an, den Inhalt direkt innerhalb der Seite anzuzeigen. Fehlt Content-Disposition, ist dies bei den meisten Antworten das Standardverhalten.

attachment

Die Direktive attachment löst eine Download-Aufforderung aus. Der Browser zeigt einen “Speichern unter”-Dialog an, statt den Inhalt im Viewport zu rendern.

filename

Der Parameter filename schlägt einen Standarddateinamen für die heruntergeladene Datei vor. Der Wert wird in doppelte Anführungszeichen gesetzt und folgt den ASCII-Kodierungsregeln.

Content-Disposition: attachment; filename="report.pdf"

filename*

Der Parameter filename* erweitert filename um Unterstützung für Zeichenkodierungen jenseits von ASCII. Sind filename und filename* beide vorhanden, hat filename* Vorrang. Das ist bei Dateinamen mit Nicht-ASCII-Zeichen nützlich.

Content-Disposition: attachment; filename="document.pdf"; filename*=UTF-8''d%C3%B6cument.pdf

form-data

Die Direktive form-data erscheint in den Teilen eines Multipart-Bodys und kennzeichnet den Inhalt als Teil einer Formularübermittlung.

name

Der Parameter name ist innerhalb der Teile eines Multipart-Bodys erforderlich und gibt an, welchem Formularfeld der jeweilige Teil entspricht.

Beispiel

Ein Server, der mit dem Download einer CSV-Datei antwortet, setzt attachment und gibt einen vorgeschlagenen Dateinamen an. Der Browser öffnet einen Speicherdialog mit vorausgefülltem “export.csv”.

Content-Disposition: attachment; filename="export.csv"

Ein Server, der ein PDF direkt im Browser anzeigt, verwendet inline. Der Browser rendert das PDF in seinem eingebauten Viewer, statt die Datei herunterzuladen.

Content-Disposition: inline

Bei einer Multipart-Formularübermittlung trägt jeder Teil ein eigenes Content-Disposition-Feld. Der Parameter name ordnet den Teil dem entsprechenden Formularfeld zu, und filename gibt den ursprünglichen Namen einer hochgeladenen Datei an.

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

Fehlersuche

Download- und Anzeigeprobleme mit Content-Disposition gehen typischerweise auf falsche Direktivwerte oder Fehler bei der Dateinamenkodierung zurück.

Datei wird mit dem falschen Dateinamen heruntergeladen. Der Browser verwendet den Parameter filename als voreingestellten Speichernamen. Ein fehlender oder fehlerhaft formatierter filename-Wert führt dazu, dass der Browser auf den URL-Pfad oder einen generischen Namen zurückfällt. Stellen Sie sicher, dass der Wert in doppelte Anführungszeichen gesetzt ist: filename=“report.pdf”. Prüfen Sie den Header mit curl -I https://example.re/file und kontrollieren Sie den Parameter filename in der Antwort.

Nicht-ASCII-Zeichen in Dateinamen werden beschädigt oder als Zeichensalat angezeigt. Der Parameter filename unterstützt nur ASCII-Zeichen. Fügen Sie bei Namen mit Akzentbuchstaben, CJK-Zeichen oder anderem Nicht-ASCII-Text den Parameter filename* mit der Kodierungssyntax hinzu: filename*=UTF-8”d%C3%B6cument.pdf. Geben Sie sowohl filename (ASCII-Rückfallwert) als auch filename* (kodierte Fassung) an, um größtmögliche Kompatibilität über alle Browser hinweg zu erreichen.

Der Browser ignoriert attachment und zeigt den Inhalt inline an. Manche Browser übergehen attachment bei Inhaltstypen, die sie nativ rendern, etwa PDFs und Bilder. Der Content-Type-Header beeinflusst dieses Verhalten. Setzt man neben attachment zusätzlich Content-Type: application/octet-stream, erzwingt das einen Download für jeden Dateityp. Auch Browsererweiterungen und eingebaute Viewer (PDF.js) können die Direktive übergehen.

Inline-Anzeige wird ausgelöst, obwohl ein Download erwartet wird. Fehlt der Content-Disposition-Header, gilt für die meisten Inhaltstypen standardmäßig inline. Der Server muss attachment explizit senden, um einen Download auszulösen. Fügen Sie in nginx dem betreffenden location-Block add_header Content-Disposition “attachment”; hinzu. Verwenden Sie in Apache Header set Content-Disposition “attachment” innerhalb einer - oder -Direktive.

Vorrang von filename gegenüber filename*. Sind beide Parameter vorhanden, hat filename* in allen modernen Browsern Vorrang. Ältere Clients, die filename* nicht unterstützen, fallen auf filename zurück. Geben Sie stets beide Parameter an. Der Wert von filename* muss Sonderzeichen prozentkodiert enthalten: filename*=UTF-8”na%C3%AFve.txt.

Framework-spezifische Hilfsmethoden für Download-Antworten. Die meisten Web-Frameworks bieten eingebaute Methoden zum Setzen von Download-Headern. Django verwendet FileResponse mit dem Parameter as_attachment. Express verwendet res.download(). Flask verwendet send_file() mit as_attachment=True. Rails verwendet send_data oder send_file mit einer disposition-Option. Diese Methoden übernehmen die Dateinamenkodierung und die Header-Formatierung und verringern so die Gefahr manueller Fehler.