13.04.2025

Download forçado de PDF do servidor: Content-Disposition

Resposta Rápida

Para iniciar o download de um arquivo para o disco rígido do usuário, use o cabeçalho HTTP Content-Disposition: attachment. Isso geralmente é configurado no servidor por meio de código ou configuração. Em um simples script PHP, fica assim:

header('Content-Disposition: attachment; filename="libereOKraken.txt"');

O nome do arquivo "libereOKraken.txt" é apenas um exemplo; você pode substituí-lo por qualquer outro nome, e esse código solicitará ao navegador do usuário que comece a baixar o arquivo para o seu disco local.

Mais sobre Downloads de Arquivos

HTML5 à Sua Disposição

Para iniciar um download de arquivo no lado do cliente, você pode usar o atributo download na tag <a> do HTML5:

<a href="/caminho/para/oKraken" download="KrakenLiberado.pdf">Baixar o Kraken</a>

O navegador executará esse comando e salvará o arquivo com o nome e extensão especificados.

Alternativa para Navegadores Antigos

Se você precisa suportar navegadores mais antigos, como o MSIE11, que não suportam o atributo download, pode criar um objeto Blob e iniciar o download manualmente:

function baixarKrakenIE(dataUri, nomeArquivo) {
  var blob = new Blob([dataUri]);
  window.navigator.msSaveOrOpenBlob(blob, nomeArquivo);
}

// Exemplo de uso:
baixarKrakenIE(uriDataAntigo, 'oKraken');

Método Universal para Download de Arquivos

Devido às diferenças no suporte entre navegadores, faz sentido combinar todos os métodos em uma única função para garantir a compatibilidade:

function baixarKraken(dataUri, nomeArquivo) {
  if (window.navigator.msSaveOrOpenBlob) { // Para IE11 e Edge
    baixarKrakenIE(dataUri, nomeArquivo);
  } else {
    // Para navegadores modernos
    var link = document.createElement("a");
    link.href = dataUri;
    link.download = nomeArquivo;
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
  }
}

// Pronto para a aventura?
var dataUri = 'data:text/plain;charset=utf-8,Libere%20o%20Kraken!';
baixarKraken(dataUri, 'oKraken.txt');

Tratamento de Erros Durante Downloads

Certifique-se de gerenciar exceções durante o processo de download para manter o usuário informado sobre possíveis problemas:

try {
  libereOKraken(); // Sua função de download
} catch(e) {
  alert('Aviso: O Kraken não pode ser liberado: ' + e.message);
}

Visualização

Para visualizar, você pode pensar no cabeçalho Content-Disposition como placas de sinalização:

Requisição do navegador: "Eu preciso desse arquivo."
Resposta do servidor com Content-Disposition: "Por favor, salve-o no seu disco rígido!"

Sem "Content-Disposition":
Arquivo ➡️ 🌐 (abre no navegador)

Com "Content-Disposition":
Arquivo ➡️ 💾 (oferecido para salvar)

Lição Principal: Content-Disposition significa "caminho para a pasta de downloads":

Content-Disposition: attachment; filename="guiade.pdf" 📄➡️💾
// Sem desvios. Estamos indo direto para o seu disco rígido.

Evitando Armadilhas em Downloads

Codificando Caracteres Especiais

Ao especificar o nome do arquivo no cabeçalho Content-Disposition, é crucial codificar corretamente caracteres especiais para evitar problemas. Use rawurlencode em PHP ou encodeURIComponent em JavaScript para isso:

header('Content-Disposition: attachment; filename="' . rawurlencode($nomeArquivo) . '"');

Sobrescrever Cabeçalhos—Uma Questão Delicada

Quando manusear Content-Disposition, tenha cuidado para não sobrescrever cabeçalhos existentes. Dado que a última configuração tem prioridade, entender como trabalhar com cabeçalhos no seu idioma ou framework de programação escolhido é extremamente importante.

Recomendações para Operações Suaves em Navegadores

Ao forçar um download, sempre configure corretamente o cabeçalho Content-Type para coincidir com o tipo de arquivo:

header('Content-Type: application/pdf');

Recursos Úteis

1. Content-Disposition - HTTP | MDN
2. RFC 6266 - Uso do Campo de Cabeçalho Content-Disposition
3. Como codificar o parâmetro filename do cabeçalho Content-Disposition em HTTP - Stack Overflow
4. Atributo Download no HTML - W3Schools
5. HTTP/1.1: Aplicações
6. GitHub - pillarjs/send: Suporte a Servidor de Arquivo Estático

Video

Navigation