Контент-Расположение

В обычном HTTP-ответе заголовок Content-Disposition — это заголовок, указывающий, ожидается ли отображение содержимого встроенно в браузере, то есть как веб-страницы или как части веб-страницы, или как приложение, которое загружается и сохраняется локально.

В теле multipart/form-data, HTTP-заголовок Content-Disposition является заголовком, который необходимо использовать для каждого подраздела multipart-тела, чтобы предоставить информацию о поле, к которому он относится. Подраздел ограничен границей, определенной в заголовке Content-Type. Применение к самому телу Content-Disposition не оказывает никакого эффекта.

Заголовок Content-Disposition определен в более широком контексте MIME-сообщений для электронной почты, но только подмножество возможных параметров применимо к HTTP-формам и запросам POST. В контексте HTTP могут использоваться только значение form-data, а также необязательные директивы name и filename.

Тип заголовка	Заголовок ответа (для основного тела), Заголовок запроса, Заголовок ответа (для подраздела multipart-тела)
Запрещённое имя заголовка	нет

Синтаксис

В качестве заголовка ответа для основного тела

Первый параметр в контексте HTTP — это либо inline (значение по умолчанию, указывающее, что он может отображаться внутри веб-страницы или как сама веб-страница), либо attachment (указывающее, что его нужно загрузить; большинство браузеров отображают диалоговое окно «Сохранить как», предварительно заполненное значением параметров filename при наличии).

Content-Disposition: inline
Content-Disposition: attachment
Content-Disposition: attachment; filename="filename.jpg"

Примечание: Chrome и Firefox 82 и выше отдают приоритет атрибуту HTML-элемента <a> download над параметром Content-Disposition inline (для ссылок с одним происхождением). Более ранние версии Firefox отдают приоритет заголовку и отобразят содержимое встроенно.

В качестве заголовка для multipart-тела

Тело multipart/form-data требует заголовка Content-Disposition для предоставления информации для каждого подраздела формы (например, для каждого поля формы и любых файлов, которые являются частью данных поля). Первая директива всегда form-data, и заголовок должен также содержать параметр name для идентификации соответствующего поля. Дополнительные директивы не зависят от регистра и имеют аргументы, которые используют синтаксис строковых значений после знака '='. Несколько параметров разделяются точкой с запятой (';').

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

Директивы

name

Следуют за строкой, содержащей имя HTML-поля в форме, к которому относится содержимое данного подраздела. При работе с несколькими файлами в одном поле (например, атрибут multiple элемента <input type="file">), может быть несколько подразделов с одинаковым именем.

Значение name со значением '_charset_' указывает, что часть не является HTML-полем, но кодировкой по умолчанию для частей без явной информации о кодировке.

filename

Следуют за строкой, содержащей исходное имя переданного файла. Имя файла всегда является необязательным и не должно использоваться приложением бездумно: информация о пути должна быть удалена, и преобразование в правила файловой системы сервера должно быть выполнено. Этот параметр предоставляет в основном справочную информацию. При использовании в сочетании с Content-Disposition: attachment, он используется в качестве имени файла по умолчанию для потенциального диалогового окна «Сохранить как», представленного пользователю.

filename*

Параметры filename и filename* отличаются только тем, что filename* использует кодировку, определённую в RFC 5987. Когда оба filename и filename* присутствуют в одном значении поля заголовка, filename* предпочтительнее filename при обоих понимании.

Предупреждение: строка, следующая за filename должна всегда заключаться в кавычки; но по соображениям совместимости многие браузеры пытаются разобрать не заключённые в кавычки имена, содержащие пробелы.

Примеры

Ответ, вызывающий диалоговое окно «Сохранить как»:

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 (по умолчанию).

Пример HTML-формы, отправленной в формате multipart/form-data, который использует заголовок Content-Disposition:

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

Спецификации

Спецификация
Использование заголовка Content-Disposition в протоколе передачи гипертекста (HTTP) # header.field.definition
Возвращение значений из форм: multipart/form-data # section-4.2

Совместимость с браузерами

	Рабочий стол						Мобильный
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox для Android	Opera Android	Safari на IOS	Samsung Internet
`Content-Disposition`	Да	12	Да С версии 82, если атрибут элемента `<a>` <a> установлен (для URL с одним происхождением), то директива `inline` игнорируется. Более ранние версии не соответствовали спецификации и игнорировали атрибут в пользу заголовка. См. сбой 1658877.	Да	Да	Да	Да	Да	Да С версии 82, если атрибут элемента `<a>` <a> установлен (для URL с одним происхождением), то директива `inline` игнорируется. Более ранние версии не соответствовали спецификации и игнорировали атрибут в пользу заголовка. См. сбой 1658877.	Да	Да	Да

Примечания по совместимости

Firefox 5 обрабатывает HTTP-заголовок ответа Content-Disposition более эффективно, если предоставлены как параметр filename, так и filename*. Он просматривает все предоставленные имена, используя параметр filename*, если он доступен, даже если параметр filename указан первым. Прежде использовался первый совпадающий параметр, что не позволяло использовать более подходящее имя. См. сбой 588781.
Firefox 82 (и выше) и Chrome отдают приоритет атрибуту HTML-элемента <a> download над параметром Content-Disposition inline (для ссылок с одним происхождением). Более ранние версии Firefox отдают приоритет заголовку и отобразят содержимое встроенно.

См. также

HTML-формы
Определение Content-Type границы multipart-тела.
Интерфейс FormData, используемый для управления данными формы для использования в API XMLHttpRequest.

© 2005–2022 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition