{"id":13459075,"url":"https://github.com/sindresorhus/electron-dl","last_synced_at":"2025-05-14T03:06:43.076Z","repository":{"id":42370793,"uuid":"46404395","full_name":"sindresorhus/electron-dl","owner":"sindresorhus","description":"Simplified file downloads for your Electron app","archived":false,"fork":false,"pushed_at":"2024-05-01T13:49:16.000Z","size":5631,"stargazers_count":1188,"open_issues_count":55,"forks_count":140,"subscribers_count":18,"default_branch":"main","last_synced_at":"2025-05-06T07:31:48.815Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sindresorhus.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"sindresorhus","open_collective":"sindresorhus","buy_me_a_coffee":"sindresorhus","custom":"https://sindresorhus.com/donate"}},"created_at":"2015-11-18T08:07:49.000Z","updated_at":"2025-04-20T13:47:49.000Z","dependencies_parsed_at":"2024-11-06T04:02:34.231Z","dependency_job_id":"89fa3cc8-9934-4511-b3ec-becbeb021b97","html_url":"https://github.com/sindresorhus/electron-dl","commit_stats":{"total_commits":107,"total_committers":33,"mean_commits":3.242424242424242,"dds":"0.36448598130841126","last_synced_commit":"972398c4eb47cdc58379e4ef662f0a92e94e6718"},"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felectron-dl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felectron-dl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felectron-dl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sindresorhus%2Felectron-dl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sindresorhus","download_url":"https://codeload.github.com/sindresorhus/electron-dl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254059500,"owners_count":22007768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T09:01:02.889Z","updated_at":"2025-05-14T03:06:43.042Z","avatar_url":"https://github.com/sindresorhus.png","language":"JavaScript","funding_links":["https://github.com/sponsors/sindresorhus","https://opencollective.com/sindresorhus","https://buymeacoffee.com/sindresorhus","https://sindresorhus.com/donate"],"categories":["JavaScript","Library","Tools","三、开发者必备工具"],"sub_categories":["Auto Updater/Release Server","For Electron","4. 网络与文件处理"],"readme":"# electron-dl\n\n\u003e Simplified file downloads for your [Electron](https://electronjs.org) app\n\n## Why?\n\n- One function call instead of having to manually implement a lot of [boilerplate](index.js).\n- Saves the file to the users Downloads directory instead of prompting.\n- Bounces the Downloads directory in the dock when done. *(macOS)*\n- Handles multiple downloads.\n- Shows badge count *(macOS \u0026 Linux only)* and download progress. Example on macOS:\n\n\u003cimg src=\"screenshot.png\" width=\"82\"\u003e\n\n## Install\n\n```sh\nnpm install electron-dl\n```\n\n*Requires Electron 30 or later.*\n\n## Usage\n\n### Register it for all windows\n\nThis is probably what you want for your app.\n\n```js\nimport {app, BrowserWindow} from 'electron';\nimport electronDl from 'electron-dl';\n\nelectronDl();\n\nlet mainWindow;\n(async () =\u003e {\n\tawait app.whenReady();\n\tmainWindow = new BrowserWindow();\n})();\n```\n\n### Use it manually\n\nThis can be useful if you need download functionality in a reusable module.\n\n```js\nimport {BrowserWindow, ipcMain} from 'electron';\nimport {download, CancelError} from 'electron-dl';\n\nipcMain.on('download-button', async (event, {url}) =\u003e {\n\tconst win = BrowserWindow.getFocusedWindow();\n\ttry {\n\t\tconsole.log(await download(win, url));\n\t} catch (error) {\n\t\tif (error instanceof CancelError) {\n\t\t\tconsole.info('item.cancel() was called');\n\t\t} else {\n\t\t\tconsole.error(error);\n\t\t}\n\t}\n});\n```\n\n## API\n\nIt can only be used in the [main](https://electronjs.org/docs/glossary/#main-process) process.\n\n### electronDl(options?)\n\n### download(window, url, options?): Promise\u003c[DownloadItem](https://electronjs.org/docs/api/download-item)\u003e\n\n### window\n\nType: `BrowserWindow | WebContentsView`\n\nThe window to register the behavior on. Alternatively, a `WebContentsView` can be passed.\n\n### url\n\nType: `string`\n\nThe URL to download.\n\n### options\n\nType: `object`\n\n#### saveAs\n\nType: `boolean`\\\nDefault: `false`\n\nShow a `Save As…` dialog instead of downloading immediately.\n\nNote: Only use this option when strictly necessary. Downloading directly without a prompt is a much better user experience.\n\n#### directory\n\nType: `string`\\\nDefault: [User's downloads directory](https://electronjs.org/docs/api/app/#appgetpathname)\n\nThe directory to save the file in.\n\nMust be an absolute path.\n\n#### filename\n\nType: `string`\\\nDefault: [`downloadItem.getFilename()`](https://electronjs.org/docs/api/download-item/#downloaditemgetfilename)\n\nName of the saved file.\n\nThis option only makes sense for `electronDl.download()`.\n\n#### errorTitle\n\nType: `string`\\\nDefault: `'Download Error'`\n\nTitle of the error dialog. Can be customized for localization.\n\nNote: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.\n\n#### errorMessage\n\nType: `string`\\\nDefault: `'The download of {filename} was interrupted'`\n\nMessage of the error dialog. `{filename}` is replaced with the name of the actual file. Can be customized for localization.\n\nNote: Error dialog will not be shown in `electronDl.download()`. Please handle error manually.\n\n#### onStarted\n\nType: `Function`\n\nOptional callback that receives the [download item](https://electronjs.org/docs/api/download-item).\nYou can use this for advanced handling such as canceling the item like `item.cancel()` which will throw `electronDl.CancelError` from the `electronDl.download()` method.\n\n#### onProgress\n\nType: `Function`\n\nOptional callback that receives an object containing information about the progress of the current download item.\n\n```js\n{\n\tpercent: 0.1,\n\ttransferredBytes: 100,\n\ttotalBytes: 1000\n}\n```\n\n#### onTotalProgress\n\nType: `Function`\n\nOptional callback that receives an object containing information about the combined progress of all download items done within any registered window.\n\nEach time a new download is started, the next callback will include it. The progress percentage could therefore become smaller again.\nThis callback provides the same data that is used for the progress bar on the app icon.\n\n```js\n{\n\tpercent: 0.1,\n\ttransferredBytes: 100,\n\ttotalBytes: 1000\n}\n```\n\n#### onCancel\n\nType: `Function`\n\nOptional callback that receives the [download item](https://electronjs.org/docs/api/download-item) for which the download has been cancelled.\n\n#### onCompleted\n\nType: `Function`\n\nOptional callback that receives an object with information about an item that has been completed. It is called for each completed item.\n\n```js\n{\n\tfilename: 'file.zip',\n\tpath: '/path/file.zip',\n\tfileSize: 503320,\n\tmimeType: 'application/zip',\n\turl: 'https://example.com/file.zip'\n}\n```\n\n#### openFolderWhenDone\n\nType: `boolean`\\\nDefault: `false`\n\nReveal the downloaded file in the system file manager, and if possible, select the file.\n\n#### showBadge\n\nType: `boolean`\\\nDefault: `true`\n\nShow a file count badge on the macOS/Linux dock/taskbar icon when a download is in progress.\n\n#### showProgressBar\n\nType: `boolean`\\\nDefault: `true`\n\nShow a progress bar on the dock/taskbar icon when a download is in progress.\n\n#### overwrite\n\nType: `boolean`\\\nDefault: `false`\n\nAllow downloaded files to overwrite files with the same name in the directory they are saved to.\n\nThe default behavior is to append a number to the filename.\n\n#### dialogOptions\n\nType: [`SaveDialogOptions`](https://www.electronjs.org/docs/latest/api/download-item#downloaditemsetsavedialogoptionsoptions)\\\nDefault: `{}`\n\nCustomize the save dialog.\n\nIf `defaultPath` is not explicity defined, a default value is assigned based on the file path.\n\n## Development\n\nAfter making changes, run the automated tests:\n\n```sh\nnpm test\n```\n\nAnd before submitting a pull request, run the manual tests to manually verify that everything works:\n\n```sh\nnpm start\n```\n\n## Related\n\n- [electron-debug](https://github.com/sindresorhus/electron-debug) - Adds useful debug features to your Electron app\n- [electron-context-menu](https://github.com/sindresorhus/electron-context-menu) - Context menu for your Electron app\n- [electron-store](https://github.com/sindresorhus/electron-store) - Save and load data like user settings, app state, cache, etc\n- [electron-unhandled](https://github.com/sindresorhus/electron-unhandled) - Catch unhandled errors and promise rejections in your Electron app\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Felectron-dl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsindresorhus%2Felectron-dl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsindresorhus%2Felectron-dl/lists"}