1. Web
  2. HTTP
  3. 參考
  4. 標頭
  5. Content-Disposition

Content-Disposition 頭

Baseline 已廣泛支援

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

HTTP Content-Disposition 頭指示內容是應該在瀏覽器中內聯顯示為網頁或網頁的一部分，還是應該作為附件本地下載。

在 multipart body（多部分主體）中，此頭必須用於每個子部分，以提供有關其對應欄位的資訊。子部分由 Content-Type 頭中定義的邊界分隔。當用於 body 本身時，Content-Disposition 沒有效果。

Content-Disposition 頭是在 MIME 訊息（用於電子郵件）的更大上下文中定義的，但只有一部分可能的引數適用於 HTTP 表單和 POST 請求。在 HTTP 上下文中，只能使用值 form-data，以及可選指令 name 和 filename。

頭型別 響應頭（用於主要主體），
請求頭，響應頭（用於多部分主體的子部分）
禁止請求頭 否

語法

作為主要主體的響應頭

HTTP 上下文中的第一個引數是 inline（預設值，表示可以在網頁內顯示，或作為網頁顯示）或 attachment（表示應該下載；大多數瀏覽器會顯示“另存為”對話方塊，如果存在 filename 引數的值，則會預填充）。

http
Content-Disposition: inline
Content-Disposition: attachment
Content-Disposition: attachment; filename="file name.jpg"
Content-Disposition: attachment; filename*=UTF-8''file%20name.jpg

檔名周圍的引號是可選的，但如果檔名中包含特殊字元（例如空格），則必須使用引號。

引數 filename 和 filename* 的唯一區別在於 filename* 使用 RFC 5987 第 3.2 節中定義的編碼。當在單個頭欄位值中同時存在 filename 和 filename* 時，如果兩者都可理解，則優先使用 filename*。建議兩者都包含以實現最大相容性，你可以透過將非 ASCII 字元替換為 ASCII 等效字元（例如將 é 轉換為 e）將 filename* 轉換為 filename。你可能希望避免在 filename 中使用百分號轉義序列，因為它們在瀏覽器中的處理方式不一致。（Firefox 和 Chrome 會解碼它們，而 Safari 不會。）

瀏覽器可能會應用轉換以符合檔案系統要求，例如將路徑分隔符（/ 和 \）轉換為下劃線（_）。

注意：Chrome 以及 Firefox 82 及更高版本，優先於 Content-Disposition: inline 引數（對於同源 URL）使用 HTML <a> 元素的 download 屬性。早期版本的 Firefox 優先使用頭，並將內容內聯顯示。

作為多部分主體的頭

multipart/form-data 主體需要一個 Content-Disposition 頭來提供有關表單每個子部分的資訊（例如，對於每個表單欄位和作為欄位資料一部分的任何檔案）。第一個指令始終是 form-data，並且頭還必須包含一個 name 引數來標識相關欄位。附加指令不區分大小寫，並且其引數在 = 符號後使用帶引號的字串語法。多個引數用分號 (;) 分隔。

http
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"

指令

name

後跟一個字串，其中包含此子部分內容所引用的表單中 HTML 欄位的名稱。當處理同一欄位中的多個檔案時（例如，<input type="file"> 元素的 multiple 屬性），可能存在多個具有相同名稱的子部分。

值為 '_charset_' 的 name 表示該部分不是 HTML 欄位，而是用於沒有明確字元集資訊的部分的預設字元集。

檔名

後跟一個字串，其中包含傳輸檔案的原始名稱。此引數主要提供指示性資訊。RFC2183 中的建議適用。

  • 儘可能優先使用 ASCII 字元（客戶端可以進行百分比編碼，只要伺服器實現能夠解碼）。
  • 應剝離任何路徑資訊，例如將 / 替換為 _。
  • 寫入磁碟時，不應覆蓋現有檔案。
  • 避免建立具有安全隱患的特殊檔案，例如在命令搜尋路徑上建立檔案。
  • 滿足其他檔案系統要求，例如受限字元和長度限制。

請注意，請求頭沒有 filename* 引數，也不允許 RFC 5987 編碼。

示例

觸發資源下載提示

以下響應在瀏覽器中觸發“另存為”對話方塊

http
200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="cool.html"
Content-Length: 21

<HTML>Save me!</HTML>

HTML 檔案將被下載而不是在瀏覽器中顯示。大多數瀏覽器將提示使用者預設使用 cool.html 檔名儲存它（如 filename 指令中指定）。

HTML 釋出 multipart/form-data 內容型別

以下示例顯示了一個使用 multipart/form-data 並使用 Content-Disposition 頭髮送的 HTML 表單。實際上，邊界值 delimiter123 將是一個瀏覽器生成的字串，例如 ----8721656041911415653955004498

http
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--

規範

規範
在超文字傳輸協議 (HTTP) 中使用 Content-Disposition 頭欄位
# 頭.欄位.定義
從表單返回值：multipart/form-data
# 第 4.2 節

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面由 MDN 貢獻者 最後修改於 。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.