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 上查看此页面 • 报告此内容的问题