Skip to main content

重大变化

重大变化

¥Breaking Changes

重大更改将记录在此处，并在可能的情况下将弃用警告添加到 JS 代码中，至少在更改之前添加 一个主要版本。

¥Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.

重大变更的类型​

¥Types of Breaking Changes

本文档使用以下约定对重大更改进行分类：

¥This document uses the following convention to categorize breaking changes:

  • API 更改：API 的更改方式使得未更新的代码一定会引发异常。

    ¥API Changed: An API was changed in such a way that code that has not been updated is guaranteed to throw an exception.

  • 行为改变：Electron 的行为发生了变化，但并不一定会引发异常。

    ¥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.

  • 已弃用：API 被标记为已弃用。该 API 将继续运行，但会发出弃用警告，并将在未来版本中删除。

    ¥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.

  • 删除：API 或功能已被删除，并且 Electron 不再支持。

    ¥Removed: An API or feature was removed, and is no longer supported by Electron.

计划中的重大 API 更改 (30.0)​

¥Planned Breaking API Changes (30.0)

行为改变：跨源 iframe 现在使用权限策略来访问功能​

¥Behavior Changed: cross-origin iframes now use Permission Policy to access features

跨源 iframe 现在必须通过 allow 属性指定给定 iframe 可用的功能才能访问它们。

¥Cross-origin iframes must now specify features available to a given iframe via the allow attribute in order to access them.

请参阅 documentation 了解更多信息。

¥See documentation for more information.

删除：--disable-color-correct-rendering 开关​

¥Removed: The --disable-color-correct-rendering switch

此开关从未被正式记录，但无论如何，此处均已删除它。Chromium 本身现在对颜色空间有更好的支持，因此不需要这个标志。

¥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.

行为改变：macOS 上的 BrowserView.setAutoResize 行为​

¥Behavior Changed: BrowserView.setAutoResize behavior on macOS

在 Electron 30 中，BrowserView 现在是新 WebContentsView API 的封装器。

¥In Electron 30, BrowserView is now a wrapper around the new WebContentsView API.

此前，BrowserView API 的 setAutoResize 函数在 macOS 上由 autoresizing 支持，在 Windows 和 Linux 上由自定义算法支持。对于简单的用例（例如使 BrowserView 填充整个窗口），这两种方法的行为是相同的。然而，在更高级的情况下，BrowserViews 在 macOS 上的自动调整大小将与在其他平台上不同，因为 Windows 和 Linux 的自定义调整大小算法并不完全匹配 macOS 自动调整大小 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.

如果你的应用使用 BrowserView.setAutoResize 执行比让 BrowserView 填充整个窗口更复杂的操作，则你可能已经有自定义逻辑来处理 macOS 上的这种行为差异。如果是这样，Electron 30 将不再需要该逻辑，因为自动调整大小行为是一致的。

¥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.

删除：params.inputFormType 属性于 context-menu 于 WebContents​

¥Removed: params.inputFormType property on context-menu on WebContents

WebContents 中的 context-menu 事件中的 params 对象的 inputFormType 属性已被删除。请改用新的 formControlType 属性。

¥The inputFormType property of the params object in the context-menu event from WebContents has been removed. Use the new formControlType property instead.

删除：process.getIOCounters()​

¥Removed: process.getIOCounters()

Chromium 已删除对此信息的访问。

¥Chromium has removed access to this information.

计划中的重大 API 更改 (29.0)​

¥Planned Breaking API Changes (29.0)

行为改变：ipcRenderer 无法再通过 contextBridge 发送​

¥Behavior Changed: ipcRenderer can no longer be sent over the contextBridge

尝试将整个 ipcRenderer 模块作为对象通过 contextBridge 发送现在将导致网桥接收端出现空对象。进行此更改是为了删除/减轻安全枪的影响。你不应该通过桥直接公开 ipcRenderer 或其方法。相反，提供一个安全的封装器，如下所示：

¥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))
})

删除：app 的 renderer-process-crashed 活动​

¥Removed: renderer-process-crashed event on app

app 的 renderer-process-crashed 事件已被删除。请改用新的 render-process-gone 事件。

¥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) => { /* ... */ })

删除：WebContents 和 <webview> 的 crashed 活动​

¥Removed: crashed event on WebContents and <webview>

WebContents 和 <webview> 上的 crashed 事件已被删除。请改用新的 render-process-gone 事件。

¥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) => { /* ... */ })

删除：app 的 gpu-process-crashed 活动​

¥Removed: gpu-process-crashed event on app

app 的 gpu-process-crashed 事件已被删除。请改用新的 child-process-gone 事件。

¥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)​

¥Planned Breaking API Changes (28.0)

行为改变：WebContents.backgroundThrottling 设置为 false 会影响主机 BrowserWindow 中的所有 WebContents​

¥Behavior Changed: WebContents.backgroundThrottling set to false affects all WebContents in the host BrowserWindow

WebContents.backgroundThrottling 设置为 false 将禁用 BrowserWindow 中显示的所有 WebContents 的帧限制。

¥WebContents.backgroundThrottling set to false will disable frames throttling in the BrowserWindow for all WebContents displayed by it.

删除：BrowserWindow.setTrafficLightPosition(position)​

¥Removed: BrowserWindow.setTrafficLightPosition(position)

BrowserWindow.setTrafficLightPosition(position) 已被删除，应使用 BrowserWindow.setWindowButtonPosition(position) API，它接受 null 而不是 { x: 0, y: 0 } 将位置重置为系统默认值。

¥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()​

¥Removed: BrowserWindow.getTrafficLightPosition()

BrowserWindow.getTrafficLightPosition() 已被删除，应使用 BrowserWindow.getWindowButtonPosition() API，当没有自定义位置时，该 API 返回 null 而不是 { x: 0, y: 0 }。

¥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()​

¥Removed: ipcRenderer.sendTo()

ipcRenderer.sendTo() API 已被删除。应通过在渲染器之间设置 MessageChannel 来替换它。

¥The ipcRenderer.sendTo() API has been removed. It should be replaced by setting up a MessageChannel between the renderers.

IpcRendererEvent 的 senderId 和 senderIsMainFrame 属性也已被删除。

¥The senderId and senderIsMainFrame properties of IpcRendererEvent have been removed as well.

删除：app.runningUnderRosettaTranslation​

¥Removed: app.runningUnderRosettaTranslation

app.runningUnderRosettaTranslation 属性已被删除。请改用 app.runningUnderARM64Translation。

¥The app.runningUnderRosettaTranslation property has been removed. Use app.runningUnderARM64Translation instead.

// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)

已弃用：app 的 renderer-process-crashed 活动​

¥Deprecated: renderer-process-crashed event on app

app 上的 renderer-process-crashed 活动已被弃用。请改用新的 render-process-gone 事件。

¥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) => { /* ... */ })

已弃用：params.inputFormType 属性于 context-menu 于 WebContents​

¥Deprecated: params.inputFormType property on context-menu on WebContents

WebContents 中的 context-menu 事件中 params 对象的 inputFormType 属性已被弃用。请改用新的 formControlType 属性。

¥The inputFormType property of the params object in the context-menu event from WebContents has been deprecated. Use the new formControlType property instead.

已弃用：WebContents 和 <webview> 的 crashed 活动​

¥Deprecated: crashed event on WebContents and <webview>

WebContents 和 <webview> 上的 crashed 事件已被弃用。请改用新的 render-process-gone 事件。

¥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) => { /* ... */ })

已弃用：app 的 gpu-process-crashed 活动​

¥Deprecated: gpu-process-crashed event on app

app 上的 gpu-process-crashed 活动已被弃用。请改用新的 child-process-gone 事件。

¥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)​

¥Planned Breaking API Changes (27.0)

删除：macOS 10.13 / 10.14 支持​

¥Removed: macOS 10.13 / 10.14 support

Chromium 不再支持 macOS 10.13 (High Sierra) 和 macOS 10.14 (Mojave)。

¥macOS 10.13 (High Sierra) and macOS 10.14 (Mojave) are no longer supported by Chromium.

旧版本的 Electron 将继续在这些操作系统上运行，但需要 macOS 10.15 (Catalina) 或更高版本才能运行 Electron v27.0.0 及更高版本。

¥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.

已弃用：ipcRenderer.sendTo()​

¥Deprecated: ipcRenderer.sendTo()

ipcRenderer.sendTo() API 已被弃用。应通过在渲染器之间设置 MessageChannel 来替换它。

¥The ipcRenderer.sendTo() API has been deprecated. It should be replaced by setting up a MessageChannel between the renderers.

IpcRendererEvent 的 senderId 和 senderIsMainFrame 属性也已被弃用。

¥The senderId and senderIsMainFrame properties of IpcRendererEvent have been deprecated as well.

删除：systemPreferences 中的配色方案事件​

¥Removed: color scheme events in systemPreferences

以下 systemPreferences 事件已被删除：

¥The following systemPreferences events have been removed:

  • inverted-color-scheme-changed

  • high-contrast-color-scheme-changed

请改用 nativeTheme 模块上的新 updated 事件。

¥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', () => { /* ... */ })

删除：macOS 上的一些 window.setVibrancy 选项​

¥Removed: Some window.setVibrancy options on macOS

以下活力选项已被删除：

¥The following vibrancy options have been removed:

  • 'light'

  • 'medium-light'

  • 'dark'

  • 'ultra-dark'

  • 'appearance-based'

它们之前已被弃用，并已被 Apple 在 10.15 中删除。

¥These were previously deprecated and have been removed by Apple in 10.15.

删除：webContents.getPrinters​

¥Removed: webContents.getPrinters

webContents.getPrinters 方法已被删除。请改用 webContents.getPrintersAsync。

¥The webContents.getPrinters method has been removed. Use webContents.getPrintersAsync instead.

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​

¥Removed: systemPreferences.{get,set}AppLevelAppearance and systemPreferences.appLevelAppearance

systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 方法以及 systemPreferences.appLevelAppearance 属性已被删除。请改用 nativeTheme 模块。

¥The systemPreferences.getAppLevelAppearance and systemPreferences.setAppLevelAppearance methods have been removed, as well as the systemPreferences.appLevelAppearance property. Use the nativeTheme module instead.

// 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 值​

¥Removed: alternate-selected-control-text value for systemPreferences.getColor

systemPreferences.getColor 的 alternate-selected-control-text 值已被删除。请改用 selected-content-background。

¥The alternate-selected-control-text value for systemPreferences.getColor has been removed. Use selected-content-background instead.

// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')

计划中的重大 API 更改 (26.0)​

¥Planned Breaking API Changes (26.0)

已弃用：webContents.getPrinters​

¥Deprecated: webContents.getPrinters

webContents.getPrinters 方法已被弃用。请改用 webContents.getPrintersAsync。

¥The webContents.getPrinters method has been deprecated. Use webContents.getPrintersAsync instead.

const w = new BrowserWindow({ show: false })

// Deprecated
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

已弃用：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance​

¥Deprecated: systemPreferences.{get,set}AppLevelAppearance and systemPreferences.appLevelAppearance

systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 方法以及 systemPreferences.appLevelAppearance 属性已被弃用。请改用 nativeTheme 模块。

¥The systemPreferences.getAppLevelAppearance and systemPreferences.setAppLevelAppearance methods have been deprecated, as well as the systemPreferences.appLevelAppearance property. Use the nativeTheme module instead.

// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'

已弃用：systemPreferences.getColor 的 alternate-selected-control-text 值​

¥Deprecated: alternate-selected-control-text value for systemPreferences.getColor

systemPreferences.getColor 的 alternate-selected-control-text 值已被弃用。请改用 selected-content-background。

¥The alternate-selected-control-text value for systemPreferences.getColor has been deprecated. Use selected-content-background instead.

// Deprecated
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')

计划中的重大 API 更改 (25.0)​

¥Planned Breaking API Changes (25.0)

已弃用：protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol​

¥Deprecated: protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol

protocol.register*Protocol 和 protocol.intercept*Protocol 方法已替换为 protocol.handle。

¥The protocol.register*Protocol and protocol.intercept*Protocol methods have been replaced with protocol.handle.

新方法可以注册新协议或拦截现有协议，并且响应可以是任何类型。

¥The new method can either register a new protocol or intercept an existing protocol, and responses can be of any type.

// Deprecated in Electron 25
protocol.registerBufferProtocol('some-protocol', () => {
  callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})

// Replace with
protocol.handle('some-protocol', () => {
  return new Response(
    Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
    { headers: { 'content-type': 'text/html' } }
  )
})
// Deprecated in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
  callback({ url: 'https://electron.nodejs.cn' })
})

// Replace with
protocol.handle('some-protocol', () => {
  return net.fetch('https://electron.nodejs.cn')
})
// Deprecated in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
  callback({ filePath: '/path/to/my/file' })
})

// Replace with
protocol.handle('some-protocol', () => {
  return net.fetch('file:///path/to/my/file')
})

已弃用：BrowserWindow.setTrafficLightPosition(position)​

¥Deprecated: BrowserWindow.setTrafficLightPosition(position)

BrowserWindow.setTrafficLightPosition(position) 已被弃用，应使用 BrowserWindow.setWindowButtonPosition(position) API，它接受 null 而不是 { x: 0, y: 0 } 将位置重置为系统默认值。

¥BrowserWindow.setTrafficLightPosition(position) has been deprecated, the BrowserWindow.setWindowButtonPosition(position) API should be used instead which accepts null instead of { x: 0, y: 0 } to reset the position to system default.

// Deprecated in Electron 25
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })

// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)

已弃用：BrowserWindow.getTrafficLightPosition()​

¥Deprecated: BrowserWindow.getTrafficLightPosition()

BrowserWindow.getTrafficLightPosition() 已被弃用，应使用 BrowserWindow.getWindowButtonPosition() API，当没有自定义位置时，它会返回 null 而不是 { x: 0, y: 0 }。

¥BrowserWindow.getTrafficLightPosition() has been deprecated, the BrowserWindow.getWindowButtonPosition() API should be used instead which returns null instead of { x: 0, y: 0 } when there is no custom position.

// Deprecated in Electron 25
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
  // No custom position.
}

// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
  // No custom position.
}

计划中的重大 API 更改 (24.0)​

¥Planned Breaking API Changes (24.0)

API 更改：nativeImage.createThumbnailFromPath(path, size)​

¥API Changed: nativeImage.createThumbnailFromPath(path, size)

maxSize 参数已更改为 size，以反映传入的大小将是创建的缩略图的大小。以前，如果图片小于 maxSize，Windows 不会放大图片，而 macOS 总是将大小设置为 maxSize。现在跨平台的行为是相同的。

¥The maxSize parameter has been changed to size to reflect that the size passed in will be the size the thumbnail created. Previously, Windows would not scale the image up if it were smaller than maxSize, and macOS would always set the size to maxSize. Behavior is now the same across platforms.

更新的行为：

¥Updated Behavior:

// 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 }
})

以前的行为（在 Windows 上）：

¥Previous Behavior (on 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 }
})

计划中的重大 API 更改 (23.0)​

¥Planned Breaking API Changes (23.0)

行为改变：macOS 上的可拖动区域​

¥Behavior Changed: Draggable Regions on macOS

可拖动区域的实现（使用 CSS 属性 -webkit-app-region: drag）在 macOS 上已更改，以使其与 Windows 和 Linux 保持一致。以前，当 -webkit-app-region: no-drag 的区域与 -webkit-app-region: drag 的区域重叠时，无论 CSS 分层如何，在 macOS 上 no-drag 区域始终优先。也就是说，如果 drag 区域位于 no-drag 区域上方，则它将被忽略。从 Electron 23 开始，drag 区域位于 no-drag 区域之上将正确导致该区域可拖动。

¥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.

此外，customButtonsOnHover BrowserWindow 属性先前创建了一个忽略 -webkit-app-region CSS 属性的可拖动区域。该问题现已修复（请参阅 #37210 进行讨论）。

¥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).

因此，如果你的应用在 macOS 上使用具有可拖动区域的无框架窗口，则应用中的可拖动区域可能会在 Electron 23 中发生变化。

¥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.

删除：Windows 7 / 8 / 8.1 支持​

¥Removed: Windows 7 / 8 / 8.1 support

不再支持 Windows 7、Windows 8 和 Windows 8.1。Electron 遵循计划中的 Chromium 弃用政策，该政策将于 从 Chromium 109 开始弃用 Windows 7 支持。

¥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.

旧版本的 Electron 将继续在这些操作系统上运行，但需要 Windows 10 或更高版本才能运行 Electron v23.0.0 及更高版本。

¥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.

删除：BrowserWindow scroll-touch-* 事件​

¥Removed: BrowserWindow scroll-touch-* events

BrowserWindow 上已弃用的 scroll-touch-begin、scroll-touch-end 和 scroll-touch-edge 事件已被删除。相反，请使用 WebContents 上新推出的 input-event 事件。

¥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()
  }
})

删除：webContents.incrementCapturerCount(stayHidden, stayAwake)​

¥Removed: webContents.incrementCapturerCount(stayHidden, stayAwake)

webContents.incrementCapturerCount(stayHidden, stayAwake) 功能已被删除。现在，当页面捕获完成时，它由 webContents.capturePage 自动处理。

¥The webContents.incrementCapturerCount(stayHidden, stayAwake) function has been removed. It is now automatically handled by webContents.capturePage when a page capture completes.

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())
})

删除：webContents.decrementCapturerCount(stayHidden, stayAwake)​

¥Removed: webContents.decrementCapturerCount(stayHidden, stayAwake)

webContents.decrementCapturerCount(stayHidden, stayAwake) 功能已被删除。现在，当页面捕获完成时，它由 webContents.capturePage 自动处理。

¥The webContents.decrementCapturerCount(stayHidden, stayAwake) function has been removed. It is now automatically handled by webContents.capturePage when a page capture completes.

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())
})

计划中的重大 API 更改 (22.0)​

¥Planned Breaking API Changes (22.0)

已弃用：webContents.incrementCapturerCount(stayHidden, stayAwake)​

¥Deprecated: webContents.incrementCapturerCount(stayHidden, stayAwake)

webContents.incrementCapturerCount(stayHidden, stayAwake) 已被弃用。现在，当页面捕获完成时，它由 webContents.capturePage 自动处理。

¥webContents.incrementCapturerCount(stayHidden, stayAwake) has been deprecated. It is now automatically handled by webContents.capturePage when a page capture completes.

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())
})

已弃用：webContents.decrementCapturerCount(stayHidden, stayAwake)​

¥Deprecated: webContents.decrementCapturerCount(stayHidden, stayAwake)

webContents.decrementCapturerCount(stayHidden, stayAwake) 已被弃用。现在，当页面捕获完成时，它由 webContents.capturePage 自动处理。

¥webContents.decrementCapturerCount(stayHidden, stayAwake) has been deprecated. It is now automatically handled by webContents.capturePage when a page capture completes.

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())
})

删除：WebContents new-window 事件​

¥Removed: WebContents new-window event

WebContents 的 new-window 事件已被删除。已被 webContents.setWindowOpenHandler() 取代。

¥The new-window event of WebContents has been removed. It is replaced by webContents.setWindowOpenHandler().

// Removed in Electron 22
webContents.on('new-window', (event) => {
  event.preventDefault()
})

// Replace with
webContents.setWindowOpenHandler((details) => {
  return { action: 'deny' }
})

删除：<webview> new-window 事件​

¥Removed: <webview> new-window event

<webview> 的 new-window 事件已被删除。没有直接替代。

¥The new-window event of <webview> has been removed. There is no direct replacement.

// Removed 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')
})

已弃用：BrowserWindow scroll-touch-* 事件​

¥Deprecated: BrowserWindow scroll-touch-* events

BrowserWindow 上的 scroll-touch-begin、scroll-touch-end 和 scroll-touch-edge 事件已弃用。相反，请使用 WebContents 上新推出的 input-event 事件。

¥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()
  }
})

计划中的重大 API 更改 (21.0)​

¥Planned Breaking API Changes (21.0)

行为改变：启用 V8 内存笼​

¥Behavior Changed: V8 Memory Cage enabled

V8 内存笼已启用，这对使用 ArrayBuffer 或 Buffer 封装非 V8 内存的原生模块有影响。有关详细信息，请参阅 关于 V8 内存笼的博客文章。

¥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 更改：webContents.printToPDF()​

¥API Changed: webContents.printToPDF()

webContents.printToPDF() 已修改为符合 Chrome DevTools 协议中的 Page.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)
})

计划中的重大 API 更改 (20.0)​

¥Planned Breaking API Changes (20.0)

删除：macOS 10.11 / 10.12 支持​

¥Removed: macOS 10.11 / 10.12 support

Chromium 不再支持 macOS 10.11 (El Capitan) 和 macOS 10.12 (Sierra)。

¥macOS 10.11 (El Capitan) and macOS 10.12 (Sierra) are no longer supported by Chromium.

旧版本的 Electron 将继续在这些操作系统上运行，但需要 macOS 10.13 (High Sierra) 或更高版本才能运行 Electron v20.0.0 及更高版本。

¥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.

默认更改：没有 nodeIntegration: true 的渲染器默认被沙箱化​

¥Default Changed: renderers without nodeIntegration: true are sandboxed by default

以前，指定预加载脚本的渲染器默认为未沙箱化。这意味着默认情况下，预加载脚本可以访问 Node.js。在 Electron 20 中，这个默认值已经改变。从 Electron 20 开始，渲染器将默认被沙箱化，除非指定了 nodeIntegration: true 或 sandbox: false。

¥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.

如果你的预加载脚本不依赖于 Node，则无需执行任何操作。如果你的预加载脚本确实依赖于 Node，请重构它们以从渲染器中删除 Node 使用，或者为相关渲染器显式指定 sandbox: false。

¥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.

删除：Linux 上的 skipTaskbar​

¥Removed: skipTaskbar on Linux

在 X11 上，skipTaskbar 向 X11 窗口管理器发送 _NET_WM_STATE_SKIP_TASKBAR 消息。Wayland 没有直接的等效项，并且已知的解决方法具有不可接受的权衡（例如 GNOME 中的 Window.is_skip_taskbar 需要不安全模式），因此 Electron 无法在 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 更改：session.setDevicePermissionHandler(handler)​

¥API Changed: session.setDevicePermissionHandler(handler)

使用 session.setDevicePermissionHandler(handler) 时调用的处理程序的参数发生了变化。该处理程序不再传递帧 WebFrameMain，而是传递 origin，这是检查设备权限的源。

¥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.

计划中的重大 API 更改 (19.0)​

¥Planned Breaking API Changes (19.0)

删除：IA32 Linux 二进制文件​

¥Removed: IA32 Linux binaries

这是 Chromium 102.0.4999.0 放弃对 IA32 Linux 支持的结果。删除对 IA32 Linux 的支持 到此结束。

¥This is a result of Chromium 102.0.4999.0 dropping support for IA32 Linux. This concludes the removal of support for IA32 Linux.

计划中的重大 API 更改 (18.0)​

¥Planned Breaking API Changes (18.0)

删除：nativeWindowOpen​

¥Removed: nativeWindowOpen

在 Electron 15 之前，window.open 默认情况下使用 BrowserWindowProxy。这意味着 window.open('about:blank') 无法打开同步可编写脚本的子窗口，以及其他不兼容性。从 Electron 15 开始，nativeWindowOpen 已默认启用。

¥Prior to Electron 15, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. Since Electron 15, nativeWindowOpen has been enabled by default.

有关更多详细信息，请参阅 在 Electron 中打开 window.open 的文档。

¥See the documentation for window.open in Electron for more details.

计划中的重大 API 更改 (17.0)​

¥Planned Breaking API Changes (17.0)

删除：渲染器中的 desktopCapturer.getSources​

¥Removed: desktopCapturer.getSources in the renderer

desktopCapturer.getSources API 现在仅在主进程中可用。为了提高 Electron 应用的默认安全性，这一点已更改。

¥The desktopCapturer.getSources API is now only available in the main process. This has been changed in order to improve the default security of Electron apps.

如果你需要此功能，可以按如下方式替换：

¥If you need this functionality, it can be replaced as follows:

// 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.

已弃用：nativeWindowOpen​

¥Deprecated: nativeWindowOpen

在 Electron 15 之前，window.open 默认情况下使用 BrowserWindowProxy。这意味着 window.open('about:blank') 无法打开同步可编写脚本的子窗口，以及其他不兼容性。从 Electron 15 开始，nativeWindowOpen 已默认启用。

¥Prior to Electron 15, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. Since Electron 15, nativeWindowOpen has been enabled by default.

有关更多详细信息，请参阅 在 Electron 中打开 window.open 的文档。

¥See the documentation for window.open in Electron for more details.

计划中的重大 API 更改 (16.0)​

¥Planned Breaking API Changes (16.0)

行为改变：Linux 上的 crashReporter 实现切换到 Crashpad​

¥Behavior Changed: crashReporter implementation switched to Crashpad on Linux

Linux 上 crashReporter API 的底层实现已从 Breakpad 更改为 Crashpad，使其与 Windows 和 Mac 保持一致。因此，现在会自动监视子进程，并且不再需要在 Node 子进程中调用 process.crashReporter.start（并且不建议这样做，因为它将启动 Crashpad 报告程序的第二个实例）。

¥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).

Linux 上注释的报告方式也有一些细微的变化，包括长值将不再在附加 __1、__2 等的注释之间分割，而是会在（新的、更长的）注释值限制处被截断 。

¥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.

已弃用：渲染器中的 desktopCapturer.getSources​

¥Deprecated: desktopCapturer.getSources in the renderer

渲染器中使用 desktopCapturer.getSources API 已被弃用并将被删除。此更改提高了 Electron 应用的默认安全性。

¥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.

有关如何在应用中替换此 API 的详细信息，请参阅 此处。

¥See here for details on how to replace this API in your app.

计划中的重大 API 更改 (15.0)​

¥Planned Breaking API Changes (15.0)

默认更改：nativeWindowOpen 默认为 true​

¥Default Changed: nativeWindowOpen defaults to true

在 Electron 15 之前，window.open 默认情况下使用 BrowserWindowProxy。这意味着 window.open('about:blank') 无法打开同步可编写脚本的子窗口，以及其他不兼容性。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. nativeWindowOpen is no longer experimental, and is now the default.

有关更多详细信息，请参阅 在 Electron 中打开 window.open 的文档。

¥See the documentation for window.open in Electron for more details.

已弃用：app.runningUnderRosettaTranslation​

¥Deprecated: app.runningUnderRosettaTranslation

app.runningUnderRosettaTranslation 属性已被弃用。请改用 app.runningUnderARM64Translation。

¥The app.runningUnderRosettaTranslation property has been deprecated. Use app.runningUnderARM64Translation instead.

// Deprecated
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)

计划中的重大 API 更改 (14.0)​

¥Planned Breaking API Changes (14.0)

删除：remote 模块​

¥Removed: remote module

remote 模块在 Electron 12 中已弃用，并将在 Electron 14 中删除。它被 @electron/remote 模块取代。

¥The remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote
// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

删除：app.allowRendererProcessReuse​

¥Removed: app.allowRendererProcessReuse

作为我们计划的一部分，app.allowRendererProcessReuse 属性将被删除，以便与 Chromium 的安全性、性能和可维护性进程模型更加紧密地保持一致。

¥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.

欲了解更多详细信息，请参阅 #18397。

¥For more detailed information see #18397.

删除：浏览器窗口亲和性​

¥Removed: Browser Window Affinity

作为我们计划的一部分，构建新 BrowserWindow 时的 affinity 选项将被删除，以便与 Chromium 的安全性、性能和可维护性进程模型更加紧密地保持一致。

¥The affinity option when constructing a new BrowserWindow will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.

欲了解更多详细信息，请参阅 #18397。

¥For more detailed information see #18397.

API 更改：window.open()​

¥API Changed: window.open()

可选参数 frameName 将不再设置窗口的标题。现在，这遵循 原生文档 在相应参数 windowName 下描述的规范。

¥The optional parameter frameName will no longer set the title of the window. This now follows the specification described by the native documentation under the corresponding parameter windowName.

如果你使用此参数来设置窗口标题，则可以使用 win.setTitle(title)。

¥If you were using this parameter to set the title of a window, you can instead use win.setTitle(title).

删除：worldSafeExecuteJavaScript​

¥Removed: worldSafeExecuteJavaScript

在 Electron 14 中，worldSafeExecuteJavaScript 将被删除。没有其他选择，请确保你的代码在启用此属性的情况下工作。从 Electron 12 开始它就被默认启用。

¥In Electron 14, worldSafeExecuteJavaScript will be removed. There is no alternative, please ensure your code works with this property enabled. It has been enabled by default since Electron 12.

如果你使用 webFrame.executeJavaScript 或 webFrame.executeJavaScriptInIsolatedWorld，你将受到此更改的影响。你需要确保 上下文桥 API 支持这些方法中任一方法返回的值，因为这些方法使用相同的值传递语义。

¥You will be affected by this change if you use either webFrame.executeJavaScript or webFrame.executeJavaScriptInIsolatedWorld. You will need to ensure that values returned by either of those methods are supported by the Context Bridge API as these methods use the same value passing semantics.

删除：BrowserWindowConstructorOptions 继承自父窗口​

¥Removed: BrowserWindowConstructorOptions inheriting from parent windows

在 Electron 14 之前，使用 window.open 打开的窗口将从其父窗口继承 BrowserWindow 构造函数选项，例如 transparent 和 resizable。从 Electron 14 开始，此行为被删除，窗口将不会从其父级继承任何 BrowserWindow 构造函数选项。

¥Prior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.

相反，使用 setWindowOpenHandler 显式设置新窗口的选项：

¥Instead, explicitly set options for the new window with setWindowOpenHandler:

webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    overrideBrowserWindowOptions: {
      // ...
    }
  }
})

删除：additionalFeatures​

¥Removed: additionalFeatures

WebContents 的 new-window 和 did-create-window 事件中已弃用的 additionalFeatures 属性已被删除。由于 new-window 使用位置参数，因此该参数仍然存在，但始终是空数组 []。（但请注意，new-window 事件本身已被弃用，并被 setWindowOpenHandler 取代。）窗口功能中的裸键现在将在选项对象中显示为值为 true 的键。

¥The deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.

// Removed in Electron 14
// Triggered by window.open('...', '', 'my-key')
webContents.on('did-create-window', (window, details) => {
  if (details.additionalFeatures.includes('my-key')) {
    // ...
  }
})

// Replace with
webContents.on('did-create-window', (window, details) => {
  if (details.options['my-key']) {
    // ...
  }
})

计划中的重大 API 更改 (13.0)​

¥Planned Breaking API Changes (13.0)

API 更改：session.setPermissionCheckHandler(handler)​

¥API Changed: session.setPermissionCheckHandler(handler)

handler 方法的第一个参数以前总是 webContents，现在有时可以是 null。你应该使用 requestingOrigin、embeddingOrigin 和 securityOrigin 属性来正确响应权限检查。由于 webContents 可能是 null，因此不再可靠。

¥The handler methods first parameter was previously always a webContents, it can now sometimes be null. You should use the requestingOrigin, embeddingOrigin and securityOrigin properties to respond to the permission check correctly. As the webContents can be null it can no longer be relied on.

// Old code
session.setPermissionCheckHandler((webContents, permission) => {
  if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
    return true
  }
  return false
})

// Replace with
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
    return true
  }
  return false
})

删除：shell.moveItemToTrash()​

¥Removed: shell.moveItemToTrash()

已弃用的同步 shell.moveItemToTrash() API 已被删除。请改用异步 shell.trashItem()。

¥The deprecated synchronous shell.moveItemToTrash() API has been removed. Use the asynchronous shell.trashItem() instead.

// Removed in Electron 13
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)

删除：BrowserWindow 扩展 API​

¥Removed: BrowserWindow extension APIs

已弃用的扩展 API 已被删除：

¥The deprecated extension APIs have been removed:

  • BrowserWindow.addExtension(path)

  • BrowserWindow.addDevToolsExtension(path)

  • BrowserWindow.removeExtension(name)

  • BrowserWindow.removeDevToolsExtension(name)

  • BrowserWindow.getExtensions()

  • BrowserWindow.getDevToolsExtensions()

请改用会话 API：

¥Use the session APIs instead:

  • ses.loadExtension(path)

  • ses.removeExtension(extension_id)

  • ses.getAllExtensions()

// Removed in Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)
// Removed in Electron 13
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)
// Removed in Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

删除：systemPreferences 中的方法​

¥Removed: methods in systemPreferences

以下 systemPreferences 方法已被弃用：

¥The following systemPreferences methods have been deprecated:

  • systemPreferences.isDarkMode()

  • systemPreferences.isInvertedColorScheme()

  • systemPreferences.isHighContrastColorScheme()

请改用以下 nativeTheme 属性：

¥Use the following nativeTheme properties instead:

  • nativeTheme.shouldUseDarkColors

  • nativeTheme.shouldUseInvertedColorScheme

  • nativeTheme.shouldUseHighContrastColors

// Removed in Electron 13
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors

// Removed in Electron 13
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme

// Removed in Electron 13
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors

已弃用：WebContents new-window 事件​

¥Deprecated: WebContents new-window event

WebContents 的 new-window 事件已被弃用。已被 webContents.setWindowOpenHandler() 取代。

¥The new-window event of WebContents has been deprecated. It is replaced by webContents.setWindowOpenHandler().

// Deprecated in Electron 13
webContents.on('new-window', (event) => {
  event.preventDefault()
})

// Replace with
webContents.setWindowOpenHandler((details) => {
  return { action: 'deny' }
})

计划中的重大 API 更改 (12.0)​

¥Planned Breaking API Changes (12.0)

删除：Pepper Flash 支持​

¥Removed: Pepper Flash support

Chromium 已经取消了对 Flash 的支持，因此我们必须效仿。有关更多详细信息，请参阅 Chromium 的 闪存路线图。

¥Chromium has removed support for Flash, and so we must follow suit. See Chromium's Flash Roadmap for more details.

默认更改：worldSafeExecuteJavaScript 默认为 true​

¥Default Changed: worldSafeExecuteJavaScript defaults to true

在 Electron 12 中，worldSafeExecuteJavaScript 将默认启用。要恢复以前的行为，必须在 WebPreferences 中指定 worldSafeExecuteJavaScript: false。请注意，将此选项设置为 false 是不安全的。

¥In Electron 12, worldSafeExecuteJavaScript will be enabled by default. To restore the previous behavior, worldSafeExecuteJavaScript: false must be specified in WebPreferences. Please note that setting this option to false is insecure.

此选项将在 Electron 14 中删除，因此请迁移你的代码以支持默认值。

¥This option will be removed in Electron 14 so please migrate your code to support the default value.

默认更改：contextIsolation 默认为 true​

¥Default Changed: contextIsolation defaults to true

在 Electron 12 中，contextIsolation 将默认启用。要恢复以前的行为，必须在 WebPreferences 中指定 contextIsolation: false。

¥In Electron 12, contextIsolation will be enabled by default. To restore the previous behavior, contextIsolation: false must be specified in WebPreferences.

为了你的应用的安全，我们 建议启用 contextIsolation。

¥We recommend having contextIsolation enabled for the security of your application.

另一个含义是，除非 nodeIntegration 是 true 并且 contextIsolation 是 false，否则 require() 不能在渲染器进程中使用。

¥Another implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.

欲了解更多详情，请参阅：https://github.com/electron/electron/issues/23506

¥For more details see: https://github.com/electron/electron/issues/23506

删除：crashReporter.getCrashesDirectory()​

¥Removed: crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory 方法已被删除。用法应替换为 app.getPath('crashDumps')。

¥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')

删除：渲染器进程中的 crashReporter 个方法​

¥Removed: crashReporter methods in the renderer process

以下 crashReporter 方法在渲染器进程中不再可用：

¥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.

详细信息请参见 #23265。

¥See #23265 for more details.

默认更改：crashReporter.start({ compress: true })​

¥Default Changed: crashReporter.start({ compress: true })

compress 选项到 crashReporter.start 的默认值已从 false 更改为 true。这意味着崩溃转储将使用 Content-Encoding: gzip 标头上传到崩溃摄取服务器，并且正文将被压缩。

¥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.

如果你的崩溃摄取服务器不支持压缩有效负载，你可以通过在崩溃报告器选项中指定 { compress: false } 来关闭压缩。

¥If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.

已弃用：remote 模块​

¥Deprecated: remote module

remote 模块在 Electron 12 中已弃用，并将在 Electron 14 中删除。它被 @electron/remote 模块取代。

¥The remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote
// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

已弃用：shell.moveItemToTrash()​

¥Deprecated: shell.moveItemToTrash()

同步 shell.moveItemToTrash() 已被新的异步 shell.trashItem() 取代。

¥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(/* ... */)

计划中的重大 API 更改 (11.0)​

¥Planned Breaking API Changes (11.0)

删除：BrowserView 的 BrowserView.{destroy, fromId, fromWebContents, getAllViews} 和 id 属性​

¥Removed: BrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserView

实验性 API BrowserView.{destroy, fromId, fromWebContents, getAllViews} 现已删除。此外，BrowserView 的 id 属性也已被删除。

¥The experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.

欲了解更多详细信息，请参阅 #23578。

¥For more detailed information, see #23578.

计划中的重大 API 更改 (10.0)​

¥Planned Breaking API Changes (10.0)

已弃用：companyName 到 crashReporter.start() 的参数​

¥Deprecated: companyName argument to crashReporter.start()

以前需要的 crashReporter.start() 的 companyName 参数现在是可选的，并且已被弃用。要以不弃用的方式获得相同的行为，你可以在 globalExtra 中传递 companyName 值。

¥The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. To get the same behavior in a non-deprecated way, you can pass a companyName value in globalExtra.

// Deprecated in Electron 10
crashReporter.start({ companyName: 'Umbrella Corporation' })
// Replace with
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

已弃用：crashReporter.getCrashesDirectory()​

¥Deprecated: crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory 方法已被弃用。用法应替换为 app.getPath('crashDumps')。

¥The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').

// Deprecated in Electron 10
crashReporter.getCrashesDirectory()
// Replace with
app.getPath('crashDumps')

已弃用：渲染器进程中的 crashReporter 个方法​

¥Deprecated: crashReporter methods in the renderer process

不推荐从渲染器进程调用以下 crashReporter 方法：

¥Calling the following crashReporter methods from the renderer process is deprecated:

  • crashReporter.start

  • crashReporter.getLastCrashReport

  • crashReporter.getUploadedReports

  • crashReporter.getUploadToServer

  • crashReporter.setUploadToServer

  • crashReporter.getCrashesDirectory

渲染器中 crashReporter 模块中剩余的唯一未弃用的方法是 addExtraParameter、removeExtraParameter 和 getParameters。

¥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.

详细信息请参见 #23265。

¥See #23265 for more details.

已弃用：crashReporter.start({ compress: false })​

¥Deprecated: crashReporter.start({ compress: false })

不推荐在 crashReporter.start 中设置 { compress: false }。几乎所有崩溃摄取服务器都支持 gzip 压缩。该选项将在 Electron 的未来版本中删除。

¥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.

默认更改：enableRemoteModule 默认为 false​

¥Default Changed: enableRemoteModule defaults to false

在 Electron 9 中，使用远程模块而不通过 enableRemoteModule WebPreferences 选项显式启用它会开始发出警告。在 Electron 10 中，远程模块现在默认处于禁用状态。要使用远程模块，必须在 WebPreferences 中指定 enableRemoteModule: true：

¥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​

API 现在是同步的，不再需要可选的回调。

¥The APIs are now synchronous and the optional callback is no longer needed.

// 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​

API 现在是同步的，不再需要可选的回调。

¥The APIs are now synchronous and the optional callback is no longer needed.

// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
protocol.registerFileProtocol(scheme, handler)

在导航发生之前，注册或拦截的协议不会对当前页面产生影响。

¥The registered or intercepted protocol does not have effect on current page until navigation happens.

protocol.isProtocolHandled​

此 API 已弃用，用户应使用 protocol.isProtocolRegistered 和 protocol.isProtocolIntercepted 代替。

¥This API is deprecated and users should use protocol.isProtocolRegistered and protocol.isProtocolIntercepted instead.

// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)

计划中的重大 API 更改 (9.0)​

¥Planned Breaking API Changes (9.0)

默认更改：默认情况下禁用在渲染器进程中加载非上下文感知的原生模块​

¥Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default

从 Electron 9 开始，我们不允许在渲染器进程中加载非上下文感知的原生模块。这是为了提高 Electron 作为项目的安全性、性能和可维护性。

¥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.

如果这对你有影响，你可以暂时将 app.allowRendererProcessReuse 设置为 false 以恢复到旧的行为。在 Electron 11 之前，此标志只是一个选项，因此你应该计划更新你的原生模块以实现上下文感知。

¥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.

欲了解更多详细信息，请参阅 #18397。

¥For more detailed information see #18397.

已弃用：BrowserWindow 扩展 API​

¥Deprecated: BrowserWindow extension APIs

以下扩展 API 已被弃用：

¥The following extension APIs have been deprecated:

  • BrowserWindow.addExtension(path)

  • BrowserWindow.addDevToolsExtension(path)

  • BrowserWindow.removeExtension(name)

  • BrowserWindow.removeDevToolsExtension(name)

  • BrowserWindow.getExtensions()

  • BrowserWindow.getDevToolsExtensions()

请改用会话 API：

¥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()

删除：<webview>.getWebContents()​

¥Removed: <webview>.getWebContents()

该 API 在 Electron 8.0 中已弃用，现已删除。

¥This API, which was deprecated in Electron 8.0, is now removed.

// Removed in Electron 9.0
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

删除：webFrame.setLayoutZoomLevelLimits()​

¥Removed: webFrame.setLayoutZoomLevelLimits()

Chromium 取消了对更改布局缩放级别限制的支持，并且超出了 Electron 的维护能力。该函数在 Electron 8.x 中已被弃用，并在 Electron 9.x 中被删除。布局缩放级别限制现在固定为最小 0.25 和最大 5.0，如 此处 所定义。

¥Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function was deprecated in Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

行为改变：现在通过 IPC 发送非 JS 对象会引发异常​

¥Behavior Changed: Sending non-JS objects over IPC now throws an exception

在 Electron 8.0 中，IPC 改为使用结构化克隆算法，带来了显着的性能提升。为了帮助简化转场，保留了旧的 IPC 序列化算法并将其用于某些无法使用结构化克隆进行序列化的对象。特别是，DOM 对象（例如 Element、Location 和 DOMMatrix）、C++ 类支持的 Node.js 对象（例如 process.env、Stream 的某些成员）和 C++ 类支持的 Electron 对象（例如 WebContents、BrowserWindow 和 WebFrame）是不可序列化的 与结构化克隆。每当调用旧算法时，都会打印一条弃用警告。

¥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.

在 Electron 9.0 中，旧的序列化算法已被删除，发送此类不可序列化的对象现在将抛出 "无法克隆对象" 错误。

¥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 更改：shell.openItem 现在是 shell.openPath​

¥API Changed: shell.openItem is now shell.openPath

shell.openItem API 已替换为异步 shell.openPath API。你可以查看原始 API 提案和推断 此处。

¥The shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.

计划中的重大 API 更改 (8.0)​

¥Planned Breaking API Changes (8.0)

行为改变：通过 IPC 发送的值现在使用结构化克隆算法进行序列化​

¥Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm

用于序列化通过 IPC 发送的对象的算法（通过 ipcRenderer.send、ipcRenderer.sendSync、WebContents.send 和相关方法）已从自定义算法切换为 V8 的内置 结构化克隆算法，与用于序列化 postMessage 消息的算法相同。这为大消息带来了 2 倍的性能提升，但也带来了一些行为上的重大变化。

¥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.

  • 通过 IPC 发送函数、Promises、WeakMap、WeakSet 或包含任何此类值的对象现在将引发异常，而不是默默地将函数转换为 undefined。

    ¥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 和 -Infinity 现在将被正确序列化，而不是转换为 null。

    ¥NaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.

  • 包含循环引用的对象现在将被正确序列化，而不是转换为 null。

    ¥Objects containing cyclic references will now be correctly serialized, instead of being converted to null.

  • Set、Map、Error 和 RegExp 值将被正确序列化，而不是转换为 {}。

    ¥Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.

  • BigInt 值将被正确序列化，而不是转换为 null。

    ¥BigInt values will be correctly serialized, instead of being converted to null.

  • 稀疏数组将被序列化，而不是使用 null 转换为密集数组。

    ¥Sparse arrays will be serialized as such, instead of being converted to dense arrays with nulls.

  • Date 对象将作为 Date 对象传输，而不是转换为其 ISO 字符串表示形式。

    ¥Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.

  • 类型化数组（例如 Uint8Array、Uint16Array、Uint32Array 等）将按原样传输，而不是转换为 Node.js Buffer。

    ¥Typed Arrays (such as Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.

  • Node.js Buffer 对象将作为 Uint8Array 传输。你可以通过封装底层 ArrayBuffer 将 Uint8Array 转换回 Node.js Buffer：

    ¥Node.js Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:

Buffer.from(value.buffer, value.byteOffset, value.byteLength)

不推荐发送任何非原生 JS 类型的对象，例如 DOM 对象（例如 Element、Location、DOMMatrix）、Node.js 对象（例如 process.env、Stream）或 Electron 对象（例如 WebContents、BrowserWindow、WebFrame）。在 Electron 8 中，这些对象将像以前一样使用 DeprecationWarning 消息进行序列化，但从 Electron 9 开始，发送这些类型的对象将引发 '无法克隆' 错误。

¥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.

已弃用：<webview>.getWebContents()​

¥Deprecated: <webview>.getWebContents()

该 API 是使用 remote 模块实现的，该模块对性能和安全都有影响。因此它的用法应该是明确的。

¥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())

但是，建议完全避免使用 remote 模块。

¥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())

已弃用：webFrame.setLayoutZoomLevelLimits()​

¥Deprecated: webFrame.setLayoutZoomLevelLimits()

Chromium 取消了对更改布局缩放级别限制的支持，并且超出了 Electron 的维护能力。该函数将在 Electron 8.x 中发出警告，并在 Electron 9.x 中不再存在。布局缩放级别限制现在固定为最小 0.25 和最大 5.0，如 此处 所定义。

¥Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron's capacity to maintain it. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

systemPreferences 中已弃用的事件​

¥Deprecated events in systemPreferences

以下 systemPreferences 事件已被弃用：

¥The following systemPreferences events have been deprecated:

  • inverted-color-scheme-changed

  • high-contrast-color-scheme-changed

请改用 nativeTheme 模块上的新 updated 事件。

¥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', () => { /* ... */ })

已弃用：systemPreferences 中的方法​

¥Deprecated: methods in systemPreferences

以下 systemPreferences 方法已被弃用：

¥The following systemPreferences methods have been deprecated:

  • systemPreferences.isDarkMode()

  • systemPreferences.isInvertedColorScheme()

  • systemPreferences.isHighContrastColorScheme()

请改用以下 nativeTheme 属性：

¥Use the following nativeTheme properties instead:

  • 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

计划中的重大 API 更改 (7.0)​

¥Planned Breaking API Changes (7.0)

已弃用：Atom.io 节点标头 URL​

¥Deprecated: Atom.io Node Headers URL

这是在 .npmrc 文件中指定为 disturl 或在构建原生 Node 模块时指定为 --dist-url 命令行标志的 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.

已弃用：https://atom.io/download/electron

¥Deprecated: https://atom.io/download/electron

用。。。来代替：https://electron.nodejs.cn/headers

¥Replace with: https://electron.nodejs.cn/headers

API 更改：session.clearAuthCache() 不再接受选项​

¥API Changed: session.clearAuthCache() no longer accepts options

session.clearAuthCache API 不再接受清除内容的选项，而是无条件清除整个缓存。

¥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 更改：powerMonitor.querySystemIdleState 现在是 powerMonitor.getSystemIdleState​

¥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 更改：powerMonitor.querySystemIdleTime 现在是 powerMonitor.getSystemIdleTime​

¥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 更改：webFrame.setIsolatedWorldInfo 取代单独的方法​

¥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'
  })

删除：getBlinkMemoryInfo 的 marked 属性​

¥Removed: marked property on getBlinkMemoryInfo

此属性在 Chromium 77 中被删除，因此不再可用。

¥This property was removed in Chromium 77, and as such is no longer available.

行为改变：<input type="file"/> 的 webkitdirectory 属性现在列出目录内容​

¥Behavior Changed: webkitdirectory attribute for <input type="file"/> now lists directory contents

HTML 文件输入上的 webkitdirectory 属性允许他们选择文件夹。Electron 的早期版本有一个不正确的实现，其中输入的 event.target.files 返回 FileList，而 FileList 返回与所选文件夹对应的 File。

¥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.

从 Electron 7 开始，FileList 现在是文件夹中包含的所有文件的列表，类似于 Chrome、Firefox 和 Edge (MDN 文档链接)。

¥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

在 Electron <=6 中，这将返回 FileList 和 File 对象：

¥In Electron <=6, this would return a FileList with a File object for:

path/to/folder

在 Electron 7 中，现在返回 FileList 和 File 对象：

¥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

请注意，webkitdirectory 不再公开所选文件夹的路径。如果你需要所选文件夹的路径而不是文件夹内容，请参阅 dialog.showOpenDialog API (link)。

¥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 更改：基于回调的 promise 化 API 版本​

¥API Changed: Callback-based versions of promisified APIs

Electron 5 和 Electron 6 引入了现有异步 API 的基于 Promise 的版本，并弃用了旧的、基于回调的对应版本。在 Electron 7 中，所有已弃用的基于回调的 API 现已删除。

¥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.

这些函数现在只返回 Promise：

¥These functions now only return Promises:

  • app.getFileIcon() #15742

  • app.dock.show() #16904

  • contentTracing.getCategories() #16583

  • contentTracing.getTraceBufferUsage() #16600

  • contentTracing.startRecording() #16584

  • contentTracing.stopRecording() #16584

  • contents.executeJavaScript() #17312

  • cookies.flushStore() #16464

  • cookies.get() #16464

  • cookies.remove() #16464

  • cookies.set() #16464

  • debugger.sendCommand() #16861

  • dialog.showCertificateTrustDialog() #17181

  • inAppPurchase.getProducts() #17355

  • inAppPurchase.purchaseProduct()#17355

  • netLog.stopLogging() #16862

  • session.clearAuthCache() #17259

  • session.clearCache() #17185

  • session.clearHostResolverCache() #17229

  • session.clearStorageData() #17249

  • session.getBlobData() #17303

  • session.getCacheSize() #17185

  • session.resolveProxy() #17222

  • session.setProxy() #17222

  • shell.openExternal() #16176

  • webContents.loadFile() #15855

  • webContents.loadURL() #15855

  • webContents.hasServiceWorker() #16535

  • webContents.printToPDF() #16795

  • webContents.savePage() #16742

  • webFrame.executeJavaScript() #17312

  • webFrame.executeJavaScriptInIsolatedWorld() #17312

  • webviewTag.executeJavaScript() #17312

  • win.capturePage() #15743

这些函数现在有两种形式：同步和基于 Promise 的异步：

¥These functions now have two forms, synchronous and Promise-based asynchronous:

  • dialog.showMessageBox()/dialog.showMessageBoxSync() #17298

  • dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973

  • dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054

计划中的重大 API 更改 (6.0)​

¥Planned Breaking API Changes (6.0)

API 更改：win.setMenu(null) 现在是 win.removeMenu()​

¥API Changed: win.setMenu(null) is now win.removeMenu()

// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()

API 更改：渲染器进程中的 electron.screen 应该通过 remote 访问​

¥API Changed: electron.screen in the renderer process should be accessed via remote

// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen

API 更改：沙盒渲染器中的 require()ing 节点内置不再隐式加载 remote 版本​

¥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')

已弃用：powerMonitor.querySystemIdleState 替换为 powerMonitor.getSystemIdleState​

¥Deprecated: powerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState

// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)

已弃用：powerMonitor.querySystemIdleTime 替换为 powerMonitor.getSystemIdleTime​

¥Deprecated: powerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime

// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()

已弃用：不再需要 app.enableMixedSandbox()​

¥Deprecated: app.enableMixedSandbox() is no longer needed

// Deprecated
app.enableMixedSandbox()

现在默认启用混合沙盒模式。

¥Mixed-sandbox mode is now enabled by default.

已弃用：Tray.setHighlightMode​

¥Deprecated: Tray.setHighlightMode

在 macOS Catalina 下，我们之前的 Tray 实现中断了。Apple 的原生替代品不支持更改高亮行为。

¥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.

计划中的重大 API 更改 (5.0)​

¥Planned Breaking API Changes (5.0)

默认更改：nodeIntegration 和 webviewTag 默认为 false，contextIsolation 默认为 true​

¥Default Changed: nodeIntegration and webviewTag default to false, contextIsolation defaults to true

以下 webPreferences 选项默认值已弃用，取而代之的是下面列出的新默认值。

¥The following webPreferences option default values are deprecated in favor of the new defaults listed below.

属性已弃用的默认值新默认值
contextIsolationfalsetrue
nodeIntegrationtruefalse
webviewTag如果设置则为 nodeIntegration，否则为 truefalse

例如。重新启用 webviewTag

¥E.g. Re-enabling the webviewTag

const w = new BrowserWindow({
  webPreferences: {
    webviewTag: true
  }
})

行为改变：通过 nativeWindowOpen 打开的子窗口中的 nodeIntegration​

¥Behavior Changed: nodeIntegration in child windows opened via nativeWindowOpen

使用 nativeWindowOpen 选项打开的子窗口将始终禁用 Node.js 集成，除非 nodeIntegrationInSubFrames 是 true。

¥Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.

API 更改：现在必须在应用准备好之前完成注册特权方案​

¥API Changed: Registering privileged schemes must now be done before app ready

渲染器进程 API webFrame.registerURLSchemeAsPrivileged 和 webFrame.registerURLSchemeAsBypassingCSP 以及浏览器进程 API protocol.registerStandardSchemes 已被删除。添加了新的 API protocol.registerSchemesAsPrivileged，用于注册具有所需权限的自定义方案。在应用准备就绪之前，需要注册自定义方案。

¥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.setIsolatedWorld* 替换为 webFrame.setIsolatedWorldInfo​

¥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 更改：webFrame.setSpellCheckProvider 现在采用异步回调​

¥API Changed: webFrame.setSpellCheckProvider now takes an asynchronous callback

spellCheck 回调现在是异步的，并且 autoCorrectWord 参数已被删除。

¥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 更改：webContents.getZoomLevel 和 webContents.getZoomFactor 现在同步​

¥API Changed: webContents.getZoomLevel and webContents.getZoomFactor are now synchronous

webContents.getZoomLevel 和 webContents.getZoomFactor 不再接受回调参数，而是直接返回数值。

¥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)

计划中的重大 API 更改 (4.0)​

¥Planned Breaking API Changes (4.0)

以下列表包括 Electron 4.0 中的重大 API 更改。

¥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​

// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()

app.getGPUInfo​

app.getGPUInfo('complete')
// Now behaves the same with `basic` on macOS
app.getGPUInfo('basic')

win_delay_load_hook​

为 Windows 构建原生模块时，模块的 binding.gyp 中的 win_delay_load_hook 变量必须为 true（这是默认值）。如果此钩子不存在，则原生模块将无法在 Windows 上加载，并显示类似 Cannot find module 的错误消息。有关更多信息，请参阅 原生模块指南。

¥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.

删除：IA32 Linux 支持​

¥Removed: IA32 Linux support

Electron 18 将不再在 32 位 Linux 系统上运行。请参阅 停止支持 32 位 Linux 了解更多信息。

¥Electron 18 will no longer run on 32-bit Linux systems. See discontinuing support for 32-bit Linux for more information.

重大 API 更改 (3.0)​

¥Breaking API Changes (3.0)

以下列表包括 Electron 3.0 中的重大 API 更改。

¥The following list includes the breaking API changes in Electron 3.0.

app​

// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()

// Deprecated
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​

// Deprecated
clipboard.readRtf()
// Replace with
clipboard.readRTF()

// Deprecated
clipboard.writeRtf()
// Replace with
clipboard.writeRTF()

// Deprecated
clipboard.readHtml()
// Replace with
clipboard.readHTML()

// Deprecated
clipboard.writeHtml()
// Replace with
clipboard.writeHTML()

crashReporter​

// Deprecated
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  autoSubmit: true
})
// Replace with
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  uploadToServer: true
})

nativeImage​

// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
  scaleFactor: 1.0
})

process​

// Deprecated
const info = process.getProcessMemoryInfo()

screen​

// Deprecated
screen.getMenuBarHeight()
// Replace with
screen.getPrimaryDisplay().workArea

session​

// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
  callback(0)
})

Tray​

// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')

// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')

webContents​

// Deprecated
webContents.openDevTools({ detach: true })
// Replace with
webContents.openDevTools({ mode: 'detach' })

// Removed
webContents.setSize(options)
// There is no replacement for this API

webFrame​

// Deprecated
webFrame.registerURLSchemeAsSecure('app')
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

// Deprecated
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

<webview>​

// Removed
webview.setAttribute('disableguestresize', '')
// There is no replacement for this API

// Removed
webview.setAttribute('guestinstance', instanceId)
// There is no replacement for this API

// Keyboard listeners no longer work on webview tag
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node 标头 URL​

¥Node Headers URL

这是在 .npmrc 文件中指定为 disturl 或在构建原生 Node 模块时指定为 --dist-url 命令行标志的 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.

已弃用：https://atom.io/download/atom-shell

¥Deprecated: https://atom.io/download/atom-shell

用。。。来代替：https://atom.io/download/electron

¥Replace with: https://atom.io/download/electron

重大 API 更改 (2.0)​

¥Breaking API Changes (2.0)

以下列表包括 Electron 2.0 中的重大 API 更改。

¥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)
// Removed
menu.popup(browserWindow, 100, 200, 2)
// Replaced with
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage​

// Removed
nativeImage.toPng()
// Replaced with
nativeImage.toPNG()

// Removed
nativeImage.toJpeg()
// Replaced with
nativeImage.toJPEG()

process​

  • process.versions.electron 和 process.version.chrome 将设为只读属性，以便与 Node 设置的其他 process.versions 属性保持一致。

    ¥process.versions.electron and process.version.chrome will be made read-only properties for consistency with the other process.versions properties set by Node.

webContents​

// Removed
webContents.setZoomLevelLimits(1, 2)
// Replaced with
webContents.setVisualZoomLevelLimits(1, 2)

webFrame​

// Removed
webFrame.setZoomLevelLimits(1, 2)
// Replaced with
webFrame.setVisualZoomLevelLimits(1, 2)

<webview>​

// Removed
webview.setZoomLevelLimits(1, 2)
// Replaced with
webview.setVisualZoomLevelLimits(1, 2)

重复的 ARM 资源​

¥Duplicate ARM Assets

每个 Electron 版本都包含两个相同的 ARM 版本，但文件名略有不同，例如 electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip。添加带有 v7l 前缀的资源是为了向用户阐明它支持哪个 ARM 版本，并消除它与未来可能生成的 armv6l 和 arm64 资源的歧义。

¥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.

不带前缀的文件仍在发布，以避免破坏可能使用该文件的任何设置。从 2.0 开始，无前缀的文件将不再发布。

¥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.

详情请参见 6986 和 7189。

¥For details, see 6986 and 7189.