Content-Disposition

Utilisation

Dans une réponse HTTP standard, l’en-tête Content-Disposition contrôle la façon dont le navigateur présente le contenu à l’utilisateur. Fixer la valeur à inline indique au navigateur d’afficher directement le contenu. Fixer la valeur à attachment déclenche à la place une boîte de dialogue de téléchargement.

Cet en-tête joue également un rôle dans les réponses multipart/form-data et les soumissions de formulaire. Chaque partie d’un corps multipart comporte son propre champ Content-Disposition, qui identifie le nom du champ de formulaire ainsi que, le cas échéant, le nom du fichier téléversé. La frontière entre les parties est définie dans l’en-tête Content-Type.

inline

La directive inline demande au navigateur d’afficher le contenu directement dans la page. C’est le comportement par défaut de la plupart des réponses lorsque Content-Disposition est absent.

attachment

La directive attachment déclenche une invite de téléchargement. Le navigateur présente une boîte de dialogue « Enregistrer sous » au lieu d’afficher le contenu dans la zone d’affichage.

filename

Le paramètre filename suggère un nom de fichier par défaut pour le fichier téléchargé. La valeur est entourée de guillemets doubles et suit les règles d’encodage ASCII.

Content-Disposition: attachment; filename="report.pdf"

filename*

Le paramètre filename* étend filename en prenant en charge des encodages de caractères au-delà d’ASCII. Lorsque filename et filename* sont tous deux présents, filename* est prioritaire. C’est utile pour les noms de fichiers contenant des caractères non ASCII.

Content-Disposition: attachment; filename="document.pdf"; filename*=UTF-8''d%C3%B6cument.pdf

form-data

La directive form-data apparaît dans les parties d’un corps multipart et indique que le contenu relève d’une soumission de formulaire.

name

Le paramètre name est obligatoire dans les parties d’un corps multipart et identifie le champ de formulaire auquel la partie correspond.

Exemple

Un serveur qui répond par le téléchargement d’un fichier CSV définit attachment et fournit un nom de fichier suggéré. Le navigateur ouvre une boîte de dialogue d’enregistrement pré-remplie avec « export.csv ».

Content-Disposition: attachment; filename="export.csv"

Un serveur qui affiche un PDF directement dans le navigateur utilise inline. Le navigateur affiche le PDF dans sa visionneuse intégrée au lieu de télécharger le fichier.

Content-Disposition: inline

Dans une soumission de formulaire multipart, chaque partie porte son propre champ Content-Disposition. Le paramètre name associe la partie au champ de formulaire correspondant, et filename indique le nom d’origine d’un fichier téléversé.

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

Dépannage

Les problèmes de téléchargement et d’affichage liés à Content-Disposition proviennent généralement de valeurs de directive incorrectes ou d’erreurs d’encodage du nom de fichier.

Le fichier est téléchargé sous un mauvais nom. Le navigateur utilise le paramètre filename comme nom d’enregistrement par défaut. Une valeur filename absente ou mal formée pousse le navigateur à se rabattre sur le chemin de l’URL ou sur un nom générique. Assurez-vous que la valeur est entourée de guillemets doubles : filename=“report.pdf”. Vérifiez l’en-tête avec curl -I https://example.re/file et contrôlez le paramètre filename dans la réponse.

Les caractères non ASCII dans les noms de fichiers sont altérés ou s’affichent en charabia. Le paramètre filename ne prend en charge que les caractères ASCII. Pour les noms comportant des lettres accentuées, des caractères CJK ou tout autre texte non ASCII, ajoutez le paramètre filename* en utilisant la syntaxe d’encodage : filename*=UTF-8”d%C3%B6cument.pdf. Incluez à la fois filename (repli ASCII) et filename* (version encodée) pour une compatibilité maximale entre navigateurs.

Le navigateur ignore attachment et affiche le contenu inline. Certains navigateurs passent outre attachment pour les types de contenu qu’ils affichent nativement, comme les PDF et les images. L’en-tête Content-Type influence ce comportement. Définir Content-Type: application/octet-stream en complément d’attachment force le téléchargement pour n’importe quel type de fichier. Les extensions de navigateur et les visionneuses intégrées (PDF.js) peuvent elles aussi passer outre la directive.

Un affichage inline se déclenche alors qu’un téléchargement est attendu. En l’absence d’en-tête Content-Disposition, la plupart des types de contenu sont traités comme inline par défaut. Le serveur doit envoyer explicitement attachment pour déclencher un téléchargement. Dans nginx, ajoutez add_header Content-Disposition “attachment”; au bloc location concerné. Dans Apache, utilisez Header set Content-Disposition “attachment” au sein d’une directive ou .

Priorité entre filename et filename*. Lorsque les deux paramètres sont présents, filename* est prioritaire dans tous les navigateurs modernes. Les clients plus anciens qui ne prennent pas en charge filename* se rabattent sur filename. Incluez toujours les deux paramètres. La valeur de filename* doit utiliser l’encodage pourcent pour les caractères spéciaux : filename*=UTF-8”na%C3%AFve.txt.

Méthodes utilitaires de réponse de téléchargement propres aux frameworks. La plupart des frameworks web fournissent des méthodes intégrées pour définir les en-têtes de téléchargement. Django utilise FileResponse avec le paramètre as_attachment. Express utilise res.download(). Flask utilise send_file() avec as_attachment=True. Rails utilise send_data ou send_file avec une option disposition. Ces méthodes gèrent l’encodage du nom de fichier et le formatage de l’en-tête, ce qui réduit le risque d’erreurs manuelles.