Skip to main content

Classe : DownloadItem

Classe : DownloadItem

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

Process: Main
This class is not exported from the 'electron' module. It is only available as a return value of other methods in the Electron API.

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 être completed, cancelled ou interrupted.

Émis lorsque le téléchargement est dans un état de terminal. 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 d'accès pour le téléchargement.

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 - le chemin de l'élément de téléchargement. 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 - 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 - Si le téléchargement peut être repris.

downloadItem.cancel()

Annule le téléchargement.

downloadItem.getURL()

Retourne String - L'URL d'origine à partir de laquelle l'élément est téléchargé.

downloadItem.getMimeType()

Retourne String - Le type mime du fichier.

downloadItem.hasUserGesture()

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

downloadItem.getFilename()

Retourne String - le 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 - Le champ Content-Disposition de l'en-tête de la réponse.

downloadItem.getState()

Retourne String - L'état 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[] - La chaîne d'URL complète de l'élément incluant toutes les redirections.

downloadItem.getLastModifiedTime()

Retourne String - La valeur de l'en-tête Last-Modified.

downloadItem.getETag()

Retourne String - La 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

Une propriété String déterminant le chemin du fichier enregistré pour 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.