Classe : DownloadItem

Gère les téléchargements de fichiers depuis des sources distantes.

Processus : Principal
Cette classe n'est pas exportée depuis le module 'electron'. Elle n'est disponible qu'en tant que valeur de retour des autres méthodes dans l'API Electron.

DownloadItem est un EventEmitter qui représente un élément de téléchargement dans Electron. Il est utilisé dans l'événement will-download de la classe Session, et permet aux utilisateurs de gérer les fichiers en cours de téléchargement.

// Dans le processus main.
const { BrowserWindow } = require('electron')
let win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
  // Définit le chemin d'enregistrement faisant qu'Electron n'affichera pas de boite de dialogue.
  item.setSavePath('/tmp/save.pdf')

  item.on('updated', (event, state) => {
    if (state === 'interrupted') {
      console.log('Le téléchargement est interrompu mais peut être redémarrer')
    } else if (state === 'progressing') {
      if (item.isPaused()) {
        console.log('Le téléchargement est en pause')
      } else {
        console.log(`Received bytes: ${item.getReceivedBytes()}`)
      }
    }
  })
  item.once('done', (event, state) => {
    if (state === 'completed') {
      console.log('Téléchargement réussi')
    } else {
      console.log(`Téléchargement échoué : ${state}`)
    }
  })
})

Événements d’instance

Événement 'updated'

Retourne :

event Event
state string - Peut être progressing ou interrupted.

Émis lorsque le téléchargement a été mis à jour et n'est pas fini.

Le state peut être un de ces cas :

progressing - Le téléchargement est en cours.
interrupted - Le téléchargement a été interrompu et peut être repris.

Événement 'done'

Retourne :

event Event
state string - Peut prendre les valeurs completed, cancelled ou interrupted.

Émis lorsque le téléchargement est dans un état de finalisation. Cela inclut téléchargement terminé, téléchargement annulé (via downloadItem.cancel()), et téléchargement interrompu ne pouvant être repris.

Le state peut être un de ces cas :

completed - Le téléchargement s'est terminé avec succès.
cancelled - Le téléchargement a été annulé.
interrupted - Le téléchargement a été interrompu et ne peux pas être repris.

Méthodes d’instance

L'objet downloadItem dispose des méthodes suivantes :

`downloadItem.setSavePath(path)`

path string - Définit le chemin pour l'enregistrement de l'élément téléchargé.

Cette API est seulement disponible dans la fonction de callback de will-download de la session. Si path n'existe pas, Electron essaiera de reproduire le répertoire récursivement. Si l'utilisateur ne définit pas le chemin de sauvegarde via l'API, Electron utilisera la routine d'origine pour déterminer le chemin de sauvegarde ; cela produit généralement une boîte de dialogue d'enregistrement.

`downloadItem.getSavePath()`

Retourne string - Chemin d'enregistrement de l'élément téléchargé. Ce sera soit le chemin défini via downloadItem.setSavePath(path) ou le chemin sélectionné dans la boîte de dialogue d'enregistrement affichée.

`downloadItem.setSaveDialogOptions(options)`

options SaveDialogOptions - Définit les options de la boîte de dialogue d'enregistrement de fichier. Cet objet a les mêmes propriétés que le paramètre options de dialog.showSaveDialog().

Cette API permet à l'utilisateur de définir des options personnalisées pour la boîte de dialogue d'enregistrement s'ouvrant par défaut pour l'élément de téléchargement. Cette API est seulement disponible dans la fonction de callback de will-download de la session.

`downloadItem.getSaveDialogOptions()`

Retourne SaveDialogOptions - Retourne l'objet précédemment défini par downloadItem.setSaveDialogOptions(options).

`downloadItem.pause()`

Met en pause le téléchargement.

`downloadItem.isPaused()`

Retourne boolean - Indique si le téléchargement est en pause.

`downloadItem.resume()`

Reprend le téléchargement qui a été mis en pause.

Remarque : Pour permettre la reprise des téléchargements, le serveur à partir duquel vous téléchargez doit supporter les requêtes partielles (range requests) et doit fournir les en-têtes Last-Modified et ETag. Sinon resume() rejettera les octets reçus précédemment et redémarrera le téléchargement à partir du début.

`downloadItem.canResume()`

Retourne boolean - Indique si le téléchargement peut être repris.

`downloadItem.cancel()`

Annule le téléchargement.

`downloadItem.getURL()`

Retourne string - URL d'origine d'où l'élément est téléchargé.

`downloadItem.getMimeType()`

Retourne string - Type mime des fichiers.

`downloadItem.hasUserGesture()`

Retourne boolean - Si le téléchargement à des gestures.

`downloadItem.getFilename()`

Retourne string - Nom du fichier du téléchargement.

Remarque : Le nom du fichier n'est pas toujours le même que celui actuellement enregistré sur le disque local. Si l'utilisateur modifie le nom du fichier dans la boîte de dialogue d'enregistrement, alors le nom actuel et le nom du fichier enregistré seront différent.

`downloadItem.getTotalBytes()`

Retourne Integer - La taille totale en octets du téléchargement.

Retourne 0 si la taille est inconnue.

`downloadItem.getReceivedBytes()`

Retourne Integer - Le nombre d'octets reçu du téléchargement.

`downloadItem.getContentDisposition()`

Retourne string - Champ Content-Disposition venant de l'en-tête de la réponse.

`downloadItem.getState()`

Retourne string - Etat actuel. Peut être progressing, completed, cancelled ou interrupted.

Remarque : Les méthodes suivantes sont particulièrement utiles pour relancer un téléchargement cancelled au redémarrage de la session.

`downloadItem.getURLChain()`

Retourne string[] - Chaîne complète d'URL de l'élément incluant toutes les redirections.

`downloadItem.getLastModifiedTime()`

Retourne string - Dernière valeur d'en-tête modifiée.

`downloadItem.getETag()`

Retourne string - valeur de l'en-tête ETag.

`downloadItem.getStartTime()`

Retourne Double - Le nombre de secondes depuis l'époch UNIX du démarrage du téléchargement.

Propriétés d'instance

`chemin d'accès à la sauvegarde`

Propriété de type string qui détermine le chemin d'enregistrement du fichier de l'élément téléchargé.

La propriété n'est disponible que dans la fonction de callback de will-download de la session. Si l’utilisateur ne définisse pas le chemin d’enregistrement via la propriété, Electron utilisera la routine d’origine pour déterminer le chemin d’enregistrement ; cela déclenche généralement une boîte de dialogue d’enregistrement.