La fonction download() de l'API downloads télécharge le fichier, compte tenu de son URL et d'autres préférences optionnelles.

  • Si l'url spécifiée utilise le protocole HTTP ou HTTPS, la requête inclura tous les cookies actuellement définis pour son nom d'hôte.
  • Si à la fois le  nom de fichier et saveAs sont spécifiés, la boîte de dialogue Enregistrer sous s'affiche, pré-remplie avec le nom du fichier spécifié.

C'est une fonction asynchrone qui renvoie une Promise.

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 :
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
Un tableau d'objets représentant des en-têtes HTTP supplémentaires à envoyer avec la requête si l'URL utilise le protocole HTTP[s]. Chaque en-tête est représenté comme un objet dictionnaire contenant le name des clés et soit value ou binaryValue, restreint à ceux autorisés par XMLHttpRequest.
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).

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.

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é du navigateur

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxOperaFirefox pour Android
Support simpleChrome Support complet OuiEdge Aucun support NonFirefox Support complet 47Opera Support complet OuiFirefox Android Support complet 48
bodyChrome Support complet OuiEdge Aucun support NonFirefox Support complet 52Opera Support complet OuiFirefox Android Support complet 52
conflictActionChrome Support complet OuiEdge Aucun support NonFirefox Support complet 47Opera Support complet OuiFirefox Android Support complet 48
filenameChrome Support complet OuiEdge Aucun support NonFirefox Support complet 47Opera Support complet OuiFirefox Android Support complet 48
headersChrome Support complet OuiEdge Aucun support NonFirefox Support complet 47Opera Support complet OuiFirefox Android Support complet 48
incognitoChrome Aucun support NonEdge Aucun support NonFirefox Support complet 57Opera Aucun support NonFirefox Android Support complet 57
methodChrome Support complet OuiEdge Aucun support NonFirefox Support complet 47
Notes
Support complet 47
Notes
Notes POST is supported from version 52.
Opera Support complet OuiFirefox Android Support complet 48
Notes
Support complet 48
Notes
Notes POST is supported from version 52.
saveAsChrome Support complet OuiEdge Aucun support NonFirefox Support complet 52
Notes
Support complet 52
Notes
Notes Before version 58, if this option was omitted, Firefox would never show the file chooser, regardless of the value of the browser's preference.
Opera Support complet OuiFirefox Android Support complet 52
Notes
Support complet 52
Notes
Notes Before version 58, if this option was omitted, Firefox would never show the file chooser, regardless of the value of the browser's preference.

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Voir les notes d'implémentation.
Voir les notes d'implémentation.

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

Remerciements :

Cette API est basée sur l'API Chromium chrome.downloads.

Étiquettes et contributeurs liés au document

Contributeurs à cette page : hellosct1
Dernière mise à jour par : hellosct1,