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

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

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

Синтаксис

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

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

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*, а не filename. Для наилучшей совместимости рекомендуется указывать оба параметра. Можно преобразовать filename* в filename, заменив символы не из ASCII их эквивалентами ASCII (например, преобразовав é в e). Лучше избегать последовательностей экранирования процентов в filename, поскольку браузеры обрабатывают их по-разному. (Firefox и Chrome декодируют их, а Safari — нет.)

Браузеры могут преобразовывать имя файла с учётом требований файловой системы, например заменять разделители пути (/ и \) символами подчёркивания (_).

В качестве заголовка для тела, состоящего из нескольких частей

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

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

За ней следует строка, содержащая исходное имя передаваемого файла. Этот параметр носит в основном справочный характер. Применимы рекомендации из RFC 2183:

• По возможности используйте символы ASCII (клиент может закодировать их с помощью процентного кодирования, если серверная реализация затем декодирует их).
• Следует удалять сведения о пути, например заменять / на _.
• При записи на диск не следует перезаписывать существующий файл.
• Не создавайте специальные файлы, которые могут представлять угрозу безопасности, например файл в каталоге поиска команд.
• Учитывайте и другие требования файловой системы, например ограничения на символы и длину имени.

Обратите внимание: заголовок запроса не содержит параметр filename* и не поддерживает кодирование RFC 5987.

Примеры

Вызов диалога загрузки ресурса

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

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

В следующем примере показана HTML-форма, отправленная с помощью multipart/form-data и заголовка Content-Disposition. На практике значение разделителя delimiter123 было бы строкой, сгенерированной браузером, например ----8721656041911415653955004498:

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

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

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

См. также

• HTML-формы
• Заголовок Content-Type, определяющий разделитель тела, состоящего из нескольких частей.
• Интерфейс FormData, используемый для подготовки данных формы к использованию в API fetch() или XMLHttpRequest.