docs: categorize breaking changes (#22834)
Co-authored-by: John Kleinschmidt <jkleinsc@github.com>
This commit is contained in:
Jeremy Apthorp
GitHub
parent
e73d5e3db5
commit
b1f4ac00f0
1 changed files with 45 additions and 38 deletions
|
|
@ -2,13 +2,19 @@
|
|||
|
||||
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.
|
||||
|
||||
## `FIXME` comments
|
||||
### Types of Breaking Changes
|
||||
|
||||
The `FIXME` string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme
|
||||
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 (10.0)
|
||||
|
||||
### Browser Window Affinity
|
||||
### 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 Chromiums process model for security,
|
||||
|
|
@ -16,7 +22,7 @@ performance and maintainability.
|
|||
|
||||
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
|
||||
|
||||
### `enableRemoteModule` defaults to `false`
|
||||
### 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
|
||||
|
|
@ -36,7 +42,7 @@ module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-
|
|||
|
||||
## Planned Breaking API Changes (9.0)
|
||||
|
||||
### Loading non-context-aware native modules in the renderer process
|
||||
### 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
|
||||
|
|
@ -48,7 +54,7 @@ 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).
|
||||
|
||||
### `<webview>.getWebContents()`
|
||||
### Removed: `<webview>.getWebContents()`
|
||||
|
||||
This API, which was deprecated in Electron 8.0, is now removed.
|
||||
|
||||
|
|
@ -60,7 +66,7 @@ const { remote } = require('electron')
|
|||
remote.webContents.fromId(webview.getWebContentsId())
|
||||
```
|
||||
|
||||
### `webFrame.setLayoutZoomLevelLimits()`
|
||||
### 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
|
||||
|
|
@ -68,7 +74,7 @@ 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).
|
||||
|
||||
### Sending non-JS objects over IPC now throws an exception
|
||||
### 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
|
||||
|
|
@ -84,14 +90,14 @@ 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.
|
||||
|
||||
### `shell.openItem` --> `shell.openPath`
|
||||
### 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/master/wg-api/spec-documents/shell-openitem.md).
|
||||
|
||||
## Planned Breaking API Changes (8.0)
|
||||
|
||||
### Values sent over IPC are now serialized with Structured Clone Algorithm
|
||||
### 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
|
||||
|
|
@ -142,7 +148,7 @@ 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
|
||||
|
||||
### `<webview>.getWebContents()`
|
||||
### Deprecated: `<webview>.getWebContents()`
|
||||
|
||||
This API is implemented using the `remote` module, which has both performance
|
||||
and security implications. Therefore its usage should be explicit.
|
||||
|
|
@ -183,7 +189,7 @@ const { ipcRenderer } = require('electron')
|
|||
ipcRenderer.invoke('openDevTools', webview.getWebContentsId())
|
||||
```
|
||||
|
||||
### `webFrame.setLayoutZoomLevelLimits()`
|
||||
### 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
|
||||
|
|
@ -193,7 +199,7 @@ limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
|
|||
|
||||
## Planned Breaking API Changes (7.0)
|
||||
|
||||
### Node Headers URL
|
||||
### 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
|
||||
|
|
@ -203,7 +209,7 @@ Deprecated: https://atom.io/download/electron
|
|||
|
||||
Replace with: https://electronjs.org/headers
|
||||
|
||||
### `session.clearAuthCache(options)`
|
||||
### 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.
|
||||
|
||||
|
|
@ -214,25 +220,25 @@ session.clearAuthCache({ type: 'password' })
|
|||
session.clearAuthCache()
|
||||
```
|
||||
|
||||
### `powerMonitor.querySystemIdleState`
|
||||
### API Changed: `powerMonitor.querySystemIdleState` is now `powerMonitor.getSystemIdleState`
|
||||
|
||||
```js
|
||||
// Removed in Electron 7.0
|
||||
powerMonitor.querySystemIdleState(threshold, callback)
|
||||
// Replace with synchronous API
|
||||
const idleState = getSystemIdleState(threshold)
|
||||
const idleState = powerMonitor.getSystemIdleState(threshold)
|
||||
```
|
||||
|
||||
### `powerMonitor.querySystemIdleTime`
|
||||
### API Changed: `powerMonitor.querySystemIdleTime` is now `powerMonitor.getSystemIdleState`
|
||||
|
||||
```js
|
||||
// Removed in Electron 7.0
|
||||
powerMonitor.querySystemIdleTime(callback)
|
||||
// Replace with synchronous API
|
||||
const idleTime = getSystemIdleTime()
|
||||
const idleTime = powerMonitor.getSystemIdleTime()
|
||||
```
|
||||
|
||||
### webFrame Isolated World APIs
|
||||
### API Changed: `webFrame.setIsolatedWorldInfo` replaces separate methods
|
||||
|
||||
```js
|
||||
// Removed in Electron 7.0
|
||||
|
|
@ -249,11 +255,11 @@ webFrame.setIsolatedWorldInfo(
|
|||
})
|
||||
```
|
||||
|
||||
### Removal of deprecated `marked` property on getBlinkMemoryInfo
|
||||
### Removed: `marked` property on `getBlinkMemoryInfo`
|
||||
|
||||
This property was removed in Chromium 77, and as such is no longer available.
|
||||
|
||||
### `webkitdirectory` attribute for `<input type="file"/>`
|
||||
### 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`
|
||||
|
|
@ -286,9 +292,10 @@ In Electron 7, this now returns a `FileList` with a `File` object for:
|
|||
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](https://github.com/electron/electron/blob/master/docs/api/dialog.md#dialogshowopendialogbrowserwindow-options)).
|
||||
|
||||
## Planned Breaking API Changes (6.0)
|
||||
|
||||
### `win.setMenu(null)`
|
||||
### API Changed: `win.setMenu(null)` is now `win.removeMenu()`
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -297,7 +304,7 @@ win.setMenu(null)
|
|||
win.removeMenu()
|
||||
```
|
||||
|
||||
### `contentTracing.getTraceBufferUsage()`
|
||||
### API Changed: `contentTracing.getTraceBufferUsage()` is now a promise
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -310,7 +317,7 @@ contentTracing.getTraceBufferUsage().then(infoObject => {
|
|||
})
|
||||
```
|
||||
|
||||
### `electron.screen` in renderer process
|
||||
### API Changed: `electron.screen` in the renderer process should be accessed via `remote`
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -319,7 +326,7 @@ require('electron').screen
|
|||
require('electron').remote.screen
|
||||
```
|
||||
|
||||
### `require` in sandboxed renderers
|
||||
### API Changed: `require()`ing node builtins in sandboxed renderers no longer implicitly loads the `remote` version
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -343,25 +350,25 @@ require('path')
|
|||
require('electron').remote.require('path')
|
||||
```
|
||||
|
||||
### `powerMonitor.querySystemIdleState`
|
||||
### Deprecated: `powerMonitor.querySystemIdleState` replaced with `powerMonitor.getSystemIdleState`
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
powerMonitor.querySystemIdleState(threshold, callback)
|
||||
// Replace with synchronous API
|
||||
const idleState = getSystemIdleState(threshold)
|
||||
const idleState = powerMonitor.getSystemIdleState(threshold)
|
||||
```
|
||||
|
||||
### `powerMonitor.querySystemIdleTime`
|
||||
### Deprecated: `powerMonitor.querySystemIdleTime` replaced with `powerMonitor.getSystemIdleTime`
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
powerMonitor.querySystemIdleTime(callback)
|
||||
// Replace with synchronous API
|
||||
const idleTime = getSystemIdleTime()
|
||||
const idleTime = powerMonitor.getSystemIdleTime()
|
||||
```
|
||||
|
||||
### `app.enableMixedSandbox`
|
||||
### Deprecated: `app.enableMixedSandbox()` is no longer needed
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -370,7 +377,7 @@ app.enableMixedSandbox()
|
|||
|
||||
Mixed-sandbox mode is now enabled by default.
|
||||
|
||||
### `Tray`
|
||||
### Deprecated: `Tray.setHighlightMode`
|
||||
|
||||
Under macOS Catalina our former Tray implementation breaks.
|
||||
Apple's native substitute doesn't support changing the highlighting behavior.
|
||||
|
|
@ -383,7 +390,7 @@ tray.setHighlightMode(mode)
|
|||
|
||||
## Planned Breaking API Changes (5.0)
|
||||
|
||||
### `new BrowserWindow({ webPreferences })`
|
||||
### 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.
|
||||
|
||||
|
|
@ -403,16 +410,16 @@ const w = new BrowserWindow({
|
|||
})
|
||||
```
|
||||
|
||||
### `nativeWindowOpen`
|
||||
### 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.
|
||||
Child windows opened with the `nativeWindowOpen` option will always have Node.js integration disabled, unless `nodeIntegrationInSubFrames` is `true`.
|
||||
|
||||
### Privileged Schemes Registration
|
||||
### API Changed: Registering privileged schemes must now be done before app ready
|
||||
|
||||
Renderer process APIs `webFrame.setRegisterURLSchemeAsPrivileged` and `webFrame.registerURLSchemeAsBypassingCSP` as well as browser process API `protocol.registerStandardSchemes` have been removed.
|
||||
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.
|
||||
|
||||
### webFrame Isolated World APIs
|
||||
### Deprecated: `webFrame.setIsolatedWorld*` replaced with `webFrame.setIsolatedWorldInfo`
|
||||
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
@ -429,7 +436,7 @@ webFrame.setIsolatedWorldInfo(
|
|||
})
|
||||
```
|
||||
|
||||
## `webFrame.setSpellCheckProvider`
|
||||
### API Changed: `webFrame.setSpellCheckProvider` now takes an asynchronous callback
|
||||
The `spellCheck` callback is now asynchronous, and `autoCorrectWord` parameter has been removed.
|
||||
```js
|
||||
// Deprecated
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue