diff --git a/docs/api/download-item.md b/docs/api/download-item.md index e3c6c393f8..29ee720697 100644 --- a/docs/api/download-item.md +++ b/docs/api/download-item.md @@ -80,7 +80,9 @@ The `downloadItem` object has the following methods: The API is only available in session's `will-download` callback function. If user doesn't set the save path via the API, Electron will use the original -routine to determine the save path(Usually prompts a save dialog). +routine to determine the save path; this usually prompts a save dialog. + +**[Deprecated](modernization/property-updates.md): use the `savePath` property instead.** #### `downloadItem.getSavePath()` @@ -88,6 +90,8 @@ Returns `String` - The save path of the download item. This will be either the p set via `downloadItem.setSavePath(path)` or the path selected from the shown save dialog. +**[Deprecated](modernization/property-updates.md): use the `savePath` property instead.** + #### `downloadItem.setSaveDialogOptions(options)` * `options` SaveDialogOptions - Set the save file dialog options. This object has the same @@ -181,3 +185,13 @@ Returns `String` - ETag header value. Returns `Double` - Number of seconds since the UNIX epoch when the download was started. + +### Instance Properties + +#### `downloadItem.savePath` + +A `String` property that determines the save file path of the download item. + +The property is only available in session's `will-download` callback function. +If user doesn't set the save path via the property, Electron will use the original +routine to determine the save path; this usually prompts a save dialog. diff --git a/docs/api/modernization/property-updates.md b/docs/api/modernization/property-updates.md index 7f508eb558..f75fdfdb95 100644 --- a/docs/api/modernization/property-updates.md +++ b/docs/api/modernization/property-updates.md @@ -20,9 +20,6 @@ The Electron team is currently undergoing an initiative to convert separate gett * `visibleOnAllWorkspaces` * `crashReporter` module * `uploadToServer` -* `DownloadItem` class - * `savePath` - * `paused` * `Session` module * `preloads` * `webContents` module @@ -47,6 +44,8 @@ The Electron team is currently undergoing an initiative to convert separate gett * `applicationMenu` * `badgeCount` * `name` +* `DownloadItem` class + * `savePath` * `BrowserWindow` module * `autohideMenuBar` * `resizable` diff --git a/shell/browser/api/atom_api_download_item.cc b/shell/browser/api/atom_api_download_item.cc index be5d43d362..5720289445 100644 --- a/shell/browser/api/atom_api_download_item.cc +++ b/shell/browser/api/atom_api_download_item.cc @@ -209,6 +209,8 @@ void DownloadItem::BuildPrototype(v8::Isolate* isolate, .SetMethod("isDone", &DownloadItem::IsDone) .SetMethod("setSavePath", &DownloadItem::SetSavePath) .SetMethod("getSavePath", &DownloadItem::GetSavePath) + .SetProperty("savePath", &DownloadItem::GetSavePath, + &DownloadItem::SetSavePath) .SetMethod("setSaveDialogOptions", &DownloadItem::SetSaveDialogOptions) .SetMethod("getSaveDialogOptions", &DownloadItem::GetSaveDialogOptions) .SetMethod("getLastModifiedTime", &DownloadItem::GetLastModifiedTime) diff --git a/spec-main/api-session-spec.js b/spec-main/api-session-spec.js index 71a4dd0068..f338f29fcc 100644 --- a/spec-main/api-session-spec.js +++ b/spec-main/api-session-spec.js @@ -553,8 +553,8 @@ describe('session module', () => { const assertDownload = (state, item, isCustom = false) => { expect(state).to.equal('completed') expect(item.getFilename()).to.equal('mock.pdf') - expect(path.isAbsolute(item.getSavePath())).to.equal(true) - expect(isPathEqual(item.getSavePath(), downloadFilePath)).to.equal(true) + expect(path.isAbsolute(item.savePath)).to.equal(true) + expect(isPathEqual(item.savePath, downloadFilePath)).to.equal(true) if (isCustom) { expect(item.getURL()).to.equal(`${protocolName}://item`) } else { @@ -571,7 +571,7 @@ describe('session module', () => { it('can download using WebContents.downloadURL', (done) => { const port = downloadServer.address().port w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath item.on('done', function (e, state) { assertDownload(state, item) done() @@ -589,7 +589,7 @@ describe('session module', () => { protocol.registerHttpProtocol(protocolName, handler, (error) => { if (error) return done(error) w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath item.on('done', function (e, state) { assertDownload(state, item, true) done() @@ -612,7 +612,7 @@ describe('session module', () => { } const done = new Promise(resolve => { w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath item.on('done', function (e, state) { resolve([state, item]) }) @@ -626,7 +626,7 @@ describe('session module', () => { it('can cancel download', (done) => { const port = downloadServer.address().port w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath item.on('done', function (e, state) { expect(state).to.equal('cancelled') expect(item.getFilename()).to.equal('mock.pdf') @@ -650,7 +650,7 @@ describe('session module', () => { const port = downloadServer.address().port w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath item.on('done', function (e, state) { expect(item.getFilename()).to.equal('download.pdf') done() @@ -694,7 +694,7 @@ describe('session module', () => { describe('when a save path is specified and the URL is unavailable', () => { it('does not display a save dialog and reports the done state as interrupted', (done) => { w.webContents.session.once('will-download', function (e, item) { - item.setSavePath(downloadFilePath) + item.savePath = downloadFilePath if (item.getState() === 'interrupted') { item.resume() } @@ -725,7 +725,7 @@ describe('session module', () => { expect(item.getMimeType()).to.equal(options.mimeType) expect(item.getReceivedBytes()).to.equal(options.offset) expect(item.getTotalBytes()).to.equal(options.length) - expect(item.getSavePath()).to.equal(downloadFilePath) + expect(item.savePath).to.equal(downloadFilePath) done() }) w.webContents.session.createInterruptedDownload(options) @@ -756,7 +756,7 @@ describe('session module', () => { expect(item.getState()).to.equal('cancelled') const options = { - path: item.getSavePath(), + path: item.savePath, urlChain: item.getURLChain(), mimeType: item.getMimeType(), offset: item.getReceivedBytes(), @@ -778,7 +778,7 @@ describe('session module', () => { const completedItem = await downloadResumed expect(completedItem.getState()).to.equal('completed') expect(completedItem.getFilename()).to.equal('logo.png') - expect(completedItem.getSavePath()).to.equal(downloadFilePath) + expect(completedItem.savePath).to.equal(downloadFilePath) expect(completedItem.getURL()).to.equal(downloadUrl) expect(completedItem.getMimeType()).to.equal('image/png') expect(completedItem.getReceivedBytes()).to.equal(14022)