檔案下載是我們開發中比較常見的業務需求，比如：匯出 excel。 web 應用檔案下載存在一些侷限性，通常是讓後端將響應的頭資訊改成 `Content-Disposition: attachment; filename=xxx.pdf`，觸發瀏覽器的下載行為。 在 electron 中的下載行為，都會觸發 session 的 [will-download](https://www.electronjs.org/docs/api/session#instance-events) 事件。在該事件裡面可以獲取到 [downloadItem](https://www.electronjs.org/docs/api/download-item) 物件，通過 [downloadItem](https://www.electronjs.org/docs/api/download-item) 物件實現一個簡單的檔案下載管理器：  ## **1. 如何觸發下載** 由於 electron 是基於 chromium 實現的，通過呼叫 webContents 的 [downloadURL](https://www.electronjs.org/docs/api/web-contents#contentsdownloadurlurl) 方法，相當於呼叫了 chromium 底層實現的下載，會忽略響應頭資訊，觸發 [will-download](https://www.electronjs.org/docs/api/session#instance-events) 事件。 ```javascript // 觸發下載 win.webContents.downloadURL(url) // 監聽 will-download session.defaultSession.on('will-download', (event, item, webContents) => {}) ``` ## **2. 下載流程**  ## **3. 功能設計** 實現一個簡單的檔案下載管理器包含以下功能： - 設定儲存路徑 - 暫停/恢復和取消 - 下載進度 - 下載速度 - 下載完成 - 開啟檔案和開啟檔案所在位置 - 檔案圖示 - 下載記錄 ### **3.1 設定儲存路徑** 如果沒有設定儲存路徑，electron 會自動彈出系統的儲存對話方塊。不想使用系統的儲存對話方塊，可以使用 [setSavePath](https://www.electronjs.org/docs/api/download-item#downloaditemsetsavepathpath) 方法，當有重名檔案時，會直接覆蓋下載。 ```javascript item.setSavePath(path) ``` 為了更好的使用者體驗，可以讓使用者自己選擇儲存位置操作。當點選位置輸入框時，渲染程序通過 ipc 與主程序通訊，開啟系統檔案選擇對話方塊。  主程序實現程式碼： ```typescript /** * 開啟檔案選擇框 * @param oldPath - 上一次開啟的路徑 */ const openFileDialog = async (oldPath: string = app.getPath('downloads')) => { if (!win) return oldPath const { canceled, filePaths } = await dialog.showOpenDialog(win, { title: '選擇儲存位置', properties: ['openDirectory', 'createDirectory'], defaultPath: oldPath, }) return !canceled ? filePaths[0] : oldPath } ipcMain.handle('openFileDialog', (event, oldPath?: string) => openFileDialog(oldPath)) ``` 渲染程序程式碼： ```javascript const path = await ipcRenderer.invoke('openFileDialog', 'PATH') ``` ### **3.2 暫停/恢復和取消** 拿到 [downloadItem](https://www.electronjs.org/docs/api/download-item) 後，暫停、恢復和取消分別呼叫 `pause`、`resume` 和 `cancel` 方法。當我們要刪除列表中正在下載的項，需要先呼叫 cancel 方法取消下載。 ### **3.3 下載進度** 在 DownloadItem 中監聽 updated 事件，可以實時獲取到已下載的位元組資料，來計算下載進度和每秒下載的速度。 ```javascript // 計算下載進度 const progress = item.getReceivedBytes() / item.getTotalBytes() ```  在下載的時候，想在 Mac 系統的程式塢和 Windows 系統的工作列展示下載資訊，比如： - 下載數：通過 app 的 [badgeCount](https://www.electronjs.org/docs/api/app#appbadgecount-linux-macos) 屬性設定，當為 0 時，不會顯示。也可以通過 dock 的 [setBadge](https://www.electronjs.org/docs/api/app#appsetbadgecountcount-linux-macos) 方法設定，該方法支援的是字串，如果不要顯示，需要設定為 ''。 - 下載進度：通過視窗的 [setProgressBar](https://www.electronjs.org/docs/api/browser-window#winsetprogressbarprogress-options) 方法設定。 > 由於 Mac 和 Windows 系統差異，下載數僅在 Mac 系統中生效。加上 process.platform === 'darwin' 條件，避免在非 Mac、Linux 系統下出現異常錯誤。 下載進度（Windows 系統工作列、Mac 系統程式塢）顯示效果：   ```javascript // mac 程式塢顯示下載數： // 方式一 app.badgeCount = 1 // 方式二 app.dock.setBadge('1') // mac 程式塢、windows 工作列顯示進度 win.setProgressBar(progress) ``` ### **3.4 下載速度** 由於 [downloadItem](https://www.electronjs.org/docs/api/download-item) 沒有直接為我們提供方法或屬性獲取下載速度，需要自己實現。 > 思路：在 updated 事件裡通過 getReceivedBytes 方法拿到本次下載的位元組資料減去上一次下載的位元組資料。 ```javascript // 記錄上一次下載的位元組資料 let prevReceivedBytes = 0 item.on('updated', (e, state) => { const receivedBytes = item.getReceivedBytes() // 計算每秒下載的速度 downloadItem.speed = receivedBytes - prevReceivedBytes prevReceivedBytes = receivedBytes }) ``` > 需要注意的是，updated 事件執行的時間約 500ms 一次。  ### **3.5 下載完成** 當一個檔案下載完成、中斷或者被取消，需要通知渲染程序修改狀態，通過監聽 [downloadItem](https://www.electronjs.org/docs/api/download-item) 的 done 事件。 ```javascript item.on('done', (e, state) => { downloadItem.state = state downloadItem.receivedBytes = item.getReceivedBytes() downloadItem.lastModifiedTime = item.getLastModifiedTime() // 通知渲染程序，更新下載狀態 webContents.send('downloadItemDone', downloadItem) }) ``` ### **3.6 開啟檔案和開啟檔案所在位置** 使用 electron 的 shell 模組來實現開啟檔案（openPath）和開啟檔案所在位置（showItemInFolder）。 > 由於 openPath 方法支援返回值 `Promise`，當不支援開啟的檔案，系統會有相應的提示，而 showItemInFolder 方法返回值是 `void`。如果需要更好的使用者體驗，可使用 nodejs 的 fs 模組，先檢查檔案是否存在。 ```typescript import fs from 'fs' // 開啟檔案 const openFile = (path: string): boolean => { if (!fs.existsSync(path)) return false shell.openPath(path) return true } // 開啟檔案所在位置 const openFileInFolder = (path: string): boolean => { if (!fs.existsSync(path)) return false shell.showItemInFolder(path) return true } ``` ### **3.7 檔案圖示** 很方便的是使用 app 模組的 [getFileIcon](https://www.electronjs.org/docs/api/app#appgetfileiconpath-options) 方法來獲取系統關聯的檔案圖示，返回的是 `Promise` 型別，我們可以用 toDataURL 方法轉換成 base64，不需要我們去處理不同檔案型別顯示不同的圖示。 ```typescript const getFileIcon = async (path: string) => { const iconDefault = './icon_default.png' if (!path) Promise.resolve(iconDefault) const icon = await app.getFileIcon(path, { size: 'normal' }) return icon.toDataURL() } ``` ### **3.8 下載記錄** 隨著下載的歷史資料越來越多，使用 [electron-store](https://github.com/sindresorhus/electron-store) 將下載記錄儲存在本地。 ## **其他** 專案的地址： [https://github.com/tal-tech/electron-playground](https://github.com/tal-tech/electron-playground) 如果想看更完整的文件，請參考下面文件 [Electron-Playground 官方文件](https://www.yuque.com/ezg6c4/