Класс: DownloadItem

Управление загрузками файлов из удалённых источников.

Процесс: Основной
Этот класс не экспортируется из модуля 'electron'. Он доступен только в качестве значения возврата других методов в API Electron.

DownloadItem — это EventEmitter, представляющий элемент загрузки в Electron. Он используется в событии will-download класса Session и позволяет пользователю управлять элементом загрузки.

// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
  // Set the save path, making Electron not to prompt a save dialog.
  item.setSavePath('/tmp/save.pdf')

  item.on('updated', (event, state) => {
    if (state === 'interrupted') {
      console.log('Download is interrupted but can be resumed')
    } else if (state === 'progressing') {
      if (item.isPaused()) {
        console.log('Download is paused')
      } else {
        console.log(`Received bytes: ${item.getReceivedBytes()}`)
      }
    }
  })
  item.once('done', (event, state) => {
    if (state === 'completed') {
      console.log('Download successfully')
    } else {
      console.log(`Download failed: ${state}`)
    }
  })
})

События экземпляра

Событие: 'updated'

Возвращает:

event Событие
state строка - Может быть progressing или interrupted.

Вызывается, когда загрузка обновлена, но не завершена.

state может быть одним из следующих:

progressing - Загрузка в процессе.
interrupted - Загрузка прервана и может быть возобновлена.

Событие: 'done'

Возвращает:

event Событие
state строка - Может быть completed, cancelled или interrupted.

Вызывается, когда загрузка находится в терминальном состоянии. Это включает завершенную загрузку, отменённую загрузку (через downloadItem.cancel()) и прерванную загрузку, которую невозможно возобновить.

state может быть одним из следующих:

completed - Загрузка успешно завершена.
cancelled - Загрузка отменена.
interrupted - Загрузка прервана и не может быть возобновлена.

Методы экземпляра

Объект downloadItem имеет следующие методы:

`downloadItem.setSavePath(path)`

path строка - Установка пути сохранения файла для элемента загрузки.

API доступно только в функции обратного вызова will-download сеанса. Если path не существует, Electron попытается создать каталог рекурсивно. Если пользователь не установит путь сохранения через API, Electron воспользуется исходным способом определения пути сохранения; это обычно приводит к открытию диалога сохранения.

`downloadItem.getSavePath()`

Возвращает string - Путь сохранения элемента загрузки. Это будет либо путь, установленный через downloadItem.setSavePath(path), либо путь, выбранный из показанного диалога сохранения.

`downloadItem.setSaveDialogOptions(options)`

options SaveDialogOptions - Установка параметров диалога сохранения файла. Этот объект имеет те же свойства, что и параметр options dialog.showSaveDialog().

Этот API позволяет пользователю устанавливать пользовательские параметры для диалога сохранения, который открывается по умолчанию для элемента загрузки. API доступен только в функции обратного вызова will-download сеанса.

`downloadItem.getSaveDialogOptions()`

Возвращает SaveDialogOptions - Возвращает объект, ранее установленный с помощью downloadItem.setSaveDialogOptions(options).

`downloadItem.pause()`

Приостанавливает загрузку.

`downloadItem.isPaused()`

Возвращает boolean - Приостановлена ли загрузка.

`downloadItem.resume()`

Возобновляет прерванную загрузку.

Примечание: Для включения возобновляемых загрузок сервер, с которого осуществляется загрузка, должен поддерживать запросы диапазона и предоставлять значения заголовков Last-Modified и ETag. В противном случае resume() отклонит ранее полученные байты и перезапустит загрузку с начала.

`downloadItem.canResume()`

Возвращает boolean - Можно ли возобновить загрузку.

`downloadItem.cancel()`

Отменяет операцию загрузки.

`downloadItem.getURL()`

Возвращает string - Исходный URL, откуда загружается элемент.

`downloadItem.getMimeType()`

Возвращает string - Тип MIME файла.

`downloadItem.hasUserGesture()`

Возвращает boolean - Является ли загрузка результатом пользовательского действия.

`downloadItem.getFilename()`

Возвращает string - Имя файла элемента загрузки.

Примечание: Имя файла не всегда совпадает с фактическим именем, сохранённым на локальном диске. Если пользователь изменяет имя файла в запрошенном диалоге сохранения, фактическое имя сохранённого файла будет другим.

`downloadItem.getTotalBytes()`

Возвращает Integer - Общий размер элемента загрузки в байтах.

Если размер неизвестен, возвращает 0.

`downloadItem.getReceivedBytes()`

Возвращает Integer - Полученные байты элемента загрузки.

`downloadItem.getContentDisposition()`

Возвращает string - Поле Content-Disposition из заголовка ответа.

`downloadItem.getState()`

Возвращает string - Текущее состояние. Может быть progressing, completed, cancelled или interrupted.

Примечание: Следующие методы полезны для возобновления элемента cancelled загрузки при перезапуске сеанса.

`downloadItem.getURLChain()`

Возвращает string[] - Полная цепочка URL элемента, включая все перенаправления.

`downloadItem.getLastModifiedTime()`

Возвращает string - Значение заголовка Last-Modified.

`downloadItem.getETag()`

Возвращает string - Значение заголовка ETag.

`downloadItem.getStartTime()`

Возвращает Double - Количество секунд с эпохи Unix, когда началась загрузка.

Свойства экземпляра

`downloadItem.savePath`

Свойство string, определяющее путь сохранения файла для элемента загрузки.

Свойство доступно только в функции обратного вызова will-download сеанса. Если пользователь не установит путь сохранения через свойство, Electron воспользуется исходным способом определения пути сохранения; это обычно приводит к открытию диалога сохранения.