2251 lines
70 KiB
Markdown
2251 lines
70 KiB
Markdown
# Breaking Changes
|
|
|
|
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least [one major version](tutorial/electron-versioning.md#semver) before the change is made.
|
|
|
|
### Types of Breaking Changes
|
|
|
|
This document uses the following convention to categorize breaking changes:
|
|
|
|
* **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.
|
|
* **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown.
|
|
* **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value.
|
|
* **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release.
|
|
* **Removed:** An API or feature was removed, and is no longer supported by Electron.
|
|
|
|
## Planned Breaking API Changes (30.0)
|
|
|
|
### Behavior Changed: cross-origin iframes now use Permission Policy to access features
|
|
|
|
Cross-origin iframes must now specify features available to a given `iframe` via the `allow`
|
|
attribute in order to access them.
|
|
|
|
See [documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe#allow) for
|
|
more information.
|
|
|
|
### Removed: The `--disable-color-correct-rendering` switch
|
|
|
|
This switch was never formally documented but it's removal is being noted here regardless. Chromium itself now has better support for color spaces so this flag should not be needed.
|
|
|
|
### Behavior Changed: `BrowserView.setAutoResize` behavior on macOS
|
|
|
|
In Electron 30, BrowserView is now a wrapper around the new [WebContentsView](api/web-contents-view.md) API.
|
|
|
|
Previously, the `setAutoResize` function of the `BrowserView` API was backed by [autoresizing](https://developer.apple.com/documentation/appkit/nsview/1483281-autoresizingmask?language=objc) on macOS, and by a custom algorithm on Windows and Linux.
|
|
For simple use cases such as making a BrowserView fill the entire window, the behavior of these two approaches was identical.
|
|
However, in more advanced cases, BrowserViews would be autoresized differently on macOS than they would be on other platforms, as the custom resizing algorithm for Windows and Linux did not perfectly match the behavior of macOS's autoresizing API.
|
|
The autoresizing behavior is now standardized across all platforms.
|
|
|
|
If your app uses `BrowserView.setAutoResize` to do anything more complex than making a BrowserView fill the entire window, it's likely you already had custom logic in place to handle this difference in behavior on macOS.
|
|
If so, that logic will no longer be needed in Electron 30 as autoresizing behavior is consistent.
|
|
|
|
### Removed: `params.inputFormType` property on `context-menu` on `WebContents`
|
|
|
|
The `inputFormType` property of the params object in the `context-menu`
|
|
event from `WebContents` has been removed. Use the new `formControlType`
|
|
property instead.
|
|
|
|
### Removed: `process.getIOCounters()`
|
|
|
|
Chromium has removed access to this information.
|
|
|
|
## Planned Breaking API Changes (29.0)
|
|
|
|
### Behavior Changed: `ipcRenderer` can no longer be sent over the `contextBridge`
|
|
|
|
Attempting to send the entire `ipcRenderer` module as an object over the `contextBridge` will now result in
|
|
an empty object on the receiving side of the bridge. This change was made to remove / mitigate
|
|
a security footgun. You should not directly expose ipcRenderer or its methods over the bridge.
|
|
Instead, provide a safe wrapper like below:
|
|
|
|
```js
|
|
contextBridge.exposeInMainWorld('app', {
|
|
onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
|
|
})
|
|
```
|
|
|
|
### Removed: `renderer-process-crashed` event on `app`
|
|
|
|
The `renderer-process-crashed` event on `app` has been removed.
|
|
Use the new `render-process-gone` event instead.
|
|
|
|
```js
|
|
// Removed
|
|
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
|
|
|
|
// Replace with
|
|
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
|
|
```
|
|
|
|
### Removed: `crashed` event on `WebContents` and `<webview>`
|
|
|
|
The `crashed` events on `WebContents` and `<webview>` have been removed.
|
|
Use the new `render-process-gone` event instead.
|
|
|
|
```js
|
|
// Removed
|
|
win.webContents.on('crashed', (event, killed) => { /* ... */ })
|
|
webview.addEventListener('crashed', (event) => { /* ... */ })
|
|
|
|
// Replace with
|
|
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
|
|
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
|
|
```
|
|
|
|
### Removed: `gpu-process-crashed` event on `app`
|
|
|
|
The `gpu-process-crashed` event on `app` has been removed.
|
|
Use the new `child-process-gone` event instead.
|
|
|
|
```js
|
|
// Removed
|
|
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
|
|
|
|
// Replace with
|
|
app.on('child-process-gone', (event, details) => { /* ... */ })
|
|
```
|
|
|
|
## Planned Breaking API Changes (28.0)
|
|
|
|
### Behavior Changed: `WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`
|
|
|
|
`WebContents.backgroundThrottling` set to false will disable frames throttling
|
|
in the `BrowserWindow` for all `WebContents` displayed by it.
|
|
|
|
### Removed: `BrowserWindow.setTrafficLightPosition(position)`
|
|
|
|
`BrowserWindow.setTrafficLightPosition(position)` has been removed, the
|
|
`BrowserWindow.setWindowButtonPosition(position)` API should be used instead
|
|
which accepts `null` instead of `{ x: 0, y: 0 }` to reset the position to
|
|
system default.
|
|
|
|
```js
|
|
// Removed in Electron 28
|
|
win.setTrafficLightPosition({ x: 10, y: 10 })
|
|
win.setTrafficLightPosition({ x: 0, y: 0 })
|
|
|
|
// Replace with
|
|
win.setWindowButtonPosition({ x: 10, y: 10 })
|
|
win.setWindowButtonPosition(null)
|
|
```
|
|
|
|
### Removed: `BrowserWindow.getTrafficLightPosition()`
|
|
|
|
`BrowserWindow.getTrafficLightPosition()` has been removed, the
|
|
`BrowserWindow.getWindowButtonPosition()` API should be used instead
|
|
which returns `null` instead of `{ x: 0, y: 0 }` when there is no custom
|
|
position.
|
|
|
|
```js
|
|
// Removed in Electron 28
|
|
const pos = win.getTrafficLightPosition()
|
|
if (pos.x === 0 && pos.y === 0) {
|
|
// No custom position.
|
|
}
|
|
|
|
// Replace with
|
|
const ret = win.getWindowButtonPosition()
|
|
if (ret === null) {
|
|
// No custom position.
|
|
}
|
|
```
|
|
|
|
### Removed: `ipcRenderer.sendTo()`
|
|
|
|
The `ipcRenderer.sendTo()` API has been removed. It should be replaced by setting up a [`MessageChannel`](tutorial/message-ports.md#setting-up-a-messagechannel-between-two-renderers) between the renderers.
|
|
|
|
The `senderId` and `senderIsMainFrame` properties of `IpcRendererEvent` have been removed as well.
|
|
|
|
### Removed: `app.runningUnderRosettaTranslation`
|
|
|
|
The `app.runningUnderRosettaTranslation` property has been removed.
|
|
Use `app.runningUnderARM64Translation` instead.
|
|
|
|
```js
|
|
// Removed
|
|
console.log(app.runningUnderRosettaTranslation)
|
|
// Replace with
|
|
console.log(app.runningUnderARM64Translation)
|
|
```
|
|
|
|
### Deprecated: `renderer-process-crashed` event on `app`
|
|
|
|
The `renderer-process-crashed` event on `app` has been deprecated.
|
|
Use the new `render-process-gone` event instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
|
|
|
|
// Replace with
|
|
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
|
|
```
|
|
|
|
### Deprecated: `params.inputFormType` property on `context-menu` on `WebContents`
|
|
|
|
The `inputFormType` property of the params object in the `context-menu`
|
|
event from `WebContents` has been deprecated. Use the new `formControlType`
|
|
property instead.
|
|
|
|
### Deprecated: `crashed` event on `WebContents` and `<webview>`
|
|
|
|
The `crashed` events on `WebContents` and `<webview>` have been deprecated.
|
|
Use the new `render-process-gone` event instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
win.webContents.on('crashed', (event, killed) => { /* ... */ })
|
|
webview.addEventListener('crashed', (event) => { /* ... */ })
|
|
|
|
// Replace with
|
|
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
|
|
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
|
|
```
|
|
|
|
### Deprecated: `gpu-process-crashed` event on `app`
|
|
|
|
The `gpu-process-crashed` event on `app` has been deprecated.
|
|
Use the new `child-process-gone` event instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
|
|
|
|
// Replace with
|
|
app.on('child-process-gone', (event, details) => { /* ... */ })
|
|
```
|
|
|
|
## Planned Breaking API Changes (27.0)
|
|
|
|
### Removed: macOS 10.13 / 10.14 support
|
|
|
|
macOS 10.13 (High Sierra) and macOS 10.14 (Mojave) are no longer supported by [Chromium](https://chromium-review.googlesource.com/c/chromium/src/+/4629466).
|
|
|
|
Older versions of Electron will continue to run on these operating systems, but macOS 10.15 (Catalina)
|
|
or later will be required to run Electron v27.0.0 and higher.
|
|
|
|
### Deprecated: `ipcRenderer.sendTo()`
|
|
|
|
The `ipcRenderer.sendTo()` API has been deprecated. It should be replaced by setting up a [`MessageChannel`](tutorial/message-ports.md#setting-up-a-messagechannel-between-two-renderers) between the renderers.
|
|
|
|
The `senderId` and `senderIsMainFrame` properties of `IpcRendererEvent` have been deprecated as well.
|
|
|
|
### Removed: color scheme events in `systemPreferences`
|
|
|
|
The following `systemPreferences` events have been removed:
|
|
|
|
* `inverted-color-scheme-changed`
|
|
* `high-contrast-color-scheme-changed`
|
|
|
|
Use the new `updated` event on the `nativeTheme` module instead.
|
|
|
|
```js
|
|
// Removed
|
|
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
|
|
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
|
|
|
|
// Replace with
|
|
nativeTheme.on('updated', () => { /* ... */ })
|
|
```
|
|
|
|
### Removed: Some `window.setVibrancy` options on macOS
|
|
|
|
The following vibrancy options have been removed:
|
|
|
|
* 'light'
|
|
* 'medium-light'
|
|
* 'dark'
|
|
* 'ultra-dark'
|
|
* 'appearance-based'
|
|
|
|
These were previously deprecated and have been removed by Apple in 10.15.
|
|
|
|
### Removed: `webContents.getPrinters`
|
|
|
|
The `webContents.getPrinters` method has been removed. Use
|
|
`webContents.getPrintersAsync` instead.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Removed
|
|
console.log(w.webContents.getPrinters())
|
|
// Replace with
|
|
w.webContents.getPrintersAsync().then((printers) => {
|
|
console.log(printers)
|
|
})
|
|
```
|
|
|
|
### Removed: `systemPreferences.{get,set}AppLevelAppearance` and `systemPreferences.appLevelAppearance`
|
|
|
|
The `systemPreferences.getAppLevelAppearance` and `systemPreferences.setAppLevelAppearance`
|
|
methods have been removed, as well as the `systemPreferences.appLevelAppearance` property.
|
|
Use the `nativeTheme` module instead.
|
|
|
|
```js
|
|
// Removed
|
|
systemPreferences.getAppLevelAppearance()
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Removed
|
|
systemPreferences.appLevelAppearance
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Removed
|
|
systemPreferences.setAppLevelAppearance('dark')
|
|
// Replace with
|
|
nativeTheme.themeSource = 'dark'
|
|
```
|
|
|
|
### Removed: `alternate-selected-control-text` value for `systemPreferences.getColor`
|
|
|
|
The `alternate-selected-control-text` value for `systemPreferences.getColor`
|
|
has been removed. Use `selected-content-background` instead.
|
|
|
|
```js
|
|
// Removed
|
|
systemPreferences.getColor('alternate-selected-control-text')
|
|
// Replace with
|
|
systemPreferences.getColor('selected-content-background')
|
|
```
|
|
|
|
## Planned Breaking API Changes (26.0)
|
|
|
|
### Deprecated: `webContents.getPrinters`
|
|
|
|
The `webContents.getPrinters` method has been deprecated. Use
|
|
`webContents.getPrintersAsync` instead.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Deprecated
|
|
console.log(w.webContents.getPrinters())
|
|
// Replace with
|
|
w.webContents.getPrintersAsync().then((printers) => {
|
|
console.log(printers)
|
|
})
|
|
```
|
|
|
|
### Deprecated: `systemPreferences.{get,set}AppLevelAppearance` and `systemPreferences.appLevelAppearance`
|
|
|
|
The `systemPreferences.getAppLevelAppearance` and `systemPreferences.setAppLevelAppearance`
|
|
methods have been deprecated, as well as the `systemPreferences.appLevelAppearance` property.
|
|
Use the `nativeTheme` module instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
systemPreferences.getAppLevelAppearance()
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Deprecated
|
|
systemPreferences.appLevelAppearance
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Deprecated
|
|
systemPreferences.setAppLevelAppearance('dark')
|
|
// Replace with
|
|
nativeTheme.themeSource = 'dark'
|
|
```
|
|
|
|
### Deprecated: `alternate-selected-control-text` value for `systemPreferences.getColor`
|
|
|
|
The `alternate-selected-control-text` value for `systemPreferences.getColor`
|
|
has been deprecated. Use `selected-content-background` instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
systemPreferences.getColor('alternate-selected-control-text')
|
|
// Replace with
|
|
systemPreferences.getColor('selected-content-background')
|
|
```
|
|
|
|
## Planned Breaking API Changes (25.0)
|
|
|
|
### Deprecated: `protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol`
|
|
|
|
The `protocol.register*Protocol` and `protocol.intercept*Protocol` methods have
|
|
been replaced with [`protocol.handle`](api/protocol.md#protocolhandlescheme-handler).
|
|
|
|
The new method can either register a new protocol or intercept an existing
|
|
protocol, and responses can be of any type.
|
|
|
|
```js
|
|
// Deprecated in Electron 25
|
|
protocol.registerBufferProtocol('some-protocol', () => {
|
|
callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
|
|
})
|
|
|
|
// Replace with
|
|
protocol.handle('some-protocol', () => {
|
|
return new Response(
|
|
Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
|
|
{ headers: { 'content-type': 'text/html' } }
|
|
)
|
|
})
|
|
```
|
|
|
|
```js
|
|
// Deprecated in Electron 25
|
|
protocol.registerHttpProtocol('some-protocol', () => {
|
|
callback({ url: 'https://electronjs.org' })
|
|
})
|
|
|
|
// Replace with
|
|
protocol.handle('some-protocol', () => {
|
|
return net.fetch('https://electronjs.org')
|
|
})
|
|
```
|
|
|
|
```js
|
|
// Deprecated in Electron 25
|
|
protocol.registerFileProtocol('some-protocol', () => {
|
|
callback({ filePath: '/path/to/my/file' })
|
|
})
|
|
|
|
// Replace with
|
|
protocol.handle('some-protocol', () => {
|
|
return net.fetch('file:///path/to/my/file')
|
|
})
|
|
```
|
|
|
|
### Deprecated: `BrowserWindow.setTrafficLightPosition(position)`
|
|
|
|
`BrowserWindow.setTrafficLightPosition(position)` has been deprecated, the
|
|
`BrowserWindow.setWindowButtonPosition(position)` API should be used instead
|
|
which accepts `null` instead of `{ x: 0, y: 0 }` to reset the position to
|
|
system default.
|
|
|
|
```js
|
|
// Deprecated in Electron 25
|
|
win.setTrafficLightPosition({ x: 10, y: 10 })
|
|
win.setTrafficLightPosition({ x: 0, y: 0 })
|
|
|
|
// Replace with
|
|
win.setWindowButtonPosition({ x: 10, y: 10 })
|
|
win.setWindowButtonPosition(null)
|
|
```
|
|
|
|
### Deprecated: `BrowserWindow.getTrafficLightPosition()`
|
|
|
|
`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
|
|
`BrowserWindow.getWindowButtonPosition()` API should be used instead
|
|
which returns `null` instead of `{ x: 0, y: 0 }` when there is no custom
|
|
position.
|
|
|
|
```js
|
|
// Deprecated in Electron 25
|
|
const pos = win.getTrafficLightPosition()
|
|
if (pos.x === 0 && pos.y === 0) {
|
|
// No custom position.
|
|
}
|
|
|
|
// Replace with
|
|
const ret = win.getWindowButtonPosition()
|
|
if (ret === null) {
|
|
// No custom position.
|
|
}
|
|
```
|
|
|
|
## Planned Breaking API Changes (24.0)
|
|
|
|
### API Changed: `nativeImage.createThumbnailFromPath(path, size)`
|
|
|
|
The `maxSize` parameter has been changed to `size` to reflect that the size passed in will be the size the thumbnail created. Previously, Windows would not scale the image up if it were smaller than `maxSize`, and
|
|
macOS would always set the size to `maxSize`. Behavior is now the same across platforms.
|
|
|
|
Updated Behavior:
|
|
|
|
```js
|
|
// a 128x128 image.
|
|
const imagePath = path.join('path', 'to', 'capybara.png')
|
|
|
|
// Scaling up a smaller image.
|
|
const upSize = { width: 256, height: 256 }
|
|
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
|
|
console.log(result.getSize()) // { width: 256, height: 256 }
|
|
})
|
|
|
|
// Scaling down a larger image.
|
|
const downSize = { width: 64, height: 64 }
|
|
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
|
|
console.log(result.getSize()) // { width: 64, height: 64 }
|
|
})
|
|
```
|
|
|
|
Previous Behavior (on Windows):
|
|
|
|
```js
|
|
// a 128x128 image
|
|
const imagePath = path.join('path', 'to', 'capybara.png')
|
|
const size = { width: 256, height: 256 }
|
|
nativeImage.createThumbnailFromPath(imagePath, size).then(result => {
|
|
console.log(result.getSize()) // { width: 128, height: 128 }
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (23.0)
|
|
|
|
### Behavior Changed: Draggable Regions on macOS
|
|
|
|
The implementation of draggable regions (using the CSS property `-webkit-app-region: drag`) has changed on macOS to bring it in line with Windows and Linux. Previously, when a region with `-webkit-app-region: no-drag` overlapped a region with `-webkit-app-region: drag`, the `no-drag` region would always take precedence on macOS, regardless of CSS layering. That is, if a `drag` region was above a `no-drag` region, it would be ignored. Beginning in Electron 23, a `drag` region on top of a `no-drag` region will correctly cause the region to be draggable.
|
|
|
|
Additionally, the `customButtonsOnHover` BrowserWindow property previously created a draggable region which ignored the `-webkit-app-region` CSS property. This has now been fixed (see [#37210](https://github.com/electron/electron/issues/37210#issuecomment-1440509592) for discussion).
|
|
|
|
As a result, if your app uses a frameless window with draggable regions on macOS, the regions which are draggable in your app may change in Electron 23.
|
|
|
|
### Removed: Windows 7 / 8 / 8.1 support
|
|
|
|
[Windows 7, Windows 8, and Windows 8.1 are no longer supported](https://www.electronjs.org/blog/windows-7-to-8-1-deprecation-notice). Electron follows the planned Chromium deprecation policy, which will [deprecate Windows 7 support beginning in Chromium 109](https://support.google.com/chrome/thread/185534985/sunsetting-support-for-windows-7-8-8-1-in-early-2023?hl=en).
|
|
|
|
Older versions of Electron will continue to run on these operating systems, but Windows 10 or later will be required to run Electron v23.0.0 and higher.
|
|
|
|
### Removed: BrowserWindow `scroll-touch-*` events
|
|
|
|
The deprecated `scroll-touch-begin`, `scroll-touch-end` and `scroll-touch-edge`
|
|
events on BrowserWindow have been removed. Instead, use the newly available
|
|
[`input-event` event](api/web-contents.md#event-input-event) on WebContents.
|
|
|
|
```js
|
|
// Removed in Electron 23.0
|
|
win.on('scroll-touch-begin', scrollTouchBegin)
|
|
win.on('scroll-touch-edge', scrollTouchEdge)
|
|
win.on('scroll-touch-end', scrollTouchEnd)
|
|
|
|
// Replace with
|
|
win.webContents.on('input-event', (_, event) => {
|
|
if (event.type === 'gestureScrollBegin') {
|
|
scrollTouchBegin()
|
|
} else if (event.type === 'gestureScrollUpdate') {
|
|
scrollTouchEdge()
|
|
} else if (event.type === 'gestureScrollEnd') {
|
|
scrollTouchEnd()
|
|
}
|
|
})
|
|
```
|
|
|
|
### Removed: `webContents.incrementCapturerCount(stayHidden, stayAwake)`
|
|
|
|
The `webContents.incrementCapturerCount(stayHidden, stayAwake)` function has been removed.
|
|
It is now automatically handled by `webContents.capturePage` when a page capture completes.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Removed in Electron 23
|
|
w.webContents.incrementCapturerCount()
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
w.webContents.decrementCapturerCount()
|
|
})
|
|
|
|
// Replace with
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
})
|
|
```
|
|
|
|
### Removed: `webContents.decrementCapturerCount(stayHidden, stayAwake)`
|
|
|
|
The `webContents.decrementCapturerCount(stayHidden, stayAwake)` function has been removed.
|
|
It is now automatically handled by `webContents.capturePage` when a page capture completes.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Removed in Electron 23
|
|
w.webContents.incrementCapturerCount()
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
w.webContents.decrementCapturerCount()
|
|
})
|
|
|
|
// Replace with
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (22.0)
|
|
|
|
### Deprecated: `webContents.incrementCapturerCount(stayHidden, stayAwake)`
|
|
|
|
`webContents.incrementCapturerCount(stayHidden, stayAwake)` has been deprecated.
|
|
It is now automatically handled by `webContents.capturePage` when a page capture completes.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Removed in Electron 23
|
|
w.webContents.incrementCapturerCount()
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
w.webContents.decrementCapturerCount()
|
|
})
|
|
|
|
// Replace with
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
})
|
|
```
|
|
|
|
### Deprecated: `webContents.decrementCapturerCount(stayHidden, stayAwake)`
|
|
|
|
`webContents.decrementCapturerCount(stayHidden, stayAwake)` has been deprecated.
|
|
It is now automatically handled by `webContents.capturePage` when a page capture completes.
|
|
|
|
```js
|
|
const w = new BrowserWindow({ show: false })
|
|
|
|
// Removed in Electron 23
|
|
w.webContents.incrementCapturerCount()
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
w.webContents.decrementCapturerCount()
|
|
})
|
|
|
|
// Replace with
|
|
w.capturePage().then(image => {
|
|
console.log(image.toDataURL())
|
|
})
|
|
```
|
|
|
|
### Removed: WebContents `new-window` event
|
|
|
|
The `new-window` event of WebContents has been removed. It is replaced by [`webContents.setWindowOpenHandler()`](api/web-contents.md#contentssetwindowopenhandlerhandler).
|
|
|
|
```js
|
|
// Removed in Electron 22
|
|
webContents.on('new-window', (event) => {
|
|
event.preventDefault()
|
|
})
|
|
|
|
// Replace with
|
|
webContents.setWindowOpenHandler((details) => {
|
|
return { action: 'deny' }
|
|
})
|
|
```
|
|
|
|
### Removed: `<webview>` `new-window` event
|
|
|
|
The `new-window` event of `<webview>` has been removed. There is no direct replacement.
|
|
|
|
```js
|
|
// Removed in Electron 22
|
|
webview.addEventListener('new-window', (event) => {})
|
|
```
|
|
|
|
```js
|
|
// Replace with
|
|
|
|
// main.js
|
|
mainWindow.webContents.on('did-attach-webview', (event, wc) => {
|
|
wc.setWindowOpenHandler((details) => {
|
|
mainWindow.webContents.send('webview-new-window', wc.id, details)
|
|
return { action: 'deny' }
|
|
})
|
|
})
|
|
|
|
// preload.js
|
|
const { ipcRenderer } = require('electron')
|
|
ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
|
|
console.log('webview-new-window', webContentsId, details)
|
|
document.getElementById('webview').dispatchEvent(new Event('new-window'))
|
|
})
|
|
|
|
// renderer.js
|
|
document.getElementById('webview').addEventListener('new-window', () => {
|
|
console.log('got new-window event')
|
|
})
|
|
```
|
|
|
|
### Deprecated: BrowserWindow `scroll-touch-*` events
|
|
|
|
The `scroll-touch-begin`, `scroll-touch-end` and `scroll-touch-edge` events on
|
|
BrowserWindow are deprecated. Instead, use the newly available [`input-event`
|
|
event](api/web-contents.md#event-input-event) on WebContents.
|
|
|
|
```js
|
|
// Deprecated
|
|
win.on('scroll-touch-begin', scrollTouchBegin)
|
|
win.on('scroll-touch-edge', scrollTouchEdge)
|
|
win.on('scroll-touch-end', scrollTouchEnd)
|
|
|
|
// Replace with
|
|
win.webContents.on('input-event', (_, event) => {
|
|
if (event.type === 'gestureScrollBegin') {
|
|
scrollTouchBegin()
|
|
} else if (event.type === 'gestureScrollUpdate') {
|
|
scrollTouchEdge()
|
|
} else if (event.type === 'gestureScrollEnd') {
|
|
scrollTouchEnd()
|
|
}
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (21.0)
|
|
|
|
### Behavior Changed: V8 Memory Cage enabled
|
|
|
|
The V8 memory cage has been enabled, which has implications for native modules
|
|
which wrap non-V8 memory with `ArrayBuffer` or `Buffer`. See the [blog post
|
|
about the V8 memory cage](https://www.electronjs.org/blog/v8-memory-cage) for
|
|
more details.
|
|
|
|
### API Changed: `webContents.printToPDF()`
|
|
|
|
`webContents.printToPDF()` has been modified to conform to [`Page.printToPDF`](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-printToPDF) in the Chrome DevTools Protocol. This has been changes in order to
|
|
address changes upstream that made our previous implementation untenable and rife with bugs.
|
|
|
|
**Arguments Changed**
|
|
|
|
* `pageRanges`
|
|
|
|
**Arguments Removed**
|
|
|
|
* `printSelectionOnly`
|
|
* `marginsType`
|
|
* `headerFooter`
|
|
* `scaleFactor`
|
|
|
|
**Arguments Added**
|
|
|
|
* `headerTemplate`
|
|
* `footerTemplate`
|
|
* `displayHeaderFooter`
|
|
* `margins`
|
|
* `scale`
|
|
* `preferCSSPageSize`
|
|
|
|
```js
|
|
// Main process
|
|
const { webContents } = require('electron')
|
|
|
|
webContents.printToPDF({
|
|
landscape: true,
|
|
displayHeaderFooter: true,
|
|
printBackground: true,
|
|
scale: 2,
|
|
pageSize: 'Ledger',
|
|
margins: {
|
|
top: 2,
|
|
bottom: 2,
|
|
left: 2,
|
|
right: 2
|
|
},
|
|
pageRanges: '1-5, 8, 11-13',
|
|
headerTemplate: '<h1>Title</h1>',
|
|
footerTemplate: '<div><span class="pageNumber"></span></div>',
|
|
preferCSSPageSize: true
|
|
}).then(data => {
|
|
fs.writeFile(pdfPath, data, (error) => {
|
|
if (error) throw error
|
|
console.log(`Wrote PDF successfully to ${pdfPath}`)
|
|
})
|
|
}).catch(error => {
|
|
console.log(`Failed to write PDF to ${pdfPath}: `, error)
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (20.0)
|
|
|
|
### Removed: macOS 10.11 / 10.12 support
|
|
|
|
macOS 10.11 (El Capitan) and macOS 10.12 (Sierra) are no longer supported by [Chromium](https://chromium-review.googlesource.com/c/chromium/src/+/3646050).
|
|
|
|
Older versions of Electron will continue to run on these operating systems, but macOS 10.13 (High Sierra)
|
|
or later will be required to run Electron v20.0.0 and higher.
|
|
|
|
### Default Changed: renderers without `nodeIntegration: true` are sandboxed by default
|
|
|
|
Previously, renderers that specified a preload script defaulted to being
|
|
unsandboxed. This meant that by default, preload scripts had access to Node.js.
|
|
In Electron 20, this default has changed. Beginning in Electron 20, renderers
|
|
will be sandboxed by default, unless `nodeIntegration: true` or `sandbox: false`
|
|
is specified.
|
|
|
|
If your preload scripts do not depend on Node, no action is needed. If your
|
|
preload scripts _do_ depend on Node, either refactor them to remove Node usage
|
|
from the renderer, or explicitly specify `sandbox: false` for the relevant
|
|
renderers.
|
|
|
|
### Removed: `skipTaskbar` on Linux
|
|
|
|
On X11, `skipTaskbar` sends a `_NET_WM_STATE_SKIP_TASKBAR` message to the X11
|
|
window manager. There is not a direct equivalent for Wayland, and the known
|
|
workarounds have unacceptable tradeoffs (e.g. Window.is_skip_taskbar in GNOME
|
|
requires unsafe mode), so Electron is unable to support this feature on Linux.
|
|
|
|
### API Changed: `session.setDevicePermissionHandler(handler)`
|
|
|
|
The handler invoked when `session.setDevicePermissionHandler(handler)` is used
|
|
has a change to its arguments. This handler no longer is passed a frame
|
|
[`WebFrameMain`](api/web-frame-main.md), but instead is passed the `origin`, which
|
|
is the origin that is checking for device permission.
|
|
|
|
## Planned Breaking API Changes (19.0)
|
|
|
|
### Removed: IA32 Linux binaries
|
|
|
|
This is a result of Chromium 102.0.4999.0 dropping support for IA32 Linux.
|
|
This concludes the [removal of support for IA32 Linux](#removed-ia32-linux-support).
|
|
|
|
## Planned Breaking API Changes (18.0)
|
|
|
|
### Removed: `nativeWindowOpen`
|
|
|
|
Prior to Electron 15, `window.open` was by default shimmed to use
|
|
`BrowserWindowProxy`. This meant that `window.open('about:blank')` did not work
|
|
to open synchronously scriptable child windows, among other incompatibilities.
|
|
Since Electron 15, `nativeWindowOpen` has been enabled by default.
|
|
|
|
See the documentation for [window.open in Electron](api/window-open.md)
|
|
for more details.
|
|
|
|
## Planned Breaking API Changes (17.0)
|
|
|
|
### Removed: `desktopCapturer.getSources` in the renderer
|
|
|
|
The `desktopCapturer.getSources` API is now only available in the main process.
|
|
This has been changed in order to improve the default security of Electron
|
|
apps.
|
|
|
|
If you need this functionality, it can be replaced as follows:
|
|
|
|
```js
|
|
// Main process
|
|
const { ipcMain, desktopCapturer } = require('electron')
|
|
|
|
ipcMain.handle(
|
|
'DESKTOP_CAPTURER_GET_SOURCES',
|
|
(event, opts) => desktopCapturer.getSources(opts)
|
|
)
|
|
```
|
|
|
|
```js
|
|
// Renderer process
|
|
const { ipcRenderer } = require('electron')
|
|
|
|
const desktopCapturer = {
|
|
getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
|
|
}
|
|
```
|
|
|
|
However, you should consider further restricting the information returned to
|
|
the renderer; for instance, displaying a source selector to the user and only
|
|
returning the selected source.
|
|
|
|
### Deprecated: `nativeWindowOpen`
|
|
|
|
Prior to Electron 15, `window.open` was by default shimmed to use
|
|
`BrowserWindowProxy`. This meant that `window.open('about:blank')` did not work
|
|
to open synchronously scriptable child windows, among other incompatibilities.
|
|
Since Electron 15, `nativeWindowOpen` has been enabled by default.
|
|
|
|
See the documentation for [window.open in Electron](api/window-open.md)
|
|
for more details.
|
|
|
|
## Planned Breaking API Changes (16.0)
|
|
|
|
### Behavior Changed: `crashReporter` implementation switched to Crashpad on Linux
|
|
|
|
The underlying implementation of the `crashReporter` API on Linux has changed
|
|
from Breakpad to Crashpad, bringing it in line with Windows and Mac. As a
|
|
result of this, child processes are now automatically monitored, and calling
|
|
`process.crashReporter.start` in Node child processes is no longer needed (and
|
|
is not advisable, as it will start a second instance of the Crashpad reporter).
|
|
|
|
There are also some subtle changes to how annotations will be reported on
|
|
Linux, including that long values will no longer be split between annotations
|
|
appended with `__1`, `__2` and so on, and instead will be truncated at the
|
|
(new, longer) annotation value limit.
|
|
|
|
### Deprecated: `desktopCapturer.getSources` in the renderer
|
|
|
|
Usage of the `desktopCapturer.getSources` API in the renderer has been
|
|
deprecated and will be removed. This change improves the default security of
|
|
Electron apps.
|
|
|
|
See [here](#removed-desktopcapturergetsources-in-the-renderer) for details on
|
|
how to replace this API in your app.
|
|
|
|
## Planned Breaking API Changes (15.0)
|
|
|
|
### Default Changed: `nativeWindowOpen` defaults to `true`
|
|
|
|
Prior to Electron 15, `window.open` was by default shimmed to use
|
|
`BrowserWindowProxy`. This meant that `window.open('about:blank')` did not work
|
|
to open synchronously scriptable child windows, among other incompatibilities.
|
|
`nativeWindowOpen` is no longer experimental, and is now the default.
|
|
|
|
See the documentation for [window.open in Electron](api/window-open.md)
|
|
for more details.
|
|
|
|
### Deprecated: `app.runningUnderRosettaTranslation`
|
|
|
|
The `app.runningUnderRosettaTranslation` property has been deprecated.
|
|
Use `app.runningUnderARM64Translation` instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
console.log(app.runningUnderRosettaTranslation)
|
|
// Replace with
|
|
console.log(app.runningUnderARM64Translation)
|
|
```
|
|
|
|
## Planned Breaking API Changes (14.0)
|
|
|
|
### Removed: `remote` module
|
|
|
|
The `remote` module was deprecated in Electron 12, and will be removed in
|
|
Electron 14. It is replaced by the
|
|
[`@electron/remote`](https://github.com/electron/remote) module.
|
|
|
|
```js
|
|
// Deprecated in Electron 12:
|
|
const { BrowserWindow } = require('electron').remote
|
|
```
|
|
|
|
```js
|
|
// Replace with:
|
|
const { BrowserWindow } = require('@electron/remote')
|
|
|
|
// In the main process:
|
|
require('@electron/remote/main').initialize()
|
|
```
|
|
|
|
### Removed: `app.allowRendererProcessReuse`
|
|
|
|
The `app.allowRendererProcessReuse` property will be removed as part of our plan to
|
|
more closely align with Chromium's process model for security, performance and maintainability.
|
|
|
|
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
|
|
|
|
### Removed: Browser Window Affinity
|
|
|
|
The `affinity` option when constructing a new `BrowserWindow` will be removed
|
|
as part of our plan to more closely align with Chromium's process model for security,
|
|
performance and maintainability.
|
|
|
|
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
|
|
|
|
### API Changed: `window.open()`
|
|
|
|
The optional parameter `frameName` will no longer set the title of the window. This now follows the specification described by the [native documentation](https://developer.mozilla.org/en-US/docs/Web/API/Window/open#parameters) under the corresponding parameter `windowName`.
|
|
|
|
If you were using this parameter to set the title of a window, you can instead use [win.setTitle(title)](api/browser-window.md#winsettitletitle).
|
|
|
|
### Removed: `worldSafeExecuteJavaScript`
|
|
|
|
In Electron 14, `worldSafeExecuteJavaScript` will be removed. There is no alternative, please
|
|
ensure your code works with this property enabled. It has been enabled by default since Electron
|
|
12.
|
|
|
|
You will be affected by this change if you use either `webFrame.executeJavaScript` or `webFrame.executeJavaScriptInIsolatedWorld`. You will need to ensure that values returned by either of those methods are supported by the [Context Bridge API](api/context-bridge.md#parameter--error--return-type-support) as these methods use the same value passing semantics.
|
|
|
|
### Removed: BrowserWindowConstructorOptions inheriting from parent windows
|
|
|
|
Prior to Electron 14, windows opened with `window.open` would inherit
|
|
BrowserWindow constructor options such as `transparent` and `resizable` from
|
|
their parent window. Beginning with Electron 14, this behavior is removed, and
|
|
windows will not inherit any BrowserWindow constructor options from their
|
|
parents.
|
|
|
|
Instead, explicitly set options for the new window with `setWindowOpenHandler`:
|
|
|
|
```js
|
|
webContents.setWindowOpenHandler((details) => {
|
|
return {
|
|
action: 'allow',
|
|
overrideBrowserWindowOptions: {
|
|
// ...
|
|
}
|
|
}
|
|
})
|
|
```
|
|
|
|
### Removed: `additionalFeatures`
|
|
|
|
The deprecated `additionalFeatures` property in the `new-window` and
|
|
`did-create-window` events of WebContents has been removed. Since `new-window`
|
|
uses positional arguments, the argument is still present, but will always be
|
|
the empty array `[]`. (Though note, the `new-window` event itself is
|
|
deprecated, and is replaced by `setWindowOpenHandler`.) Bare keys in window
|
|
features will now present as keys with the value `true` in the options object.
|
|
|
|
```js
|
|
// Removed in Electron 14
|
|
// Triggered by window.open('...', '', 'my-key')
|
|
webContents.on('did-create-window', (window, details) => {
|
|
if (details.additionalFeatures.includes('my-key')) {
|
|
// ...
|
|
}
|
|
})
|
|
|
|
// Replace with
|
|
webContents.on('did-create-window', (window, details) => {
|
|
if (details.options['my-key']) {
|
|
// ...
|
|
}
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (13.0)
|
|
|
|
### API Changed: `session.setPermissionCheckHandler(handler)`
|
|
|
|
The `handler` methods first parameter was previously always a `webContents`, it can now sometimes be `null`. You should use the `requestingOrigin`, `embeddingOrigin` and `securityOrigin` properties to respond to the permission check correctly. As the `webContents` can be `null` it can no longer be relied on.
|
|
|
|
```js
|
|
// Old code
|
|
session.setPermissionCheckHandler((webContents, permission) => {
|
|
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
|
|
return true
|
|
}
|
|
return false
|
|
})
|
|
|
|
// Replace with
|
|
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
|
|
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
|
|
return true
|
|
}
|
|
return false
|
|
})
|
|
```
|
|
|
|
### Removed: `shell.moveItemToTrash()`
|
|
|
|
The deprecated synchronous `shell.moveItemToTrash()` API has been removed. Use
|
|
the asynchronous `shell.trashItem()` instead.
|
|
|
|
```js
|
|
// Removed in Electron 13
|
|
shell.moveItemToTrash(path)
|
|
// Replace with
|
|
shell.trashItem(path).then(/* ... */)
|
|
```
|
|
|
|
### Removed: `BrowserWindow` extension APIs
|
|
|
|
The deprecated extension APIs have been removed:
|
|
|
|
* `BrowserWindow.addExtension(path)`
|
|
* `BrowserWindow.addDevToolsExtension(path)`
|
|
* `BrowserWindow.removeExtension(name)`
|
|
* `BrowserWindow.removeDevToolsExtension(name)`
|
|
* `BrowserWindow.getExtensions()`
|
|
* `BrowserWindow.getDevToolsExtensions()`
|
|
|
|
Use the session APIs instead:
|
|
|
|
* `ses.loadExtension(path)`
|
|
* `ses.removeExtension(extension_id)`
|
|
* `ses.getAllExtensions()`
|
|
|
|
```js
|
|
// Removed in Electron 13
|
|
BrowserWindow.addExtension(path)
|
|
BrowserWindow.addDevToolsExtension(path)
|
|
// Replace with
|
|
session.defaultSession.loadExtension(path)
|
|
```
|
|
|
|
```js
|
|
// Removed in Electron 13
|
|
BrowserWindow.removeExtension(name)
|
|
BrowserWindow.removeDevToolsExtension(name)
|
|
// Replace with
|
|
session.defaultSession.removeExtension(extension_id)
|
|
```
|
|
|
|
```js
|
|
// Removed in Electron 13
|
|
BrowserWindow.getExtensions()
|
|
BrowserWindow.getDevToolsExtensions()
|
|
// Replace with
|
|
session.defaultSession.getAllExtensions()
|
|
```
|
|
|
|
### Removed: methods in `systemPreferences`
|
|
|
|
The following `systemPreferences` methods have been deprecated:
|
|
|
|
* `systemPreferences.isDarkMode()`
|
|
* `systemPreferences.isInvertedColorScheme()`
|
|
* `systemPreferences.isHighContrastColorScheme()`
|
|
|
|
Use the following `nativeTheme` properties instead:
|
|
|
|
* `nativeTheme.shouldUseDarkColors`
|
|
* `nativeTheme.shouldUseInvertedColorScheme`
|
|
* `nativeTheme.shouldUseHighContrastColors`
|
|
|
|
```js
|
|
// Removed in Electron 13
|
|
systemPreferences.isDarkMode()
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Removed in Electron 13
|
|
systemPreferences.isInvertedColorScheme()
|
|
// Replace with
|
|
nativeTheme.shouldUseInvertedColorScheme
|
|
|
|
// Removed in Electron 13
|
|
systemPreferences.isHighContrastColorScheme()
|
|
// Replace with
|
|
nativeTheme.shouldUseHighContrastColors
|
|
```
|
|
|
|
### Deprecated: WebContents `new-window` event
|
|
|
|
The `new-window` event of WebContents has been deprecated. It is replaced by [`webContents.setWindowOpenHandler()`](api/web-contents.md#contentssetwindowopenhandlerhandler).
|
|
|
|
```js
|
|
// Deprecated in Electron 13
|
|
webContents.on('new-window', (event) => {
|
|
event.preventDefault()
|
|
})
|
|
|
|
// Replace with
|
|
webContents.setWindowOpenHandler((details) => {
|
|
return { action: 'deny' }
|
|
})
|
|
```
|
|
|
|
## Planned Breaking API Changes (12.0)
|
|
|
|
### Removed: Pepper Flash support
|
|
|
|
Chromium has removed support for Flash, and so we must follow suit. See
|
|
Chromium's [Flash Roadmap](https://www.chromium.org/flash-roadmap) for more
|
|
details.
|
|
|
|
### Default Changed: `worldSafeExecuteJavaScript` defaults to `true`
|
|
|
|
In Electron 12, `worldSafeExecuteJavaScript` will be enabled by default. To restore
|
|
the previous behavior, `worldSafeExecuteJavaScript: false` must be specified in WebPreferences.
|
|
Please note that setting this option to `false` is **insecure**.
|
|
|
|
This option will be removed in Electron 14 so please migrate your code to support the default
|
|
value.
|
|
|
|
### Default Changed: `contextIsolation` defaults to `true`
|
|
|
|
In Electron 12, `contextIsolation` will be enabled by default. To restore
|
|
the previous behavior, `contextIsolation: false` must be specified in WebPreferences.
|
|
|
|
We [recommend having contextIsolation enabled](tutorial/security.md#3-enable-context-isolation) for the security of your application.
|
|
|
|
Another implication is that `require()` cannot be used in the renderer process unless
|
|
`nodeIntegration` is `true` and `contextIsolation` is `false`.
|
|
|
|
For more details see: https://github.com/electron/electron/issues/23506
|
|
|
|
### Removed: `crashReporter.getCrashesDirectory()`
|
|
|
|
The `crashReporter.getCrashesDirectory` method has been removed. Usage
|
|
should be replaced by `app.getPath('crashDumps')`.
|
|
|
|
```js
|
|
// Removed in Electron 12
|
|
crashReporter.getCrashesDirectory()
|
|
// Replace with
|
|
app.getPath('crashDumps')
|
|
```
|
|
|
|
### Removed: `crashReporter` methods in the renderer process
|
|
|
|
The following `crashReporter` methods are no longer available in the renderer
|
|
process:
|
|
|
|
* `crashReporter.start`
|
|
* `crashReporter.getLastCrashReport`
|
|
* `crashReporter.getUploadedReports`
|
|
* `crashReporter.getUploadToServer`
|
|
* `crashReporter.setUploadToServer`
|
|
* `crashReporter.getCrashesDirectory`
|
|
|
|
They should be called only from the main process.
|
|
|
|
See [#23265](https://github.com/electron/electron/pull/23265) for more details.
|
|
|
|
### Default Changed: `crashReporter.start({ compress: true })`
|
|
|
|
The default value of the `compress` option to `crashReporter.start` has changed
|
|
from `false` to `true`. This means that crash dumps will be uploaded to the
|
|
crash ingestion server with the `Content-Encoding: gzip` header, and the body
|
|
will be compressed.
|
|
|
|
If your crash ingestion server does not support compressed payloads, you can
|
|
turn off compression by specifying `{ compress: false }` in the crash reporter
|
|
options.
|
|
|
|
### Deprecated: `remote` module
|
|
|
|
The `remote` module is deprecated in Electron 12, and will be removed in
|
|
Electron 14. It is replaced by the
|
|
[`@electron/remote`](https://github.com/electron/remote) module.
|
|
|
|
```js
|
|
// Deprecated in Electron 12:
|
|
const { BrowserWindow } = require('electron').remote
|
|
```
|
|
|
|
```js
|
|
// Replace with:
|
|
const { BrowserWindow } = require('@electron/remote')
|
|
|
|
// In the main process:
|
|
require('@electron/remote/main').initialize()
|
|
```
|
|
|
|
### Deprecated: `shell.moveItemToTrash()`
|
|
|
|
The synchronous `shell.moveItemToTrash()` has been replaced by the new,
|
|
asynchronous `shell.trashItem()`.
|
|
|
|
```js
|
|
// Deprecated in Electron 12
|
|
shell.moveItemToTrash(path)
|
|
// Replace with
|
|
shell.trashItem(path).then(/* ... */)
|
|
```
|
|
|
|
## Planned Breaking API Changes (11.0)
|
|
|
|
### Removed: `BrowserView.{destroy, fromId, fromWebContents, getAllViews}` and `id` property of `BrowserView`
|
|
|
|
The experimental APIs `BrowserView.{destroy, fromId, fromWebContents, getAllViews}`
|
|
have now been removed. Additionally, the `id` property of `BrowserView`
|
|
has also been removed.
|
|
|
|
For more detailed information, see [#23578](https://github.com/electron/electron/pull/23578).
|
|
|
|
## Planned Breaking API Changes (10.0)
|
|
|
|
### Deprecated: `companyName` argument to `crashReporter.start()`
|
|
|
|
The `companyName` argument to `crashReporter.start()`, which was previously
|
|
required, is now optional, and further, is deprecated. To get the same
|
|
behavior in a non-deprecated way, you can pass a `companyName` value in
|
|
`globalExtra`.
|
|
|
|
```js
|
|
// Deprecated in Electron 10
|
|
crashReporter.start({ companyName: 'Umbrella Corporation' })
|
|
// Replace with
|
|
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })
|
|
```
|
|
|
|
### Deprecated: `crashReporter.getCrashesDirectory()`
|
|
|
|
The `crashReporter.getCrashesDirectory` method has been deprecated. Usage
|
|
should be replaced by `app.getPath('crashDumps')`.
|
|
|
|
```js
|
|
// Deprecated in Electron 10
|
|
crashReporter.getCrashesDirectory()
|
|
// Replace with
|
|
app.getPath('crashDumps')
|
|
```
|
|
|
|
### Deprecated: `crashReporter` methods in the renderer process
|
|
|
|
Calling the following `crashReporter` methods from the renderer process is
|
|
deprecated:
|
|
|
|
* `crashReporter.start`
|
|
* `crashReporter.getLastCrashReport`
|
|
* `crashReporter.getUploadedReports`
|
|
* `crashReporter.getUploadToServer`
|
|
* `crashReporter.setUploadToServer`
|
|
* `crashReporter.getCrashesDirectory`
|
|
|
|
The only non-deprecated methods remaining in the `crashReporter` module in the
|
|
renderer are `addExtraParameter`, `removeExtraParameter` and `getParameters`.
|
|
|
|
All above methods remain non-deprecated when called from the main process.
|
|
|
|
See [#23265](https://github.com/electron/electron/pull/23265) for more details.
|
|
|
|
### Deprecated: `crashReporter.start({ compress: false })`
|
|
|
|
Setting `{ compress: false }` in `crashReporter.start` is deprecated. Nearly
|
|
all crash ingestion servers support gzip compression. This option will be
|
|
removed in a future version of Electron.
|
|
|
|
### Default Changed: `enableRemoteModule` defaults to `false`
|
|
|
|
In Electron 9, using the remote module without explicitly enabling it via the
|
|
`enableRemoteModule` WebPreferences option began emitting a warning. In
|
|
Electron 10, the remote module is now disabled by default. To use the remote
|
|
module, `enableRemoteModule: true` must be specified in WebPreferences:
|
|
|
|
```js
|
|
const w = new BrowserWindow({
|
|
webPreferences: {
|
|
enableRemoteModule: true
|
|
}
|
|
})
|
|
```
|
|
|
|
We [recommend moving away from the remote
|
|
module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-70d69500f31).
|
|
|
|
### `protocol.unregisterProtocol`
|
|
|
|
### `protocol.uninterceptProtocol`
|
|
|
|
The APIs are now synchronous and the optional callback is no longer needed.
|
|
|
|
```js
|
|
// Deprecated
|
|
protocol.unregisterProtocol(scheme, () => { /* ... */ })
|
|
// Replace with
|
|
protocol.unregisterProtocol(scheme)
|
|
```
|
|
|
|
### `protocol.registerFileProtocol`
|
|
|
|
### `protocol.registerBufferProtocol`
|
|
|
|
### `protocol.registerStringProtocol`
|
|
|
|
### `protocol.registerHttpProtocol`
|
|
|
|
### `protocol.registerStreamProtocol`
|
|
|
|
### `protocol.interceptFileProtocol`
|
|
|
|
### `protocol.interceptStringProtocol`
|
|
|
|
### `protocol.interceptBufferProtocol`
|
|
|
|
### `protocol.interceptHttpProtocol`
|
|
|
|
### `protocol.interceptStreamProtocol`
|
|
|
|
The APIs are now synchronous and the optional callback is no longer needed.
|
|
|
|
```js
|
|
// Deprecated
|
|
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
|
|
// Replace with
|
|
protocol.registerFileProtocol(scheme, handler)
|
|
```
|
|
|
|
The registered or intercepted protocol does not have effect on current page
|
|
until navigation happens.
|
|
|
|
### `protocol.isProtocolHandled`
|
|
|
|
This API is deprecated and users should use `protocol.isProtocolRegistered`
|
|
and `protocol.isProtocolIntercepted` instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
|
|
// Replace with
|
|
const isRegistered = protocol.isProtocolRegistered(scheme)
|
|
const isIntercepted = protocol.isProtocolIntercepted(scheme)
|
|
```
|
|
|
|
## Planned Breaking API Changes (9.0)
|
|
|
|
### Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default
|
|
|
|
As of Electron 9 we do not allow loading of non-context-aware native modules in
|
|
the renderer process. This is to improve security, performance and maintainability
|
|
of Electron as a project.
|
|
|
|
If this impacts you, you can temporarily set `app.allowRendererProcessReuse` to `false`
|
|
to revert to the old behavior. This flag will only be an option until Electron 11 so
|
|
you should plan to update your native modules to be context aware.
|
|
|
|
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
|
|
|
|
### Deprecated: `BrowserWindow` extension APIs
|
|
|
|
The following extension APIs have been deprecated:
|
|
|
|
* `BrowserWindow.addExtension(path)`
|
|
* `BrowserWindow.addDevToolsExtension(path)`
|
|
* `BrowserWindow.removeExtension(name)`
|
|
* `BrowserWindow.removeDevToolsExtension(name)`
|
|
* `BrowserWindow.getExtensions()`
|
|
* `BrowserWindow.getDevToolsExtensions()`
|
|
|
|
Use the session APIs instead:
|
|
|
|
* `ses.loadExtension(path)`
|
|
* `ses.removeExtension(extension_id)`
|
|
* `ses.getAllExtensions()`
|
|
|
|
```js
|
|
// Deprecated in Electron 9
|
|
BrowserWindow.addExtension(path)
|
|
BrowserWindow.addDevToolsExtension(path)
|
|
// Replace with
|
|
session.defaultSession.loadExtension(path)
|
|
```
|
|
|
|
```js
|
|
// Deprecated in Electron 9
|
|
BrowserWindow.removeExtension(name)
|
|
BrowserWindow.removeDevToolsExtension(name)
|
|
// Replace with
|
|
session.defaultSession.removeExtension(extension_id)
|
|
```
|
|
|
|
```js
|
|
// Deprecated in Electron 9
|
|
BrowserWindow.getExtensions()
|
|
BrowserWindow.getDevToolsExtensions()
|
|
// Replace with
|
|
session.defaultSession.getAllExtensions()
|
|
```
|
|
|
|
### Removed: `<webview>.getWebContents()`
|
|
|
|
This API, which was deprecated in Electron 8.0, is now removed.
|
|
|
|
```js
|
|
// Removed in Electron 9.0
|
|
webview.getWebContents()
|
|
// Replace with
|
|
const { remote } = require('electron')
|
|
remote.webContents.fromId(webview.getWebContentsId())
|
|
```
|
|
|
|
### Removed: `webFrame.setLayoutZoomLevelLimits()`
|
|
|
|
Chromium has removed support for changing the layout zoom level limits, and it
|
|
is beyond Electron's capacity to maintain it. The function was deprecated in
|
|
Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits
|
|
are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
|
|
[here](https://chromium.googlesource.com/chromium/src/+/938b37a6d2886bf8335fc7db792f1eb46c65b2ae/third_party/blink/common/page/page_zoom.cc#11).
|
|
|
|
### Behavior Changed: Sending non-JS objects over IPC now throws an exception
|
|
|
|
In Electron 8.0, IPC was changed to use the Structured Clone Algorithm,
|
|
bringing significant performance improvements. To help ease the transition, the
|
|
old IPC serialization algorithm was kept and used for some objects that aren't
|
|
serializable with Structured Clone. In particular, DOM objects (e.g. `Element`,
|
|
`Location` and `DOMMatrix`), Node.js objects backed by C++ classes (e.g.
|
|
`process.env`, some members of `Stream`), and Electron objects backed by C++
|
|
classes (e.g. `WebContents`, `BrowserWindow` and `WebFrame`) are not
|
|
serializable with Structured Clone. Whenever the old algorithm was invoked, a
|
|
deprecation warning was printed.
|
|
|
|
In Electron 9.0, the old serialization algorithm has been removed, and sending
|
|
such non-serializable objects will now throw an "object could not be cloned"
|
|
error.
|
|
|
|
### API Changed: `shell.openItem` is now `shell.openPath`
|
|
|
|
The `shell.openItem` API has been replaced with an asynchronous `shell.openPath` API.
|
|
You can see the original API proposal and reasoning [here](https://github.com/electron/governance/blob/main/wg-api/spec-documents/shell-openitem.md).
|
|
|
|
## Planned Breaking API Changes (8.0)
|
|
|
|
### Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm
|
|
|
|
The algorithm used to serialize objects sent over IPC (through
|
|
`ipcRenderer.send`, `ipcRenderer.sendSync`, `WebContents.send` and related
|
|
methods) has been switched from a custom algorithm to V8's built-in [Structured
|
|
Clone Algorithm][SCA], the same algorithm used to serialize messages for
|
|
`postMessage`. This brings about a 2x performance improvement for large
|
|
messages, but also brings some breaking changes in behavior.
|
|
|
|
* Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any
|
|
such values, over IPC will now throw an exception, instead of silently
|
|
converting the functions to `undefined`.
|
|
|
|
```js
|
|
// Previously:
|
|
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
|
|
// => results in { value: 3 } arriving in the main process
|
|
|
|
// From Electron 8:
|
|
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
|
|
// => throws Error("() => {} could not be cloned.")
|
|
```
|
|
|
|
* `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead
|
|
of being converted to `null`.
|
|
* Objects containing cyclic references will now be correctly serialized,
|
|
instead of being converted to `null`.
|
|
* `Set`, `Map`, `Error` and `RegExp` values will be correctly serialized,
|
|
instead of being converted to `{}`.
|
|
* `BigInt` values will be correctly serialized, instead of being converted to
|
|
`null`.
|
|
* Sparse arrays will be serialized as such, instead of being converted to dense
|
|
arrays with `null`s.
|
|
* `Date` objects will be transferred as `Date` objects, instead of being
|
|
converted to their ISO string representation.
|
|
* Typed Arrays (such as `Uint8Array`, `Uint16Array`, `Uint32Array` and so on)
|
|
will be transferred as such, instead of being converted to Node.js `Buffer`.
|
|
* Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can
|
|
convert a `Uint8Array` back to a Node.js `Buffer` by wrapping the underlying
|
|
`ArrayBuffer`:
|
|
|
|
```js
|
|
Buffer.from(value.buffer, value.byteOffset, value.byteLength)
|
|
```
|
|
|
|
Sending any objects that aren't native JS types, such as DOM objects (e.g.
|
|
`Element`, `Location`, `DOMMatrix`), Node.js objects (e.g. `process.env`,
|
|
`Stream`), or Electron objects (e.g. `WebContents`, `BrowserWindow`,
|
|
`WebFrame`) is deprecated. In Electron 8, these objects will be serialized as
|
|
before with a DeprecationWarning message, but starting in Electron 9, sending
|
|
these kinds of objects will throw a 'could not be cloned' error.
|
|
|
|
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
|
|
|
|
### Deprecated: `<webview>.getWebContents()`
|
|
|
|
This API is implemented using the `remote` module, which has both performance
|
|
and security implications. Therefore its usage should be explicit.
|
|
|
|
```js
|
|
// Deprecated
|
|
webview.getWebContents()
|
|
// Replace with
|
|
const { remote } = require('electron')
|
|
remote.webContents.fromId(webview.getWebContentsId())
|
|
```
|
|
|
|
However, it is recommended to avoid using the `remote` module altogether.
|
|
|
|
```js
|
|
// main
|
|
const { ipcMain, webContents } = require('electron')
|
|
|
|
const getGuestForWebContents = (webContentsId, contents) => {
|
|
const guest = webContents.fromId(webContentsId)
|
|
if (!guest) {
|
|
throw new Error(`Invalid webContentsId: ${webContentsId}`)
|
|
}
|
|
if (guest.hostWebContents !== contents) {
|
|
throw new Error('Access denied to webContents')
|
|
}
|
|
return guest
|
|
}
|
|
|
|
ipcMain.handle('openDevTools', (event, webContentsId) => {
|
|
const guest = getGuestForWebContents(webContentsId, event.sender)
|
|
guest.openDevTools()
|
|
})
|
|
|
|
// renderer
|
|
const { ipcRenderer } = require('electron')
|
|
|
|
ipcRenderer.invoke('openDevTools', webview.getWebContentsId())
|
|
```
|
|
|
|
### Deprecated: `webFrame.setLayoutZoomLevelLimits()`
|
|
|
|
Chromium has removed support for changing the layout zoom level limits, and it
|
|
is beyond Electron's capacity to maintain it. The function will emit a warning
|
|
in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level
|
|
limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
|
|
[here](https://chromium.googlesource.com/chromium/src/+/938b37a6d2886bf8335fc7db792f1eb46c65b2ae/third_party/blink/common/page/page_zoom.cc#11).
|
|
|
|
### Deprecated events in `systemPreferences`
|
|
|
|
The following `systemPreferences` events have been deprecated:
|
|
|
|
* `inverted-color-scheme-changed`
|
|
* `high-contrast-color-scheme-changed`
|
|
|
|
Use the new `updated` event on the `nativeTheme` module instead.
|
|
|
|
```js
|
|
// Deprecated
|
|
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
|
|
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
|
|
|
|
// Replace with
|
|
nativeTheme.on('updated', () => { /* ... */ })
|
|
```
|
|
|
|
### Deprecated: methods in `systemPreferences`
|
|
|
|
The following `systemPreferences` methods have been deprecated:
|
|
|
|
* `systemPreferences.isDarkMode()`
|
|
* `systemPreferences.isInvertedColorScheme()`
|
|
* `systemPreferences.isHighContrastColorScheme()`
|
|
|
|
Use the following `nativeTheme` properties instead:
|
|
|
|
* `nativeTheme.shouldUseDarkColors`
|
|
* `nativeTheme.shouldUseInvertedColorScheme`
|
|
* `nativeTheme.shouldUseHighContrastColors`
|
|
|
|
```js
|
|
// Deprecated
|
|
systemPreferences.isDarkMode()
|
|
// Replace with
|
|
nativeTheme.shouldUseDarkColors
|
|
|
|
// Deprecated
|
|
systemPreferences.isInvertedColorScheme()
|
|
// Replace with
|
|
nativeTheme.shouldUseInvertedColorScheme
|
|
|
|
// Deprecated
|
|
systemPreferences.isHighContrastColorScheme()
|
|
// Replace with
|
|
nativeTheme.shouldUseHighContrastColors
|
|
```
|
|
|
|
## Planned Breaking API Changes (7.0)
|
|
|
|
### Deprecated: Atom.io Node Headers URL
|
|
|
|
This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url`
|
|
command line flag when building native Node modules. Both will be supported for
|
|
the foreseeable future but it is recommended that you switch.
|
|
|
|
Deprecated: https://atom.io/download/electron
|
|
|
|
Replace with: https://electronjs.org/headers
|
|
|
|
### API Changed: `session.clearAuthCache()` no longer accepts options
|
|
|
|
The `session.clearAuthCache` API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
|
|
|
|
```js
|
|
// Deprecated
|
|
session.clearAuthCache({ type: 'password' })
|
|
// Replace with
|
|
session.clearAuthCache()
|
|
```
|
|
|
|
### API Changed: `powerMonitor.querySystemIdleState` is now `powerMonitor.getSystemIdleState`
|
|
|
|
```js
|
|
// Removed in Electron 7.0
|
|
powerMonitor.querySystemIdleState(threshold, callback)
|
|
// Replace with synchronous API
|
|
const idleState = powerMonitor.getSystemIdleState(threshold)
|
|
```
|
|
|
|
### API Changed: `powerMonitor.querySystemIdleTime` is now `powerMonitor.getSystemIdleTime`
|
|
|
|
```js
|
|
// Removed in Electron 7.0
|
|
powerMonitor.querySystemIdleTime(callback)
|
|
// Replace with synchronous API
|
|
const idleTime = powerMonitor.getSystemIdleTime()
|
|
```
|
|
|
|
### API Changed: `webFrame.setIsolatedWorldInfo` replaces separate methods
|
|
|
|
```js
|
|
// Removed in Electron 7.0
|
|
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
|
|
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
|
|
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
|
|
// Replace with
|
|
webFrame.setIsolatedWorldInfo(
|
|
worldId,
|
|
{
|
|
securityOrigin: 'some_origin',
|
|
name: 'human_readable_name',
|
|
csp: 'content_security_policy'
|
|
})
|
|
```
|
|
|
|
### Removed: `marked` property on `getBlinkMemoryInfo`
|
|
|
|
This property was removed in Chromium 77, and as such is no longer available.
|
|
|
|
### Behavior Changed: `webkitdirectory` attribute for `<input type="file"/>` now lists directory contents
|
|
|
|
The `webkitdirectory` property on HTML file inputs allows them to select folders.
|
|
Previous versions of Electron had an incorrect implementation where the `event.target.files`
|
|
of the input returned a `FileList` that returned one `File` corresponding to the selected folder.
|
|
|
|
As of Electron 7, that `FileList` is now list of all files contained within
|
|
the folder, similarly to Chrome, Firefox, and Edge
|
|
([link to MDN docs](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory)).
|
|
|
|
As an illustration, take a folder with this structure:
|
|
|
|
```console
|
|
folder
|
|
├── file1
|
|
├── file2
|
|
└── file3
|
|
```
|
|
|
|
In Electron <=6, this would return a `FileList` with a `File` object for:
|
|
|
|
```console
|
|
path/to/folder
|
|
```
|
|
|
|
In Electron 7, this now returns a `FileList` with a `File` object for:
|
|
|
|
```console
|
|
/path/to/folder/file3
|
|
/path/to/folder/file2
|
|
/path/to/folder/file1
|
|
```
|
|
|
|
Note that `webkitdirectory` no longer exposes the path to the selected folder.
|
|
If you require the path to the selected folder rather than the folder contents,
|
|
see the `dialog.showOpenDialog` API ([link](api/dialog.md#dialogshowopendialogbrowserwindow-options)).
|
|
|
|
### API Changed: Callback-based versions of promisified APIs
|
|
|
|
Electron 5 and Electron 6 introduced Promise-based versions of existing
|
|
asynchronous APIs and deprecated their older, callback-based counterparts.
|
|
In Electron 7, all deprecated callback-based APIs are now removed.
|
|
|
|
These functions now only return Promises:
|
|
|
|
* `app.getFileIcon()` [#15742](https://github.com/electron/electron/pull/15742)
|
|
* `app.dock.show()` [#16904](https://github.com/electron/electron/pull/16904)
|
|
* `contentTracing.getCategories()` [#16583](https://github.com/electron/electron/pull/16583)
|
|
* `contentTracing.getTraceBufferUsage()` [#16600](https://github.com/electron/electron/pull/16600)
|
|
* `contentTracing.startRecording()` [#16584](https://github.com/electron/electron/pull/16584)
|
|
* `contentTracing.stopRecording()` [#16584](https://github.com/electron/electron/pull/16584)
|
|
* `contents.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312)
|
|
* `cookies.flushStore()` [#16464](https://github.com/electron/electron/pull/16464)
|
|
* `cookies.get()` [#16464](https://github.com/electron/electron/pull/16464)
|
|
* `cookies.remove()` [#16464](https://github.com/electron/electron/pull/16464)
|
|
* `cookies.set()` [#16464](https://github.com/electron/electron/pull/16464)
|
|
* `debugger.sendCommand()` [#16861](https://github.com/electron/electron/pull/16861)
|
|
* `dialog.showCertificateTrustDialog()` [#17181](https://github.com/electron/electron/pull/17181)
|
|
* `inAppPurchase.getProducts()` [#17355](https://github.com/electron/electron/pull/17355)
|
|
* `inAppPurchase.purchaseProduct()`[#17355](https://github.com/electron/electron/pull/17355)
|
|
* `netLog.stopLogging()` [#16862](https://github.com/electron/electron/pull/16862)
|
|
* `session.clearAuthCache()` [#17259](https://github.com/electron/electron/pull/17259)
|
|
* `session.clearCache()` [#17185](https://github.com/electron/electron/pull/17185)
|
|
* `session.clearHostResolverCache()` [#17229](https://github.com/electron/electron/pull/17229)
|
|
* `session.clearStorageData()` [#17249](https://github.com/electron/electron/pull/17249)
|
|
* `session.getBlobData()` [#17303](https://github.com/electron/electron/pull/17303)
|
|
* `session.getCacheSize()` [#17185](https://github.com/electron/electron/pull/17185)
|
|
* `session.resolveProxy()` [#17222](https://github.com/electron/electron/pull/17222)
|
|
* `session.setProxy()` [#17222](https://github.com/electron/electron/pull/17222)
|
|
* `shell.openExternal()` [#16176](https://github.com/electron/electron/pull/16176)
|
|
* `webContents.loadFile()` [#15855](https://github.com/electron/electron/pull/15855)
|
|
* `webContents.loadURL()` [#15855](https://github.com/electron/electron/pull/15855)
|
|
* `webContents.hasServiceWorker()` [#16535](https://github.com/electron/electron/pull/16535)
|
|
* `webContents.printToPDF()` [#16795](https://github.com/electron/electron/pull/16795)
|
|
* `webContents.savePage()` [#16742](https://github.com/electron/electron/pull/16742)
|
|
* `webFrame.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312)
|
|
* `webFrame.executeJavaScriptInIsolatedWorld()` [#17312](https://github.com/electron/electron/pull/17312)
|
|
* `webviewTag.executeJavaScript()` [#17312](https://github.com/electron/electron/pull/17312)
|
|
* `win.capturePage()` [#15743](https://github.com/electron/electron/pull/15743)
|
|
|
|
These functions now have two forms, synchronous and Promise-based asynchronous:
|
|
|
|
* `dialog.showMessageBox()`/`dialog.showMessageBoxSync()` [#17298](https://github.com/electron/electron/pull/17298)
|
|
* `dialog.showOpenDialog()`/`dialog.showOpenDialogSync()` [#16973](https://github.com/electron/electron/pull/16973)
|
|
* `dialog.showSaveDialog()`/`dialog.showSaveDialogSync()` [#17054](https://github.com/electron/electron/pull/17054)
|
|
|
|
## Planned Breaking API Changes (6.0)
|
|
|
|
### API Changed: `win.setMenu(null)` is now `win.removeMenu()`
|
|
|
|
```js
|
|
// Deprecated
|
|
win.setMenu(null)
|
|
// Replace with
|
|
win.removeMenu()
|
|
```
|
|
|
|
### API Changed: `electron.screen` in the renderer process should be accessed via `remote`
|
|
|
|
```js
|
|
// Deprecated
|
|
require('electron').screen
|
|
// Replace with
|
|
require('electron').remote.screen
|
|
```
|
|
|
|
### API Changed: `require()`ing node builtins in sandboxed renderers no longer implicitly loads the `remote` version
|
|
|
|
```js
|
|
// Deprecated
|
|
require('child_process')
|
|
// Replace with
|
|
require('electron').remote.require('child_process')
|
|
|
|
// Deprecated
|
|
require('fs')
|
|
// Replace with
|
|
require('electron').remote.require('fs')
|
|
|
|
// Deprecated
|
|
require('os')
|
|
// Replace with
|
|
require('electron').remote.require('os')
|
|
|
|
// Deprecated
|
|
require('path')
|
|
// Replace with
|
|
require('electron').remote.require('path')
|
|
```
|
|
|
|
### Deprecated: `powerMonitor.querySystemIdleState` replaced with `powerMonitor.getSystemIdleState`
|
|
|
|
```js
|
|
// Deprecated
|
|
powerMonitor.querySystemIdleState(threshold, callback)
|
|
// Replace with synchronous API
|
|
const idleState = powerMonitor.getSystemIdleState(threshold)
|
|
```
|
|
|
|
### Deprecated: `powerMonitor.querySystemIdleTime` replaced with `powerMonitor.getSystemIdleTime`
|
|
|
|
```js
|
|
// Deprecated
|
|
powerMonitor.querySystemIdleTime(callback)
|
|
// Replace with synchronous API
|
|
const idleTime = powerMonitor.getSystemIdleTime()
|
|
```
|
|
|
|
### Deprecated: `app.enableMixedSandbox()` is no longer needed
|
|
|
|
```js
|
|
// Deprecated
|
|
app.enableMixedSandbox()
|
|
```
|
|
|
|
Mixed-sandbox mode is now enabled by default.
|
|
|
|
### Deprecated: `Tray.setHighlightMode`
|
|
|
|
Under macOS Catalina our former Tray implementation breaks.
|
|
Apple's native substitute doesn't support changing the highlighting behavior.
|
|
|
|
```js
|
|
// Deprecated
|
|
tray.setHighlightMode(mode)
|
|
// API will be removed in v7.0 without replacement.
|
|
```
|
|
|
|
## Planned Breaking API Changes (5.0)
|
|
|
|
### Default Changed: `nodeIntegration` and `webviewTag` default to false, `contextIsolation` defaults to true
|
|
|
|
The following `webPreferences` option default values are deprecated in favor of the new defaults listed below.
|
|
|
|
| Property | Deprecated Default | New Default |
|
|
|----------|--------------------|-------------|
|
|
| `contextIsolation` | `false` | `true` |
|
|
| `nodeIntegration` | `true` | `false` |
|
|
| `webviewTag` | `nodeIntegration` if set else `true` | `false` |
|
|
|
|
E.g. Re-enabling the webviewTag
|
|
|
|
```js
|
|
const w = new BrowserWindow({
|
|
webPreferences: {
|
|
webviewTag: true
|
|
}
|
|
})
|
|
```
|
|
|
|
### Behavior Changed: `nodeIntegration` in child windows opened via `nativeWindowOpen`
|
|
|
|
Child windows opened with the `nativeWindowOpen` option will always have Node.js integration disabled, unless `nodeIntegrationInSubFrames` is `true`.
|
|
|
|
### API Changed: Registering privileged schemes must now be done before app ready
|
|
|
|
Renderer process APIs `webFrame.registerURLSchemeAsPrivileged` and `webFrame.registerURLSchemeAsBypassingCSP` as well as browser process API `protocol.registerStandardSchemes` have been removed.
|
|
A new API, `protocol.registerSchemesAsPrivileged` has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
|
|
|
|
### Deprecated: `webFrame.setIsolatedWorld*` replaced with `webFrame.setIsolatedWorldInfo`
|
|
|
|
```js
|
|
// Deprecated
|
|
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
|
|
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
|
|
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
|
|
// Replace with
|
|
webFrame.setIsolatedWorldInfo(
|
|
worldId,
|
|
{
|
|
securityOrigin: 'some_origin',
|
|
name: 'human_readable_name',
|
|
csp: 'content_security_policy'
|
|
})
|
|
```
|
|
|
|
### API Changed: `webFrame.setSpellCheckProvider` now takes an asynchronous callback
|
|
|
|
The `spellCheck` callback is now asynchronous, and `autoCorrectWord` parameter has been removed.
|
|
|
|
```js
|
|
// Deprecated
|
|
webFrame.setSpellCheckProvider('en-US', true, {
|
|
spellCheck: (text) => {
|
|
return !spellchecker.isMisspelled(text)
|
|
}
|
|
})
|
|
// Replace with
|
|
webFrame.setSpellCheckProvider('en-US', {
|
|
spellCheck: (words, callback) => {
|
|
callback(words.filter(text => spellchecker.isMisspelled(text)))
|
|
}
|
|
})
|
|
```
|
|
|
|
### API Changed: `webContents.getZoomLevel` and `webContents.getZoomFactor` are now synchronous
|
|
|
|
`webContents.getZoomLevel` and `webContents.getZoomFactor` no longer take callback parameters,
|
|
instead directly returning their number values.
|
|
|
|
```js
|
|
// Deprecated
|
|
webContents.getZoomLevel((level) => {
|
|
console.log(level)
|
|
})
|
|
// Replace with
|
|
const level = webContents.getZoomLevel()
|
|
console.log(level)
|
|
```
|
|
|
|
```js
|
|
// Deprecated
|
|
webContents.getZoomFactor((factor) => {
|
|
console.log(factor)
|
|
})
|
|
// Replace with
|
|
const factor = webContents.getZoomFactor()
|
|
console.log(factor)
|
|
```
|
|
|
|
## Planned Breaking API Changes (4.0)
|
|
|
|
The following list includes the breaking API changes made in Electron 4.0.
|
|
|
|
### `app.makeSingleInstance`
|
|
|
|
```js
|
|
// Deprecated
|
|
app.makeSingleInstance((argv, cwd) => {
|
|
/* ... */
|
|
})
|
|
// Replace with
|
|
app.requestSingleInstanceLock()
|
|
app.on('second-instance', (event, argv, cwd) => {
|
|
/* ... */
|
|
})
|
|
```
|
|
|
|
### `app.releaseSingleInstance`
|
|
|
|
```js
|
|
// Deprecated
|
|
app.releaseSingleInstance()
|
|
// Replace with
|
|
app.releaseSingleInstanceLock()
|
|
```
|
|
|
|
### `app.getGPUInfo`
|
|
|
|
```js
|
|
app.getGPUInfo('complete')
|
|
// Now behaves the same with `basic` on macOS
|
|
app.getGPUInfo('basic')
|
|
```
|
|
|
|
### `win_delay_load_hook`
|
|
|
|
When building native modules for windows, the `win_delay_load_hook` variable in
|
|
the module's `binding.gyp` must be true (which is the default). If this hook is
|
|
not present, then the native module will fail to load on Windows, with an error
|
|
message like `Cannot find module`. See the [native module
|
|
guide](./tutorial/using-native-node-modules.md) for more.
|
|
|
|
### Removed: IA32 Linux support
|
|
|
|
Electron 18 will no longer run on 32-bit Linux systems. See [discontinuing support for 32-bit Linux](https://www.electronjs.org/blog/linux-32bit-support) for more information.
|
|
|
|
## Breaking API Changes (3.0)
|
|
|
|
The following list includes the breaking API changes in Electron 3.0.
|
|
|
|
### `app`
|
|
|
|
```js
|
|
// Deprecated
|
|
app.getAppMemoryInfo()
|
|
// Replace with
|
|
app.getAppMetrics()
|
|
|
|
// Deprecated
|
|
const metrics = app.getAppMetrics()
|
|
const { memory } = metrics[0] // Deprecated property
|
|
```
|
|
|
|
### `BrowserWindow`
|
|
|
|
```js
|
|
// Deprecated
|
|
const optionsA = { webPreferences: { blinkFeatures: '' } }
|
|
const windowA = new BrowserWindow(optionsA)
|
|
// Replace with
|
|
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
|
|
const windowB = new BrowserWindow(optionsB)
|
|
|
|
// Deprecated
|
|
window.on('app-command', (e, cmd) => {
|
|
if (cmd === 'media-play_pause') {
|
|
// do something
|
|
}
|
|
})
|
|
// Replace with
|
|
window.on('app-command', (e, cmd) => {
|
|
if (cmd === 'media-play-pause') {
|
|
// do something
|
|
}
|
|
})
|
|
```
|
|
|
|
### `clipboard`
|
|
|
|
```js
|
|
// Deprecated
|
|
clipboard.readRtf()
|
|
// Replace with
|
|
clipboard.readRTF()
|
|
|
|
// Deprecated
|
|
clipboard.writeRtf()
|
|
// Replace with
|
|
clipboard.writeRTF()
|
|
|
|
// Deprecated
|
|
clipboard.readHtml()
|
|
// Replace with
|
|
clipboard.readHTML()
|
|
|
|
// Deprecated
|
|
clipboard.writeHtml()
|
|
// Replace with
|
|
clipboard.writeHTML()
|
|
```
|
|
|
|
### `crashReporter`
|
|
|
|
```js
|
|
// Deprecated
|
|
crashReporter.start({
|
|
companyName: 'Crashly',
|
|
submitURL: 'https://crash.server.com',
|
|
autoSubmit: true
|
|
})
|
|
// Replace with
|
|
crashReporter.start({
|
|
companyName: 'Crashly',
|
|
submitURL: 'https://crash.server.com',
|
|
uploadToServer: true
|
|
})
|
|
```
|
|
|
|
### `nativeImage`
|
|
|
|
```js
|
|
// Deprecated
|
|
nativeImage.createFromBuffer(buffer, 1.0)
|
|
// Replace with
|
|
nativeImage.createFromBuffer(buffer, {
|
|
scaleFactor: 1.0
|
|
})
|
|
```
|
|
|
|
### `process`
|
|
|
|
```js
|
|
// Deprecated
|
|
const info = process.getProcessMemoryInfo()
|
|
```
|
|
|
|
### `screen`
|
|
|
|
```js
|
|
// Deprecated
|
|
screen.getMenuBarHeight()
|
|
// Replace with
|
|
screen.getPrimaryDisplay().workArea
|
|
```
|
|
|
|
### `session`
|
|
|
|
```js
|
|
// Deprecated
|
|
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
|
|
callback(true)
|
|
})
|
|
// Replace with
|
|
ses.setCertificateVerifyProc((request, callback) => {
|
|
callback(0)
|
|
})
|
|
```
|
|
|
|
### `Tray`
|
|
|
|
```js
|
|
// Deprecated
|
|
tray.setHighlightMode(true)
|
|
// Replace with
|
|
tray.setHighlightMode('on')
|
|
|
|
// Deprecated
|
|
tray.setHighlightMode(false)
|
|
// Replace with
|
|
tray.setHighlightMode('off')
|
|
```
|
|
|
|
### `webContents`
|
|
|
|
```js
|
|
// Deprecated
|
|
webContents.openDevTools({ detach: true })
|
|
// Replace with
|
|
webContents.openDevTools({ mode: 'detach' })
|
|
|
|
// Removed
|
|
webContents.setSize(options)
|
|
// There is no replacement for this API
|
|
```
|
|
|
|
### `webFrame`
|
|
|
|
```js
|
|
// Deprecated
|
|
webFrame.registerURLSchemeAsSecure('app')
|
|
// Replace with
|
|
protocol.registerStandardSchemes(['app'], { secure: true })
|
|
|
|
// Deprecated
|
|
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
|
|
// Replace with
|
|
protocol.registerStandardSchemes(['app'], { secure: true })
|
|
```
|
|
|
|
### `<webview>`
|
|
|
|
```js
|
|
// Removed
|
|
webview.setAttribute('disableguestresize', '')
|
|
// There is no replacement for this API
|
|
|
|
// Removed
|
|
webview.setAttribute('guestinstance', instanceId)
|
|
// There is no replacement for this API
|
|
|
|
// Keyboard listeners no longer work on webview tag
|
|
webview.onkeydown = () => { /* handler */ }
|
|
webview.onkeyup = () => { /* handler */ }
|
|
```
|
|
|
|
### Node Headers URL
|
|
|
|
This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url`
|
|
command line flag when building native Node modules.
|
|
|
|
Deprecated: https://atom.io/download/atom-shell
|
|
|
|
Replace with: https://atom.io/download/electron
|
|
|
|
## Breaking API Changes (2.0)
|
|
|
|
The following list includes the breaking API changes made in Electron 2.0.
|
|
|
|
### `BrowserWindow`
|
|
|
|
```js
|
|
// Deprecated
|
|
const optionsA = { titleBarStyle: 'hidden-inset' }
|
|
const windowA = new BrowserWindow(optionsA)
|
|
// Replace with
|
|
const optionsB = { titleBarStyle: 'hiddenInset' }
|
|
const windowB = new BrowserWindow(optionsB)
|
|
```
|
|
|
|
### `menu`
|
|
|
|
```js
|
|
// Removed
|
|
menu.popup(browserWindow, 100, 200, 2)
|
|
// Replaced with
|
|
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })
|
|
```
|
|
|
|
### `nativeImage`
|
|
|
|
```js
|
|
// Removed
|
|
nativeImage.toPng()
|
|
// Replaced with
|
|
nativeImage.toPNG()
|
|
|
|
// Removed
|
|
nativeImage.toJpeg()
|
|
// Replaced with
|
|
nativeImage.toJPEG()
|
|
```
|
|
|
|
### `process`
|
|
|
|
* `process.versions.electron` and `process.version.chrome` will be made
|
|
read-only properties for consistency with the other `process.versions`
|
|
properties set by Node.
|
|
|
|
### `webContents`
|
|
|
|
```js
|
|
// Removed
|
|
webContents.setZoomLevelLimits(1, 2)
|
|
// Replaced with
|
|
webContents.setVisualZoomLevelLimits(1, 2)
|
|
```
|
|
|
|
### `webFrame`
|
|
|
|
```js
|
|
// Removed
|
|
webFrame.setZoomLevelLimits(1, 2)
|
|
// Replaced with
|
|
webFrame.setVisualZoomLevelLimits(1, 2)
|
|
```
|
|
|
|
### `<webview>`
|
|
|
|
```js
|
|
// Removed
|
|
webview.setZoomLevelLimits(1, 2)
|
|
// Replaced with
|
|
webview.setVisualZoomLevelLimits(1, 2)
|
|
```
|
|
|
|
### Duplicate ARM Assets
|
|
|
|
Each Electron release includes two identical ARM builds with slightly different
|
|
filenames, like `electron-v1.7.3-linux-arm.zip` and
|
|
`electron-v1.7.3-linux-armv7l.zip`. The asset with the `v7l` prefix was added
|
|
to clarify to users which ARM version it supports, and to disambiguate it from
|
|
future armv6l and arm64 assets that may be produced.
|
|
|
|
The file _without the prefix_ is still being published to avoid breaking any
|
|
setups that may be consuming it. Starting at 2.0, the unprefixed file will
|
|
no longer be published.
|
|
|
|
For details, see
|
|
[6986](https://github.com/electron/electron/pull/6986)
|
|
and
|
|
[7189](https://github.com/electron/electron/pull/7189).
|