downloads.download()

Syntaxe

var downloading = browser.downloads.download(
  options, // object
);

Paramètres

options

Un object spécifiant le fichier que vous souhaitez télécharger et toutes les autres préférences que vous souhaitez définir concernant le téléchargement. Il peut contenir les propriétés suivantes :

allowHttpErrorsFacultatif

Un tag booléen qui permet de poursuivre les téléchargements même s'ils rencontrent des erreurs HTTP. L'utilisation de ce drapeau, par exemple, permet le téléchargement des pages d'erreur du serveur. La valeur par défaut est false. Lorsqu'il est défini à :

• false, le téléchargement est annulé lorsqu'il rencontre une erreur HTTP.
• true, le téléchargement se poursuit lorsqu'une erreur HTTP est rencontrée et que l'erreur du serveur HTTP n'est pas signalée. Toutefois, si le téléchargement échoue en raison d'une erreur liée au fichier, au réseau, à l'utilisateur ou autre, cette erreur est signalée.

bodyFacultatif

Un string représentant le corps du message de la requête.

conflictActionFacultatif

Une chaîne représentant l'action que vous voulez effectuer s'il y a un conflit de nom de fichier, tel que défini dans le downloads.FilenameConflictAction type (par défaut "uniquify" quand il n'est pas spécifié).

filenameFacultatif

Un string eprésentant un chemin d'accès au fichier par rapport au répertoire de téléchargement par défaut, qui indique l'emplacement où vous souhaitez enregistrer le fichier et le nom de fichier que vous souhaitez utiliser. Les chemins absolus, les chemins vides et les chemins contenant des références arrières (../) provoqueront une erreur. Si elle est omise, cette valeur sera par défaut le nom de fichier déjà donné au fichier de téléchargement, et un emplacement immédiatement dans le répertoire de téléchargement.

headersFacultatif

Si l'URL utilise les protocoles HTTP ou HTTPS, un array d'objects représentant des en-têtes HTTP supplémentaires à envoyer avec la requête. Chaque en-tête est représenté sous la forme d'un objet dictionnaire contenant le name des clés et soit la value, soit la valeur binaryValue. Les en-têtes interdits par XMLHttpRequest et fetch ne peuvent pas être spécifiés, cependant, Firefox 70 et les versions ultérieures permettent d'utiliser l'en-tête Referer. Tenter d'utiliser un en-tête interdit provoque une erreur.

incognitoFacultatif

Un boolean: s'il est présent et défini sur true, associez ce téléchargement à une session de navigation privée. Cela signifie qu'il n'apparaîtra dans le gestionnaire de téléchargement que pour les fenêtres privées actuellement ouvertes.

methodFacultatif

Un string représentant la méthode HTTP à utiliser si l'url utilise le protocole HTTP[S]. Cela peut être "GET" ou "POST".

saveAsFacultatif

Un boolean qui spécifie s'il faut fournir une boîte de dialogue de sélection de fichier pour permettre à l'utilisateur de sélectionner un nom de fichier (true), ou non (false).

Si cette option est omise, le navigateur affichera le sélecteur de fichier ou non en fonction de la préférence générale de l'utilisateur pour ce comportement (dans Firefox cette préférence est intitulée "Toujours vous demander où enregistrer les fichiers" dans about:preferences, ou browser.download.useDownloadDir dans about:config).

Note : Firefox pour Android provoque une erreur si saveAs est à true. Le paramètre est ignoré lorsque saveAs est false ou non inclus.

url

Un string représentant l'URL à télécharger.

Valeur retournée

Une Promise. Si le téléchargement a démarré avec succès, la promesse sera remplie avec l'id de la nouvelle downloads.DownloadItem. Sinon, la promesse sera rejetée avec un message d'erreur venant de downloads.InterruptReason.

Si vous utilisez URL.createObjectURL() pour télécharger des données créées en JavaScript et que vous voulez révoquer l'URL de l'objet (avec revokeObjectURL) plus tard (comme il est fortement recommandé), vous devez le faire après le téléchargement. Pour ce faire, écoutez l'événement downloads.onChanged.

Compatibilité des navigateurs

Examples

Le fragment suivant tente de télécharger un exemple de fichier, en spécifiant également un nom de fichier et un emplacement pour l'enregistrer, ainsi que l'option uniquify conflictAction.

function onStartedDownload(id) {
  console.log(`Started downloading: ${id}`);
}

function onFailed(error) {
  console.log(`Download failed: ${error}`);
}

var downloadUrl = "https://example.org/image.png";

var downloading = browser.downloads.download({
  url: downloadUrl,
  filename: "my-image-again.png",
  conflictAction: "uniquify",
});

downloading.then(onStartedDownload, onFailed);