内容处置

在常规的 HTTP 响应中，**Content-Disposition** 响应头指示内容是预期在浏览器中内联显示，即作为网页或网页的一部分，还是作为附件下载并保存到本地。

在 multipart/form-data 主体中，HTTP **Content-Disposition** 通用头是必须在多部分主体的每个子部分上使用的头，以提供有关其所应用字段的信息。子部分由Content-Type 头中定义的边界分隔。在主体本身使用 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="filename.jpg"
Content-Disposition: attachment; filename*="filename.jpg"

文件名周围的引号是可选的，但如果您在文件名中使用特殊字符，例如空格，则需要使用引号。

参数 filename 和 filename* 仅在 filename* 使用 RFC 5987 中定义的编码方面有所不同。当 filename 和 filename* 都在一个头字段值中存在时，如果两者都理解，则 filename* 比 filename 更优先。建议同时包含两者以确保最大的兼容性，您可以通过将非 ASCII 字符替换为 ASCII 等效字符（例如，将 é 转换为 e）将 filename* 转换为 filename。您可能希望避免在 filename 中使用百分比转义序列，因为它们在不同浏览器之间处理方式不一致。（Firefox 和 Chrome 会解码它们，而 Safari 不会。）

浏览器可能会应用转换以符合文件系统要求，例如将路径分隔符（/ 和 \）转换为下划线 (_)。

注意：Chrome 和 Firefox 82 及更高版本将 HTML <a> 元素 的 download 属性优先于 Content-Disposition: inline 参数（对于 同源 URL）。早期版本的 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 属性），可以有几个具有相同名称的子部分。

name 的值为 '_charset_' 表示该部分不是 HTML 字段，而是用于没有显式字符集信息的子部分的默认字符集。

filename

后面跟着一个字符串，其中包含传输文件的原始名称。此参数主要提供指示性信息。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 文件名（默认情况下）。

使用 Content-Disposition 头的 multipart/form-data 格式发布的 HTML 表单示例

http
POST /test.html HTTP/1.1
Host: example.org
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="field1"

value1
--boundary
Content-Disposition: form-data; name="field2"; filename="example.txt"

value2
--boundary--

规范

规范
超文本传输协议 (HTTP) 中 Content-Disposition 头字段的使用
# header.field.definition
从表单返回的值：multipart/form-data
# section-4.2

浏览器兼容性

BCD 表格只能在浏览器中加载

另请参阅