重大更改
这里将记录重大更改,并在可能的情况下向JS代码添加弃用警告,在这更改之前至少会有一个重要版本.
重大更改的类型
本文档使用以下约定对重大更改进行分类:
- **API 更改:**已更改的 API 会以某种方式使未更新的代码必定抛出异常。
- **行为改变:**Electron 的行为已经改变,但并不一定抛出相应的异常。
- **默认值更改:**依赖于默认值的代码的行为可能被破坏,但不保证会抛出相应的异常。 您可以通过显式指定该值的方式恢复旧的默认行为。
- **已废弃:**该 API 已标记为废弃。 该 API 依旧可正常运作,但会抛出已废弃警告,并在将来会移除。
- **已移除:**该 API 或功能已移除,Electron团队不再对此提供支持。
计划重写的 API (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 preseve 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')
.
计划重写的 API (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.
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.
计划重写的 API (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. 此更改是为了消除/减轻一种安全隐患。 你不应该直接暴露 bridge 上的 ipcRenderer 或它的方法。 相反,应该提供一个像下面这样的安全包装器:
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) => { /* ... */ })
计划重写的 API (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.
已移除: 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)
已移除: 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.
}
// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
// No custom position.
}
已移除: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been removed. 可以通过在渲染器之间设置一个 MessageChannel
来替换它。
The senderId
and senderIsMainFrame
properties of IpcRendererEvent
have been removed as well.
已移除: 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) => { /* ... */ })
计划重写的 API (27.0)
已移除:macOS 10.13 / 10.14 / 支援
macOS 10.13 (High Serria) 和 macOS 10.14 (Mojave) 不再支援Chromium.
旧版本的 Electron 将继续在这些操作系统上运行,但需要 macOS 10.15 (Catalina) 或更高版本才能运行 Electron v27.0.0 及更高版本。
弃用:ipcRenderer.sendTo()
ipcRenderer.sendTo()
已被弃用。 可以通过在渲染器之间设置一个 MessageChannel
来替换它。
IpcRendererEvent
的 senderId
和 senderIsMainFrame
属性也已被弃用。
已删除: systemPreferences
中的 color scheme 相关事件
以下 systemPreferences
事件已被删除:
inverted-color-scheme-changed
high-contrast-color-scheme-changed
请改用 nativeTheme
模块上的新 updated
事件。
// 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:
- '浅色'
- 'medium-light'
- '深色'
- 'ultra-dark'
- 'appearance-based'
These were previously deprecated and have been removed by Apple in 10.15.
已删除: webContents.getPrinters
webContents.getPrinters
方法已被删除。 使用webContents.getPrintersAsync
代替。
const w = new BrowserWindow({ show: false })
// Removed
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
已删除:systemPreferences.{get,set}AppLevelAppearance
和 systemPreferences.appLevelAppearance
方法 systemPreferences.getAppLevelAppearance
和 systemPreferences.setAppLevelAppearance
已被删除,也包括属性 systemPreferences.appLevelAppearance
。 请改用模块 nativeTheme
。
// Removed
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
已删除:systemPreferences.getColor
的 alternate-selected-control-text
值
systemPreferences.getColor
的 alternate-selected-control-text
值已被删除。 替换为 selected-content-background
。
// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
计划重写的 API (26.0)
弃用:webContents.getPrinters
webContents.getPrinters
方法已经被废除。 使用webContents.getPrintersAsync
代替。
const w = new BrowserWindow({ show: false })
// 被弃用
console.log(w.webContents.getPrinters())
// 替换为
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
弃用:systemPreferences.{get,set}AppLevelAppearance
和 systemPreferences.appLevelAppearance
方法systemPreferences.getAppLevelAppearance
和 systemPreferences.setAppLevelAppearance
已被弃用,也包括属性 systemPreferences.appLevelAppearance
。 请改用模块 nativeTheme
。
// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'