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.

Em uma resposta HTTP normal, o cabeçalho de resposta Content-Disposition indica se o conteúdo é esperado a ser exibido inline no navegador, isso significa, como uma página Web ou parte de uma, ou como um anexo, que é baixado e salvo localmente.

Em um corpo multipart/form-data, o cabeçalho geral HTTP Content-Disposition é um cabeçalho que pode ser utilizado em uma subparte de um corpo multipartes para dar informações sobre o campo a que ele se aplica. A subparte é delimitada pelo limite definido no cabeçalho Content-Type. Usado no corpo em si, Content-Disposition não tem efeito.

O cabeçalho Content-Disposition é definido em um grande contexto de mensagens MIME para e-mail, mas somente um subconjunto dos possíveis parâmetros são aplicados à formulários HTTP e requisições POST requests. Somente o valor form-data, assim como a diretiva opcional name e filename, podem ser usadas no contexto HTTP.

Tipo de cabeçalho Response header (para o corpo principal)
General header (para a subparte de um corpo multipartes)
Forbidden header name não

Sintaxe

Como cabeçalho de resposta para o corpo principal

O primeiro parâmetro no contexto HTTP ou é inline (valor padrão, indicando que ele pode ser mostrado dentro de uma página Web, ou como uma página Web) ou attachment (indicando que ele deve ser baixado; a maioria dos navegadores apresenta uma caixa de diálogo "Salvar como", pré-preenchido com o valor do parâmetro filename se presente).

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

Como cabeçalho para um corpo multipartes

O primeiro parâmetro no contexto HTTP é sempre o form-data. Parâmetros adicionais são case-insensitive e possuem argumentos que usam a sintaxe de cadeia de caracteres delimitadas por aspas depois do sinal '='. Múltiplos parâmetros são separados por um ponto e vírgula (';').

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

Diretivas

name

O nome é seguido por uma cadeia de caracteres contendo o nome do campo HTML no formulário que o conteúdo dessa subparte se refere. Quando lidando com múltiplos arquivos no mesmo campo (por exemplo, o atributo multiple de um elemento {HTMLElement("input","<input type=\"file\">")}}), podem haver diversas subpartes com o mesmo nome.

Um name com o valor de '_charset_' indica que a parte não é um campo HTML, mas uma codificação para usar em partes sem explicitar a informação de codificação.

filename

É seguido por uma cadeia de caracteres contendo o nome original do arquivo transmitido. O nome do arquivo é sempre opcional e não deve ser usado cegamente pela aplicação: informação de caminho deve ser removida, e conversão para as regras do sistema de arquivo do servidor devem ser feitas. Este parâmetro provém a maior parte da informação indicativa. Quando usado em combinação com Content-Disposition: attachment, ele é usado como nome de arquivo padrão para uma eventual caixa de diálogo "Salvar como" apresentado ao usuário.

filename*

Os parâmetros "filename" e "filename*" se diferenciam somente no fato de que "filename*" usa a codificação definida na RFC 5987. Quando ambos "filename" e "filename*" estão presentes em um único campo de valor do cabeçalho, "filename*" é preferido sobre "filename" quando ambos são entendidos.

Exemplos

Uma resposta ativando a caixa de diálogo "Salvar como":

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

<HTML>Me salve!</HTML>

O simples arquivo HTML será salvo como um download regular ao invés de ser mostrado no navegador. A maioria dos navegadores irá propôr salvar o arquivo como nome de cool.html (por padrão).

Um exemplo de um formulário de HTML postado usando o formato multipart/form-data que faz o uso do cabeçalho 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--

Especificações

Especificação Título
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

Compatibilidade com navegadores

BCD tables only load in the browser

Notas de compatibilidade

  • Firefox 5 lida com o cabeçalho de resposta HTTP Content-Disposition mais efetivamente se ambos parâmetros filename e filename* são providos; ele olha através de todos os nomes providenciados, usando o parâmetro filename* se um estiver disponível, mesmo se o parâmetro filename estiver incluído primeiro. Anteriormente, o primeiro parâmetro que combinasse seria utilizado, Previously, the first matching parameter would be used, desse modo prevenindo um nome mais apropriado de ser utilizado. Veja Erro do Firefox 588781.

Veja também