Content-Disposition

Penggunaan

Dalam respons HTTP standar, header Content-Disposition mengontrol bagaimana browser menyajikan konten kepada pengguna. Menyetel nilainya ke inline memberi tahu browser untuk merender konten secara langsung. Menyetel nilainya ke attachment justru memicu dialog unduhan.

Header ini juga berperan dalam respons multipart/form-data dan pengiriman formulir. Setiap bagian dari badan multipart menyertakan field Content-Disposition tersendiri, yang mengidentifikasi nama field formulir serta nama berkas opsional untuk berkas yang diunggah. Batas antarbagian didefinisikan dalam header Content-Type.

inline

Direktif inline menginstruksikan browser untuk menampilkan konten secara langsung di dalam halaman. Ini adalah perilaku bawaan untuk sebagian besar respons ketika Content-Disposition tidak ada.

attachment

Direktif attachment memicu permintaan unduhan. Browser menampilkan dialog “Save As” alih-alih merender konten di viewport.

filename

Parameter filename menyarankan nama berkas bawaan untuk berkas yang diunduh. Nilainya diapit tanda kutip ganda dan mengikuti aturan pengodean ASCII.

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

filename*

Parameter filename* memperluas filename dengan dukungan pengodean karakter di luar ASCII. Ketika filename dan filename* sama-sama hadir, filename* yang diutamakan. Ini berguna untuk nama berkas yang mengandung karakter non-ASCII.

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

form-data

Direktif form-data muncul pada bagian-bagian badan multipart dan menandai bahwa konten tersebut merupakan bagian dari pengiriman formulir.

name

Parameter name wajib ada di dalam bagian-bagian badan multipart dan mengidentifikasi field formulir yang bersesuaian dengan bagian tersebut.

Contoh

Sebuah server yang merespons dengan unduhan berkas CSV menyetel attachment dan menyediakan saran nama berkas. Browser membuka dialog penyimpanan dengan “export.csv” yang sudah terisi.

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

Sebuah server yang menampilkan PDF langsung di browser menggunakan inline. Browser merender PDF tersebut di penampil bawaannya alih-alih mengunduh berkasnya.

Content-Disposition: inline

Dalam sebuah pengiriman formulir multipart, setiap bagian membawa field Content-Disposition tersendiri. Parameter name memetakan bagian tersebut ke field formulir yang bersesuaian, dan filename menunjukkan nama asli dari berkas yang diunggah.

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

Pemecahan masalah

Masalah unduhan dan tampilan pada Content-Disposition umumnya berasal dari nilai direktif yang keliru atau kesalahan pengodean nama berkas.

Berkas terunduh dengan nama yang salah. Browser menggunakan parameter filename sebagai nama simpan bawaan. Nilai filename yang hilang atau salah format menyebabkan browser kembali menggunakan path URL atau nama generik. Pastikan nilainya diapit tanda kutip ganda: filename=“report.pdf”. Verifikasi header tersebut dengan curl -I https://example.re/file dan periksa parameter filename pada responsnya.

Karakter non-ASCII pada nama berkas rusak atau tampil sebagai karakter kacau. Parameter filename hanya mendukung karakter ASCII. Untuk nama yang mengandung huruf beraksen, karakter CJK, atau teks non-ASCII lainnya, tambahkan parameter filename* menggunakan sintaks pengodean: filename*=UTF-8”d%C3%B6cument.pdf. Sertakan keduanya, filename (cadangan ASCII) dan filename* (versi terkode), untuk kompatibilitas maksimal di berbagai browser.

Browser mengabaikan attachment dan menampilkan konten secara inline. Sebagian browser menimpa attachment untuk tipe konten yang dapat mereka render secara native, seperti PDF dan gambar. Header Content-Type memengaruhi perilaku ini. Menyetel Content-Type: application/octet-stream bersama attachment memaksa unduhan untuk tipe berkas apa pun. Ekstensi browser dan penampil bawaan (PDF.js) juga dapat menimpa direktif tersebut.

Tampilan inline terpicu padahal unduhan yang diharapkan. Header Content-Disposition yang hilang akan default ke inline untuk sebagian besar tipe konten. Server harus secara eksplisit mengirim attachment untuk memicu unduhan. Di nginx, tambahkan add_header Content-Disposition “attachment”; ke blok location yang relevan. Di Apache, gunakan Header set Content-Disposition “attachment” di dalam direktif atau .

Prioritas filename vs filename*. Ketika kedua parameter hadir, filename* yang diutamakan di semua browser modern. Klien lama yang tidak mendukung filename* akan kembali menggunakan filename. Selalu sertakan kedua parameter. Nilai filename* harus menggunakan percent-encoding untuk karakter khusus: filename*=UTF-8”na%C3%AFve.txt.

Helper respons unduhan spesifik framework. Sebagian besar framework web menyediakan metode bawaan untuk menyetel header unduhan. Django menggunakan FileResponse dengan parameter as_attachment. Express menggunakan res.download(). Flask menggunakan send_file() dengan as_attachment=True. Rails menggunakan send_data atau send_file dengan opsi disposition. Metode-metode ini menangani pengodean nama berkas dan pemformatan header, sehingga mengurangi kemungkinan kesalahan manual.