Aller au contenu principal

Classe : DownloadItem

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'. Il 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 - Set the save file path of the download item.

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

Returns string - The save path of the download item. 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()

Returns boolean - Whether the download is paused.

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

Returns boolean - Whether the download can resume.

downloadItem.cancel()

Annule le téléchargement.

downloadItem.getURL()

Returns string - The origin URL where the item is downloaded from.

downloadItem.getMimeType()

Returns string - The files mime type.

downloadItem.hasUserGesture()

Returns boolean - Whether the download has user gesture.

downloadItem.getFilename()

Returns string - The file name of the download item.

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

Returns string - The Content-Disposition field from the response header.

downloadItem.getState()

Returns string - The current state. 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()

Returns string[] - The complete URL chain of the item including any redirects.

downloadItem.getLastModifiedTime()

Returns string - Last-Modified header value.

downloadItem.getETag()

Returns string - ETag header value.

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

A string property that determines the save file path of the download item.

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.