Class: DownloadItem

원격 소스에서 파일 다운로드를 제어한다.

프로세스: 메인
이 클래스는 'electron' 모듈에서 직접 내보내지 않는다. Electron API의 다른 메서드 반환값으로만 사용할 수 있다.

DownloadItem은 Electron에서 다운로드 항목을 나타내는 EventEmitter다. Session 클래스의 will-download 이벤트에서 사용되며, 사용자가 다운로드 항목을 제어할 수 있게 한다.

// 메인 프로세스에서
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.session.on('will-download', (event, item, webContents) => {
  // 저장 경로를 설정해 Electron이 저장 대화상자를 표시하지 않게 한다.
  item.setSavePath('/tmp/save.pdf')

  item.on('updated', (event, state) => {
    if (state === 'interrupted') {
      console.log('다운로드가 중단되었지만 재개할 수 있음')
    } else if (state === 'progressing') {
      if (item.isPaused()) {
        console.log('다운로드가 일시 중지됨')
      } else {
        console.log(`수신한 바이트: ${item.getReceivedBytes()}`)
      }
    }
  })
  item.once('done', (event, state) => {
    if (state === 'completed') {
      console.log('다운로드 성공')
    } else {
      console.log(`다운로드 실패: ${state}`)
    }
  })
})

인스턴스 이벤트

이벤트: 'updated'

반환값:

event Event
state string - progressing 또는 interrupted 상태일 수 있음

다운로드가 업데이트되었지만 완료되지 않은 경우 발생한다.

state는 다음 중 하나일 수 있다:

progressing - 다운로드가 진행 중임
interrupted - 다운로드가 중단되었으며 재개할 수 있음

이벤트: 'done'

반환값:

event Event
state string - completed, cancelled, interrupted 중 하나

다운로드가 종료 상태에 도달했을 때 발생한다. 이는 완료된 다운로드, 취소된 다운로드(downloadItem.cancel()를 통해), 그리고 재개할 수 없는 중단된 다운로드를 포함한다.

state는 다음 중 하나일 수 있다:

completed - 다운로드가 성공적으로 완료됨
cancelled - 다운로드가 취소됨
interrupted - 다운로드가 중단되었고 재개할 수 없음

인스턴스 메서드

downloadItem 객체는 다음과 같은 메서드를 제공한다:

`downloadItem.setSavePath(path)`

path string - 다운로드 항목의 저장 파일 경로를 설정한다.

이 API는 세션의 will-download 콜백 함수 내에서만 사용할 수 있다.
경로가 존재하지 않으면, Electron은 해당 디렉터리를 재귀적으로 생성하려고 시도한다.
사용자가 이 API를 통해 저장 경로를 설정하지 않으면, Electron은 원래의 절차에 따라 저장 경로를 결정한다. 일반적으로 이 경우 저장 대화상자가 표시된다.

downloadItem.getSavePath()는 다운로드 항목의 저장 경로를 문자열로 반환한다. 이 경로는 downloadItem.setSavePath(path)를 통해 설정한 경로이거나, 표시된 저장 대화상자에서 선택한 경로가 된다.

`downloadItem.setSaveDialogOptions(options)`

options SaveDialogOptions - 파일 저장 대화상자 옵션을 설정한다. 이 객체는 dialog.showSaveDialog()의 options 매개변수와 동일한 속성을 가진다.

이 API는 기본적으로 열리는 다운로드 항목에 대한 저장 대화상자의 커스텀 옵션을 설정할 수 있게 해준다. 이 API는 세션의 will-download 콜백 함수 내에서만 사용할 수 있다.

`downloadItem.getSaveDialogOptions()`

SaveDialogOptions 객체를 반환한다. 이 객체는 이전에 downloadItem.setSaveDialogOptions(options)를 통해 설정된 값을 담고 있다.

`downloadItem.pause()`

다운로드를 일시 중지한다.

downloadItem.isPaused()는 다운로드가 일시 중지된 상태인지 여부를 boolean 값으로 반환한다.

`downloadItem.resume()`

일시 중지된 다운로드를 다시 시작한다.

참고: 다운로드 재개 기능을 사용하려면, 다운로드 대상 서버가 범위 요청(range requests)을 지원하고 Last-Modified 및 ETag 헤더 값을 제공해야 한다. 이 조건이 충족되지 않으면, resume()은 이전에 받은 데이터를 무시하고 처음부터 다운로드를 다시 시작한다.

downloadItem.canResume()는 boolean 값을 반환한다. 이 값은 다운로드를 재개할 수 있는지 여부를 나타낸다.

`downloadItem.cancel()`

다운로드 작업을 취소한다.

`downloadItem.getURL()`

string 타입을 반환한다. 다운로드 항목의 원본 URL을 나타낸다.

downloadItem.getMimeType()는 파일의 MIME 타입을 문자열로 반환한다.

`downloadItem.hasUserGesture()`

boolean을 반환한다. 다운로드가 사용자 제스처로 시작되었는지 여부를 나타낸다.

`downloadItem.getFilename()`

string 타입을 반환한다. 다운로드 항목의 파일 이름을 나타낸다.

참고: 이 메서드가 반환하는 파일 이름이 항상 로컬 디스크에 저장된 실제 파일 이름과 일치하지는 않는다. 사용자가 다운로드 저장 대화상자에서 파일 이름을 변경할 경우, 저장된 파일의 실제 이름은 다를 수 있다.

`downloadItem.getCurrentBytesPerSecond()`

Integer 타입의 값을 반환한다. 이 값은 현재 다운로드 속도를 초당 바이트 단위로 나타낸다.

`downloadItem.getTotalBytes()`

Integer를 반환한다. 다운로드 항목의 전체 크기를 바이트 단위로 나타낸다.

크기를 알 수 없는 경우 0을 반환한다.

downloadItem.getReceivedBytes()는 다운로드 항목에서 현재까지 받은 바이트 수를 정수 형태로 반환한다.

`downloadItem.getPercentComplete()`

Integer 타입의 값을 반환한다. 다운로드 진행률을 백분율로 나타낸다.

`downloadItem.getContentDisposition()`

string 타입을 반환한다. 이 값은 응답 헤더의 Content-Disposition 필드에서 가져온다.

`downloadItem.getState()`

string 타입의 현재 상태를 반환한다. 가능한 값은 progressing, completed, cancelled, interrupted 중 하나다.

참고: 아래 메서드들은 세션이 재시작되었을 때 cancelled 상태의 항목을 재개하는 데 유용하다.

downloadItem.getURLChain() 메서드는 아이템의 전체 URL 체인을 반환한다. 여기에는 리다이렉트가 포함된 모든 URL이 담겨 있다. 반환값은 string[] 타입이다.

`downloadItem.getLastModifiedTime()`

string 타입의 값을 반환한다. 이 값은 Last-Modified 헤더의 값을 나타낸다.

`downloadItem.getETag()`

string 타입의 ETag 헤더 값을 반환한다.

`downloadItem.getStartTime()`

Double 타입의 값을 반환한다. 다운로드가 시작된 시점을 유닉스 시간(UNIX epoch) 기준으로 초 단위로 나타낸다.

`downloadItem.getEndTime()`

Double 타입의 값을 반환한다. 이 값은 UNIX epoch(1970년 1월 1일 00:00:00 UTC) 이후로 다운로드가 완료된 시점까지의 시간을 초 단위로 나타낸다.

인스턴스 속성

`downloadItem.savePath`

다운로드 항목의 저장 파일 경로를 결정하는 string 타입 속성이다.

이 속성은 세션의 will-download 콜백 함수 내에서만 사용할 수 있다. 사용자가 이 속성을 통해 저장 경로를 설정하지 않으면, Electron은 원래의 절차를 따라 저장 경로를 결정한다. 일반적으로 이 경우 저장 대화 상자가 나타난다.