Breaking Changes
Breaking-Änderungen werden hier dokumentiert, und Veraltungswarnungen werden js-Code nach Möglichkeit hinzugefügt, mindestens eine Hauptversion, bevor die Änderung vorgenommen wird.
Typen von Breaking-Änderungen
In diesem Dokument wird die folgende Konvention zur Kategorisierung von Breaking-Änderungen verwendet:
- API geändert: Die API wurde so geändert, dass Code, der nicht aktualisiert wurde, garantiert eine Ausnahme wirft.
- Verhalten geändert: Das Verhalten von Electron hat sich geändert, aber nicht so, dass eine Ausnahme unbedingt geworfen wird.
- Standard geändert: Code, der vom alten Standardwert abhängig ist, funktioniert möglicherweise nicht mehr und wirft nicht notwendigerweise eine Ausnahme. Das alte Verhalten kann durch explizite Angabe des Wertes wiederhergestellt werden.
- Veraltet: Eine API wurde als veraltet markiert. Die API wird weiterhin funktionieren, sendet aber eine Veraltungswarnung aus und wird in einer zukünftigen Version entfernt.
- Entfernt: Eine API oder Funktion wurde entfernt und wird von Electron nicht mehr unterstützt.
Geplante Bruch-API-Änderungen (33.0)
Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all
APIs which provide access to a WebFrameMain
instance may return an instance with frame.detached
set to true
, or possibly return null
.
When a frame performs a cross-origin navigation, it enters into a detached state in which it's no longer attached to the page. In this state, it may be running unload handlers prior to being deleted. In the event of an IPC sent during this state, frame.detached
will be set to true
with the frame being destroyed shortly thereafter.
When receiving an event, it's important to access WebFrameMain properties immediately upon being received. Otherwise, it's not guaranteed to point to the same webpage as when received. To avoid misaligned expectations, Electron will return null
in the case of late access where the webpage has changed.
ipcMain.on('unload-event', (event) => {
event.senderFrame; // ✅ accessed immediately
});
ipcMain.on('unload-event', async (event) => {
await crossOriginNavigationPromise;
event.senderFrame; // ❌ returns `null` due to late access
});
Behavior Changed: custom protocol URL handling on Windows
Due to changes made in Chromium to support Non-Special Scheme URLs, custom protocol URLs that use Windows file paths will no longer work correctly with the deprecated protocol.registerFileProtocol
and the baseURLForDataURL
property on BrowserWindow.loadURL
, WebContents.loadURL
, and <webview>.loadURL
. protocol.handle
will also not work with these types of URLs but this is not a change since it has always worked that way.
// No longer works
protocol.registerFileProtocol('other', () => {
callback({ filePath: '/path/to/my/file' })
})
const mainWindow = new BrowserWindow()
mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://C:\\myapp' })
mainWindow.loadURL('other://C:\\myapp\\index.html')
// Replace with
const path = require('node:path')
const nodeUrl = require('node:url')
protocol.handle(other, (req) => {
const srcPath = 'C:\\myapp\\'
const reqURL = new URL(req.url)
return net.fetch(nodeUrl.pathToFileURL(path.join(srcPath, reqURL.pathname)).toString())
})
mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://' })
mainWindow.loadURL('other://index.html')
Behavior Changed: webContents
property on login
on app
The webContents
property in the login
event from app
will be null
when the event is triggered for requests from the utility process created with respondToAuthRequestsFromMainProcess
option.
Deprecated: textured
option in BrowserWindowConstructorOption.type
The textured
option of type
in BrowserWindowConstructorOptions
has been deprecated with no replacement. This option relied on the NSWindowStyleMaskTexturedBackground
style mask on macOS, which has been deprecated with no alternative.
Removed: macOS 10.15 support
macOS 10.15 (Catalina) is no longer supported by Chromium.
Older versions of Electron will continue to run on Catalina, but macOS 11 (Big Sur) or later will be required to run Electron v33.0.0 and higher.
Veraltet: systemPreferences.accessibilityDisplayShouldReduceTransparency
The systemPreferences.accessibilityDisplayShouldReduceTransparency
property is now deprecated in favor of the new nativeTheme.prefersReducedTransparency
, which provides identical information and works cross-platform.
// Deprecated
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency
// Replace with:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency
Geplante Bruch-API-Änderungen (32.0)
Removed: File.path
The nonstandard path
property of the Web File
object was added in an early version of Electron as a convenience method for working with native files when doing everything in the renderer was more common. However, it represents a deviation from the standard and poses a minor security risk as well, so beginning in Electron 32.0 it has been removed in favor of the webUtils.getPathForFile
method.
// Before (renderer)
const file = document.querySelector('input[type=file]').files[0]
alert(`Uploaded file path was: ${file.path}`)
// After (renderer)
const file = document.querySelector('input[type=file]').files[0]
electron.showFilePath(file)
// (preload)
const { contextBridge, webUtils } = require('electron')
contextBridge.exposeInMainWorld('electron', {
showFilePath (file) {
// It's best not to expose the full file path to the web content if
// possible.
const path = webUtils.getPathForFile(file)
alert(`Uploaded file path was: ${path}`)
}
})
Deprecated: clearHistory
, canGoBack
, goBack
, canGoForward
, goForward
, goToIndex
, canGoToOffset
, goToOffset
on WebContents
The navigation-related APIs are now deprecated.
These APIs have been moved to the navigationHistory
property of WebContents
to provide a more structured and intuitive interface for managing navigation history.
// Deprecated
win.webContents.clearHistory()
win.webContents.canGoBack()
win.webContents.goBack()
win.webContents.canGoForward()
win.webContents.goForward()
win.webContents.goToIndex(index)
win.webContents.canGoToOffset()
win.webContents.goToOffset(index)
// Replace with
win.webContents.navigationHistory.clear()
win.webContents.navigationHistory.canGoBack()
win.webContents.navigationHistory.goBack()
win.webContents.navigationHistory.canGoForward()
win.webContents.navigationHistory.goForward()
win.webContents.navigationHistory.canGoToOffset()
win.webContents.navigationHistory.goToOffset(index)
Geplante Bruch-API-Änderungen (31.0)
Removed: WebSQL
support
Chromium has removed support for WebSQL upstream, transitioning it to Android only. See Chromium's intent to remove discussion for more information.
Behavior Changed: nativeImage.toDataURL
will preserve PNG colorspace
PNG decoder implementation has been changed to preserve colorspace data, the encoded data returned from this function now matches it.
See crbug.com/332584706 for more information.
Behavior Changed: window.flashFrame(bool)
will flash dock icon continuously on macOS
This brings the behavior to parity with Windows and Linux. Prior behavior: The first flashFrame(true)
bounces the dock icon only once (using the NSInformationalRequest level) and flashFrame(false)
does nothing. New behavior: Flash continuously until flashFrame(false)
is called. This uses the NSCriticalRequest level instead. To explicitly use NSInformationalRequest
to cause a single dock icon bounce, it is still possible to use dock.bounce('informational')
.
Geplante Bruch-API-Änderungen (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 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.
Previously, the setAutoResize
function of the BrowserView
API was backed by autoresizing 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.
Deprecated: BrowserView
The BrowserView
class has been deprecated and replaced by the new WebContentsView
class.
BrowserView
related methods in BrowserWindow
have also been deprecated:
BrowserWindow.fromBrowserView(browserView)
win.setBrowserView(browserView)
win.getBrowserView()
win.addBrowserView(browserView)
win.removeBrowserView(browserView)
win.setTopBrowserView(browserView)
win.getBrowserViews()
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.
Entfernt: process.getIOCounters()
Chromium has removed access to this information.
Geplante Bruch-API-Änderungen (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:
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.
// 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.
// 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.
// Removed
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
Geplante Bruch-API-Änderungen (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.
Entfernt: 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.
// 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)
Entfernt: 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.
// Removed in Electron 28
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// Ersetzt durch
const ret = win.getWindowButtonPosition()
if (ret === null) {
// Keine benutzerdefinierte Position.
}
Entfernt: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been removed. It should be replaced by setting up a MessageChannel
between the renderers.
The senderId
and senderIsMainFrame
properties of IpcRendererEvent
have been removed as well.
Entfernt: app.runningUnderRosettaTranslation
The app.runningUnderRosettaTranslation
property has been removed. App.runningUnderARM64Translation
// 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.
// 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.
// 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.
// Deprecated
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
Geplante Bruch-API-Änderungen (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.
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.
Veraltet: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been deprecated. It should be replaced by setting up a MessageChannel
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.
// Removed
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replace with
nativeTheme.on('updated', () => { /* ... */ })
Entfernt: Einige window.setVibrancy
Optionen auf macOS
Die folgenden Lebendigkeitsoptionen wurden entfernt:
- 'light'
- 'medium-light'
- 'dark'
- 'ultra-dark'
- 'appearance-based'
Diese wurden zuvor als veraltet markiert und wurden von Apple in 10.15 entfernt.
Entfernt: webContents.getPrinters
The webContents.getPrinters
method has been removed. Verwende stattdessen webContents.getPrintersAsync
.
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. Verwenden Sie stattdessen das nativeTheme
Modul.
// 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. Verwenden Sie stattdessen selected-content-background
.
// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
Geplante Bruch-API-Änderungen (26.0)
Veraltet: webContents.getPrinters
Die webContents.getPrinters
Methode wurde veraltet. Verwende stattdessen webContents.getPrintersAsync
.
const w = new BrowserWindow({ show: false })
// Veraltet
console.log(w.webContents.getPrinters())
// Ersetzen mit
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
Veraltet: systemPreferences.{get,set}AppLevelAppearance
und systemPreferences.appLevelAppearance
Die systemPreferences.getAppLevelAppearance
und systemPreferences.setAppLevelAppearance
Methoden sowie die systemPreferences.appLevelAppearance
Eigenschaft wurden veraltet. Verwenden Sie stattdessen das nativeTheme
Modul.
// Veraltet
systemPreferences.getAppLevelAppearance()
// Ersetzt durch
nativeTheme.shouldUseDarkColors
// Veraltet
systemPreferences.appLevelAppearance
// Ersetzt durch
nativeTheme.shouldUseDarkColors
// Veraltet
systemPreferences.setAppLevelAppearance('dark')
// Ersetzt mit
nativeTheme.themeSource = 'dark'
Veraltet: alternate-selected-control-text
Wert für systemPreferences.getColor
Der alternate-selected-control-text
Wert für systemPreferences.getColor
wurde veraltet. Verwenden Sie stattdessen selected-content-background
.
// Veraltet
systemPreferences.getColor('alternate-selected-control-text')
// Ersetzt mit
systemPreferences.getColor('selected-content-background')
Geplante Bruch-API-Änderungen (25.0)
Deprecated: protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol
and protocol.isProtocol{Registered,Intercepted}
Die protocol.register*Protocol
und protocol.intercept*Protocol
Methoden wurden durch protocol.handle
ersetzt.
Die neue Methode kann entweder ein neues Protokoll registrieren oder ein bestehendes Protokoll abfangen, und Antworten können von jedem Typ sein.
// Veraltet in Electron 25
protocol.registerBufferProtocol('some-protocol', () => {
callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})
// Ersetzt mit
protocol.handle('some-protocol', () => {
return new Response(
Buffer.from('<h5>Response</h5>'), // Kann auch ein string oder ReadableStream sein.
{ headers: { 'content-type': 'text/html' } }
)
})
// Veraltet in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
callback({ url: 'https://electronjs.org' })
})
// Ersetzt mit
protocol.handle('some-protocol', () => {
return net.fetch('https://electronjs.org')
})
// Veraltet in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
callback({ filePath: '/pfad/zu/meiner/datei' })
})
// Ersetzt mit
protocol.handle('some-protocol', () => {
return net.fetch('/pfad/zu/meiner/datei' )
})
Veraltet: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position)
wurde veraltet, die BrowserWindow.setWindowButtonPosition(position)
API sollte stattdessen verwendet werden, die null
anstelle von { x: 0, y: 0 }
akzeptiert, um die Position auf Systemstandart zurückzusetzen.
// Veraltet in Electron 25
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })
// Ersetzt mit
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)
Veraltet: BrowserWindow.getTrafficLightPosition()
BrowserWindow.getTrafficLightPosition()
wurde veraltet, die BrowserWindow.getWindowButtonPosition()
API sollte stattdessen verwendet werden, die null
anstatt { x: 0, y: 0 }
zurückgibt, wenn keine benutzerdefinierte Position vorhanden ist.
// Veraltet in Electron 25
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// Keine benutzerdefinierte Position.
}
// Ersetzt durch
const ret = win.getWindowButtonPosition()
if (ret === null) {
// Keine benutzerdefinierte Position.
}
Geplante Bruch-API-Änderungen (24.0)
API geändert: 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.
Aktualisiertes Verhalten:
// 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 }
})
Vorheriges Verhalten (unter Windows):
// 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 }
})
Geplante Bruch-API-Änderungen (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 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. Electron follows the planned Chromium deprecation policy, which will deprecate Windows 7 support beginning in Chromium 109.
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 on WebContents.
// 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()
}
})
Entfernt: webContents.incrementCapturerCount(stayHidden, stayAwake)
The webContents.incrementCapturerCount(stayHidden, stayAwake)
function has been removed. Es wird nun automatisch von webContents.capturePage
bearbeitet, wenn eine Seitenerfassung abgeschlossen ist.
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())
})
Entfernt: webContents.decrementCapturerCount(stayHidden, stayAwake)
The webContents.decrementCapturerCount(stayHidden, stayAwake)
function has been removed. Es wird nun automatisch von webContents.capturePage
bearbeitet, wenn eine Seitenerfassung abgeschlossen ist.
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())
})
Geplante Bruch-API-Änderungen (22.0)
Veraltet: webContents.incrementCapturerCount(stayHidden, stayAwake)
webContents.incrementCapturerCount(stayHidden, stayAwake)
ist veraltet. Es wird nun automatisch von webContents.capturePage
bearbeitet, wenn eine Seitenerfassung abgeschlossen ist.
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())
})
Veraltet: webContents.decrementCapturerCount(stayHidden, stayAwake)
webContents.decrementCapturerCount(stayHidden, stayAwake)
ist veraltet. Es wird nun automatisch von webContents.capturePage
bearbeitet, wenn eine Seitenerfassung abgeschlossen ist.
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. Es wird durch webContents.setWindowOpenHandler()
ersetzt.
// 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. Es gibt keinen direkten Ersatz dafür.
// Entfernt in Electron 22
webview.addEventListener('new-window', (event) => {})
// 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 on WebContents.
// 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()
}
})
Geplante Bruch-API-Änderungen (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 for more details.
API Changed: webContents.printToPDF()
webContents.printToPDF()
has been modified to conform to Page.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
// 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)
})
Geplante Bruch-API-Änderungen (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.
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.
Entfernt: skipTaskbar
unter 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 geändert: 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
, but instead is passed the origin
, which is the origin that is checking for device permission.
Geplante Bruch-API-Änderungen (19.0)
Entfernt: IA32 Linux-Binärdateien
Dies ist das Ergebnis des Support-Endes Chromiums für IA32 Linux ab der Version 102.0.4999.0. Dies schließt die Entfernung der Unterstützung für IA32 Linux ab.
Geplante Bruch-API-Änderungen (18.0)
Entfernt: 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. Seit Electron 15 ist nativeWindowOpen
standardmäßig aktiviert.
See the documentation for window.open in Electron for more details.
Geplante Bruch-API-Änderungen (17.0)
Entfernt: desktopCapturer.getSources
im Renderer
Die API desktopCapturer.getSources
ist jetzt nur im Hauptprozess verfügbar. Dies wurde geändert, um die Standardsicherheit von Electron Apps zu verbessern.
Wenn Sie diese Funktion benötigen, kann sie wie folgt ersetzt werden:
// Main process
const { ipcMain, desktopCapturer } = require('electron')
ipcMain.handle(
'DESKTOP_CAPTURER_GET_SOURCES',
(event, opts) => desktopCapturer.getSources(opts)
)
// 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. Seit Electron 15 ist nativeWindowOpen
standardmäßig aktiviert.
See the documentation for window.open in Electron for more details.
Geplante Bruch-API-Änderungen (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 for details on how to replace this API in your app.
Geplante Bruch-API-Änderungen (15.0)
Standardwert geändert: nativeWindowOpen
ist standardmäßig auf true
eingestellt
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 for more details.
Veraltet: app.runningUnderRosettaTranslation
The app.runningUnderRosettaTranslation
property has been deprecated. App.runningUnderARM64Translation
// Veraltet
console.log(app.runningUnderRosettaTranslation)
// Ersetzen durch
console.log(app.runningUnderARM64Translation)
Geplante Bruch-API-Änderungen (14.0)
Entfernt: remote
Modul
The remote
module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote
module.
// Veraltet in Electron 12:
const { BrowserWindow } = require('electron').remote
// Ersetzen von:
sonst { BrowserWindow } = require('@electron/remote')
// Im Hauptprozess:
require('@electron/remote/main').initialize()
Entfernt: 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.
Weitere Informationen findest du unter #18397.
Entfernt: Browserfenster-Affinität
Die Einstellung Affinität
beim Erstellen eines neuen BrowserWindow
wird entfernt als Teil unseres Plans, sich stärker an das Prozessmodell von Chromium für Sicherheit, Leistung und Wartbarkeit anzupassen.
Weitere Informationen findest du unter #18397.
API geändert: window.open()
Der optionale Parameter FrameName
legt nicht mehr den Titel des Fensters fest. Dies folgt nun der Spezifikation, die in der nativen Dokumentation unter dem zugehörigen Parameter windowName
beschrieben wird.
If you were using this parameter to set the title of a window, you can instead use win.setTitle(title).
Entfernt: worldSafeExecuteJavaScript
In Electron 14 wird worldSafeExecuteJavaScript
entfernt. Es gibt keine Alternative, bitte stelle sicher, dass dein Code mit dieser Eigenschaft funktioniert. Es wurde standardmäßig aktiviert, da Electron
12.
Sie werden von dieser Änderung betroffen sein, wenn Sie entweder webFrame.executeJavaScript
oder webFrame.executeJavaScriptInIsolatedWorld
verwenden. You will need to ensure that values returned by either of those methods are supported by the Context Bridge API as these methods use the same value passing semantics.
Entfernt: BrowserWindowConstructorOptions, die von übergeordneten Fenstern geerbt werden
Vor Electron 14 würden Fenster, die mit window.open
geöffnet wurden, BrowserWindow Konstruktor Optionen wie transparent
und resizable
von ihrem Elternfenster erben. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.
Stattdessen explizit Optionen für das neue Fenster mit setWindowOpenHandler
setzen:
webContents.setWindowOpenHandler((details) => {
return {
action: 'allow',
overrideBrowserWindowOptions: {
// ...
}
}
})
Entfernt: additionalFeatures
Die veraltete additionalFeatures
Eigenschaft in den new-window
und did-create-window
Events von WebContent wurde entfernt. Da new-window
Positionsargumente verwendet, ist das Argument immer noch vorhanden, wird aber immer das leere Array []
sein. (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.
// Entfernt in Electron 14
// Ausgelöst von 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']) {
// ...
}
})
Geplante Bruch-API-Änderungen (13.0)
API geändert: session.setPermissionCheckHandler(handler)
Die Handler
Methoden ersten Parameters waren zuvor immer ein webContents
, es kann jetzt manchmal null
sein. Sie sollten die requestingOrigin
, einbettenOrigin
und securityOrigin
Eigenschaften verwenden, um auf die Berechtigungsprüfung korrekt zu reagieren. Da der Webcontent
null sein kann
nicht mehr auf ihn angewiesen werden.
// Alter Code
session.setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
return true
}
return false
})
// Ersetzen mit
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
return true
}
return false
})
Removed: shell.moveItemToTrash()
Die veraltete synchrone shell.moveItemToTrash()
API wurde entfernt. Verwende stattdessen die asynchrone shell.trashItem()
.
// Entfernt in Electron 13
shell.moveItemTosh(path)
// Ersetzen durch
shell.trashItem(path).then(/* ... */)
Entfernt: BrowserWindow
Erweiterungs-APIs
Die veralteten Erweiterungs-APIs wurden entfernt:
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()
// In Electron 13 entfernt
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Ersetzen durch
session.defaultSession.loadExtension(path)
// In Electron 13 entfernt
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Ersetzen durch
session.defaultSession.loadExtension(path)
// In Electron 13 entfernt
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Ersetzen durch
session.defaultSession.getAllExtensions()
Eliminado: métodos en systemPreferences
Die folgenden systemPreferences
Methoden wurden veraltet:
systemPreferences.isDarkMode()
systemPreferences.isInvertedColorScheme()
systemPreferences.isHighContrastColorScheme()
Verwende stattdessen die folgenden nativeTheme
Eigenschaften:
nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors
// Entfernt in Electron 13
systemPreferences.isDarkMode()
// Ersetzen durch
nativeTheme.shouldUseDarkColors
// Entfernt in Electron 13
systemPreferences. sInvertedColorScheme()
// Ersetzen durch
nativeTheme.shouldUseInvertedColorScheme
// In Electron 13 entfernt
systemPreferences.isHighContrastColorScheme()
// Ersetzen durch
nativeTheme.shouldUseHighContrastColorColorScheme
Veraltet: WebContents new-window
Ereignis
Das new-window
Ereignis von WebContents wurde veraltet. Es wird durch webContents.setWindowOpenHandler()
ersetzt.
// Veraltet in Electron 13
webContents.on('new-window', (event) => {
event. reventDefault()
})
// Ersetzen durch
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})
Geplante Bruch-API-Änderungen (12.0)
Entfernt: Pepper Flash Unterstützung
Chromium hat die Unterstützung für Flash entfernt, und deshalb müssen wir diesem Beispiel folgen. Weitere Details findest du in der Flash-Roadmap von Chromium.
Standardwert geändert: worldSafeExecuteJavaScript
ist standardmäßig auf true
eingestellt
In Electron 12, worldSafeExecuteJavaScript
wird standardmäßig aktiviert. Um das vorherige Verhalten wiederherzustellen, muss worldSafeExecuteJavaScript: false
in WebPreferences angegeben werden. Bitte beachte, dass die Einstellung dieser Option auf false
unsicher ist.
Diese Einstellung wird in Electron 14 entfernt, also migriere bitte deinen Code um den Standardwert zu unterstützen.
Default Changed: contextIsolation
defaults to true
In Electron 12, contextIsolation
wird standardmäßig aktiviert. Um das vorherige Verhalten wiederherzustellen, muss contextIsolation: false
in WebPreferences angegeben werden.
We recommend having contextIsolation enabled 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
Entfernt: crashReporter.getCrashesDirectory()
The crashReporter.getCrashesDirectory
method has been removed. Usage should be replaced by app.getPath('crashDumps')
.
// 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 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
module.
// Veraltet in Electron 12:
const { BrowserWindow } = require('electron').remote
// Ersetzen von:
sonst { BrowserWindow } = require('@electron/remote')
// Im Hauptprozess:
require('@electron/remote/main').initialize()
Veraltet: shell.moveItemToTrash()
The synchronous shell.moveItemToTrash()
has been replaced by the new, asynchronous shell.trashItem()
.
// Deprecated in Electron 12
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)
Geplante Bruch-API-Änderungen (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.
Geplante Bruch-API-Änderungen (10.0)
Veraltet: companyName
Argument, um crashReporter.start()
The companyName
argument to crashReporter.start()
, which was previously required, is now optional, and further, is deprecated. Um das gleiche Verhalten auf nicht veraltete Weise zu erhalten, können Sie einen companyName
Wert in globalExtra
übergeben.
// Deprecated in Electron 10
crashReporter.start({ companyName: 'Umbrella Corporation' })
// Replace with
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })
Veraltet: crashReporter.getCrashesDirectory()
Die crashReporter.getCrashesDirectory
Methode wurde veraltet. Usage should be replaced by app.getPath('crashDumps')
.
// 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 for more details.
Veraltet: 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.
Standardwert geändert: enableRemoteModule
ist standardmäßig auf false
eingestellt
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:
const w = new BrowserWindow({
webPreferences: {
enableRemoteModule: true
}
})
We recommend moving away from the remote module.
protocol.unregisterProtocol
protocol.uninterceptProtocol
Diese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.
// 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
Diese Schnittstelle ist jetzt Synchron und der optionale callback wird nicht länger gebraucht.
// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
protocol.registerFileProtocol(scheme, handler)
Das registrierte oder abgefangene Protokoll hat keine Auswirkungen auf die aktuelle Seite, bis eine Navigation stattfindet.
protocol.isProtocolHandled
Diese Schnittstelle ist veraltet anstatt dessen sollten Benutzer protocol.isProtocolRegistered
und protocol.isProtocolIntercepted
nutzen.
// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)
Geplante Bruch-API-Änderungen (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.
Weitere Informationen findest du unter #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()
// Deprecated in Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)
// Deprecated in Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)
// Deprecated in Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()
Removed: <webview>.getWebContents()
Diese API, die seit Electron 8.0 veraltet ist, wird nun entfernt.
// Removed in Electron 9.0
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())
Entfernt: webFrame.setLayoutZoomLevelLimits()
Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. 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.
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.
Geplante Bruch-API-Änderungen (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, 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
.
// 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 tonull
.- Objects containing cyclic references will now be correctly serialized, instead of being converted to
null
. Set
,Map
,Error
andRegExp
values will be correctly serialized, instead of being converted to{}
.BigInt
values will be correctly serialized, instead of being converted tonull
.- Sparse arrays will be serialized as such, instead of being converted to dense arrays with
null
s. Date
objects will be transferred asDate
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.jsBuffer
. - Node.js
Buffer
objects will be transferred asUint8Array
s. You can convert aUint8Array
back to a Node.jsBuffer
by wrapping the underlyingArrayBuffer
:
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.
Veraltet: <webview>.getWebContents()
This API is implemented using the remote
module, which has both performance and security implications. Therefore its usage should be explicit.
// 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.
// 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())
Veraltet: webFrame.setLayoutZoomLevelLimits()
Chromium hat die Unterstützung für das Ändern des Layout-Zoomniveaus entfernt und es übersteigt die Möglichkeiten von uns, dies zu pflegen. 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.
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.
// Deprecated
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replace with
nativeTheme.on('updated', () => { /* ... */ })
Deprecated: methods in systemPreferences
Die folgenden systemPreferences
Methoden wurden veraltet:
systemPreferences.isDarkMode()
systemPreferences.isInvertedColorScheme()
systemPreferences.isHighContrastColorScheme()
Verwende stattdessen die folgenden nativeTheme
Eigenschaften:
nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors
// Deprecated
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme
// Deprecated
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors
Geplante Bruch-API-Änderungen (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.
// Deprecated
session.clearAuthCache({ type: 'password' })
// Replace with
session.clearAuthCache()
API Changed: powerMonitor.querySystemIdleState
is now powerMonitor.getSystemIdleState
// 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
// Removed in Electron 7.0
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()
API Changed: webFrame.setIsolatedWorldInfo
replaces separate methods
// 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).
As an illustration, take a folder with this structure:
folder
├── file1
├── file2
└── file3
In Electron <=6, this would return a FileList
with a File
object for:
path/to/folder
In Electron 7, this now returns a FileList
with a File
object for:
/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 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()
#15742app.dock.show()
#16904contentTracing.getCategories()
#16583contentTracing.getTraceBufferUsage()
#16600contentTracing.startRecording()
#16584contentTracing.stopRecording()
#16584contents.executeJavaScript()
#17312cookies.flushStore()
#16464cookies.get()
#16464cookies.remove()
#16464cookies.set()
#16464debugger.sendCommand()
#16861dialog.showCertificateTrustDialog()
#17181inAppPurchase.getProducts()
#17355inAppPurchase.purchaseProduct()
#17355netLog.stopLogging()
#16862session.clearAuthCache()
#17259session.clearCache()
#17185session.clearHostResolverCache()
#17229session.clearStorageData()
#17249session.getBlobData()
#17303session.getCacheSize()
#17185session.resolveProxy()
#17222session.setProxy()
#17222shell.openExternal()
#16176webContents.loadFile()
#15855webContents.loadURL()
#15855webContents.hasServiceWorker()
#16535webContents.printToPDF()
#16795webContents.savePage()
#16742webFrame.executeJavaScript()
#17312webFrame.executeJavaScriptInIsolatedWorld()
#17312webviewTag.executeJavaScript()
#17312win.capturePage()
#15743
These functions now have two forms, synchronous and Promise-based asynchronous:
dialog.showMessageBox()
/dialog.showMessageBoxSync()
#17298dialog.showOpenDialog()
/dialog.showOpenDialogSync()
#16973dialog.showSaveDialog()
/dialog.showSaveDialogSync()
#17054
Geplante Bruch-API-Änderungen (6.0)
API Changed: win.setMenu(null)
is now win.removeMenu()
// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()
API Changed: electron.screen
in the renderer process should be accessed via remote
// 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
// 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
// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)
Deprecated: powerMonitor.querySystemIdleTime
replaced with powerMonitor.getSystemIdleTime
// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()
Deprecated: app.enableMixedSandbox()
is no longer needed
// Deprecated
app.enableMixedSandbox()
Mixed-sandbox mode is now enabled by default.
Veraltet: Tray.setHighlightMode
Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.
Geplante Bruch-API-Änderungen (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 |
z.B. Re-enabling the webviewTag
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
// 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.
// 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.
// Deprecated
webContents.getZoomLevel((level) => {
console.log(level)
})
// Replace with
const level = webContents.getZoomLevel()
console.log(level)
// Deprecated
webContents.getZoomFactor((factor) => {
console.log(factor)
})
// Replace with
const factor = webContents.getZoomFactor()
console.log(factor)
Geplante Bruch-API-Änderungen (4.0)
The following list includes the breaking API changes made in Electron 4.0.
app.makeSingleInstance
// Deprecated
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})
app.releaseSingleInstance
// Veraltet
app.releaseSingleInstance()
// Ersetze mit
app.releaseSingleInstanceLock()
app.getGPUInfo
app.getGPUInfo('complete')
// Verhält sich jetzt gleich wie `basic` auf 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 for more.
Removed: IA32 Linux support
Electron 18 will no longer run on 32-bit Linux systems. See discontinuing support for 32-bit Linux for more information.
Breaking API Changes (3.0)
The following list includes the breaking API changes in Electron 3.0.
app
// Veraltet
app.getAppMemoryInfo()
// Ersetze mit
app.getAppMetrics()
// Veraltet
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property
BrowserWindow
// 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
// Veraltet
clipboard.readRtf()
// Ersetze mit
clipboard.readRTF()
// Veraltet
clipboard.writeRtf()
// Ersetze mit
clipboard.writeRTF()
// Veraltet
clipboard.readHtml()
// Ersetze mit
clipboard.readHTML()
// Veraltet
clipboard.writeHtml()
// Ersetze mit
clipboard.writeHTML()
crashReporter
// Veraltet
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// Ersetze mit
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})
nativeImage
// Veraltet
nativeImage.createFromBuffer(buffer, 1.0)
// Ersetze mit
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})
process
// Veraltet
const info = process.getProcessMemoryInfo()
screen
// Veraltet
screen.getMenuBarHeight()
// Ersetze mit
screen.getPrimaryDisplay().workArea
session
// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})
Tray
// Veraltet
tray.setHighlightMode(true)
// Ersetze mit
tray.setHighlightMode('on')
// Veraltet
tray.setHighlightMode(false)
// Ersetze mit
tray.setHighlightMode('off')
webContents
// Veraltet
webContents.openDevTools({ detach: true })
// Ersetze mit
webContents.openDevTools({ mode: 'detach' })
// Entfernt
webContents.setSize(options)
// Für diese API gibt es keinen Ersatz
webFrame
// Veraltet
webFrame.registerURLSchemeAsSecure('app')
// Ersetze mit
protocol.registerStandardSchemes(['app'], { secure: true })
// Veraltet
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// Ersetze mit
protocol.registerStandardSchemes(['app'], { secure: true })
<webview>
// Entfernt
webview.setAttribute('disableguestresize', '')
// Für diese API gibt es keinen Ersatz
// Entfernt
webview.setAttribute('guestinstance', instanceId)
// Für diese API gibt es keinen Ersatz
// Keyboard listener funktionieren nicht länger für 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
// Deprecated
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)
menu
// Entfernt
menu.popup(browserWindow, 100, 200, 2)
// Ersetze mit
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })
nativeImage
// Entfernt
nativeImage.toPng()
// Ersetze mit
nativeImage.toPNG()
// Entfernt
nativeImage.toJpeg()
// Ersetze mit
nativeImage.toJPEG()
process
process.versions.electron
andprocess.version.chrome
will be made read-only properties for consistency with the otherprocess.versions
properties set by Node.
webContents
// Entfernt
webContents.setZoomLevelLimits(1, 2)
// Ersetze mit
webContents.setVisualZoomLevelLimits(1, 2)
webFrame
// Entfernt
webFrame.setZoomLevelLimits(1, 2)
// Ersetze mit
webFrame.setVisualZoomLevelLimits(1, 2)
<webview>
// Entfernt
webview.setZoomLevelLimits(1, 2)
// Ersetze mit
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.