Content-Disposition

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

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

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

Тип заголовка	Заголовок ответа (для тела ответа простого типа) Основной заголовок (для каждой части составного тела)
Запрещённое имя заголовка	нет

Синтаксис

Как заголовок ответа с обычным телом

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

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

Как заголовок в составном теле

Первым параметром в контексте HTTP всегда является form-data; дополнительные параметры регистронезависимые и могут иметь аргументы, значения которых следуют после знака '=' и берутся в кавычки. Несколько параметров разделяются через точку с запятой (';').

Content-Disposition: form-data
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", но только в случае когда оба значения корректны.

Примеры

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

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

<HTML>Save me!</HTML>

Простой HTML-файл будет сохранён как обычное сохранение с диалогом "Сохранить как" вместо отображения контента файла в браузере. Большинство браузеров предложат его сохранить под именем cool.html (это поведение по умолчанию).

Пример HTML-формы, переданной через POST с использованием формата 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--

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

Спецификация	Название
RFC 7578	Returning Values from Forms: multipart/form-data
RFC 6266	Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)
RFC 2183	Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field

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

Update compatibility data on GitHub

	Компьютеры						Мобильные
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome для Android	Firefox для Android	Opera для Android	Safari on iOS	Samsung Internet
`Content-Disposition`	Chrome Полная поддержка Да	Edge Полная поддержка Да	Firefox Полная поддержка Да	IE Полная поддержка Да	Opera Полная поддержка Да	Safari Полная поддержка Да	WebView Android Полная поддержка Да	Chrome Android Полная поддержка Да	Firefox Android Полная поддержка Да	Opera Android Полная поддержка Да	Safari iOS Полная поддержка Да	Samsung Internet Android Полная поддержка Да

Легенда

Полная поддержка: Полная поддержка

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

Firefox 5 обрабатывает Content-Disposition заголовка HTTP-ответа response более эффективно, если присутствуют оба параметра filename и filename*; он просматривает сначала все предоставленные имена filename*, даже есть вначале идут filename. Ранее использовалось первое найденное имя. See баг 588781.

Смотрите также

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

Последнее изменение: Mar 23, 2019, by MDN contributors