Content-Disposition

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

В обычном 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

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

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Content-Disposition

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
See implementation notes.

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

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

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

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