重大更改

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

  • API 更改：已更改的 API 会以某种方式使未更新的代码必定抛出异常。
  • 行为改变：Electron 的行为已经改变，但并不一定抛出相应的异常。
  • 默认值更改：依赖于默认值的代码的行为可能被破坏，但不保证会抛出相应的异常。 您可以通过显式指定该值的方式恢复旧的默认行为。
  • 已废弃：该 API 已标记为废弃。 该 API 依旧可正常运作，但会抛出已废弃警告，并在将来会移除。
  • 已移除：该 API 或功能已移除，Electron团队不再对此提供支持。

Removed: Windows 7 / 8 / 8.1 support

Windows 7, Windows 8, and Windows 8.1 are no longer supported. Electron follows the planned Chromium deprecation policy, which will .

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-* 事件

在 BrowserWindow 上已弃用的 scroll-touch-begin、scroll-touch-end 和 scroll-touch-edge 事件已被删除。 Instead, use the newly available on WebContents.

已移除：webContents.incrementCapturerCount(stayHidden, stayAwake)

The webContents.incrementCapturerCount(stayHidden, stayAwake) function has been removed. 当页面捕获完成时，它现在由 webContents.capturePage 自动处理。

  1. const w = new BrowserWindow({ show: false })
  3. // Removed in Electron 23
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // Replace with
  11. w.capturePage().then(image => {
  12.   console.log(image.toDataURL())
  13. })

已移除：webContents.decrementCapturerCount(stayHidden, stayAwake)

The webContents.decrementCapturerCount(stayHidden, stayAwake) function has been removed. 当页面捕获完成时，它现在由 webContents.capturePage 自动处理。

  1. const w = new BrowserWindow({ show: false })
  3. // Removed in Electron 23
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // Replace with
  11. w.capturePage().then(image => {
  12.   console.log(image.toDataURL())
  13. })

计划重写的 API (22.0)

已废弃：webContents.incrementCapturerCount(stayHidden, stayAwake)

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

  1. const w = new BrowserWindow({ show: false })
  3. // Removed in Electron 23
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // Replace with
  11. w.capturePage().then(image => {
  12.   console.log(image.toDataURL())
  13. })

已废弃：webContents.decrementCapturerCount(stayHidden, stayAwake)

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

  1. const w = new BrowserWindow({ show: false })
  3. // Removed in Electron 23
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // Replace with
  11. w.capturePage().then(image => {
  12.   console.log(image.toDataURL())
  13. })

已废弃: WebContents new-window 事件

WebContents 中的 new-window 事件已经被废弃。 已弃用：webContents.setWindowOpenHandler()。

  1. // Removed in Electron 22
  2. webContents.on('new-window', (event) => {
  3.   event.preventDefault()
  4. })
  6. // Replace with
  7. webContents.setWindowOpenHandler((details) => {
  8.   return { action: 'deny' }
  9. })

已废弃：Browserwindow scroll-touch-* 事件

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

  1. // Deprecated
  2. win.on('scroll-touch-begin', scrollTouchBegin)
  3. win.on('scroll-touch-edge', scrollTouchEdge)
  4. win.on('scroll-touch-end', scrollTouchEnd)
  6. // Replace with
  7. win.webContents.on('input-event', (_, event) => {
  8.   if (event.type === 'gestureScrollBegin') {
  9.     scrollTouchBegin()
  10.   } else if (event.type === 'gestureScrollUpdate') {
  11.     scrollTouchEdge()
  12.   } else if (event.type === 'gestureScrollEnd') {
  13.     scrollTouchEnd()
  14.   }
  15. })

计划重写的 API (21.0)

Behavior Changed: V8 Memory Cage enabled

The V8 memory cage has been enabled, which has implications for native modules which wrap non-V8 memory with ArrayBuffer or Buffer. See the for more details.

API Changed: webContents.printToPDF()

webContents.printToPDF() has been modified to conform to 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.

参数更改

  • pageRanges

参数移除

  • printSelectionOnly
  • marginsType
  • headerFooter
  • scaleFactor

参数添加

  • headerTemplate
  • footerTemplate
  • displayHeaderFooter
  • margins
  • scale
  • preferCSSPageSize
  1. // Main process
  2. const { webContents } = require('electron')
  4. webContents.printToPDF({
  5.   landscape: true,
  6.   displayHeaderFooter: true,
  7.   printBackground: true,
  8.   scale: 2,
  9.   pageSize: 'Ledger',
  10.   margins: {
  11.     top: 2,
  12.     bottom: 2,
  13.     left: 2,
  14.     right: 2
  15.   },
  16.   pageRanges: '1-5, 8, 11-13',
  17.   headerTemplate: '<h1>Title</h1>',
  18.   footerTemplate: '<div><span class="pageNumber"></span></div>',
  19.   preferCSSPageSize: true
  20. }).then(data => {
  21.   fs.writeFile(pdfPath, data, (error) => {
  22.     if (error) throw error
  23.     console.log(`Wrote PDF successfully to ${pdfPath}`)
  24.   })
  25. }).catch(error => {
  26.   console.log(`Failed to write PDF to ${pdfPath}: `, error)
  27. })

计划重写的 API (20.0)

默认值被更改：默认情况下，渲染器不为 nodeIntegration: true 将进行沙盒处理

之前, 指定预加载脚本的渲染器默认不启用沙盒。 这意味着默认情况下，预加载脚本可以访问Node.js。 在 Electron 20中，此默认值将被更改。 从Electron 20开始，渲染器 默认情况下会被沙盒化，除非指定了 nodeIntegration: true 或 sandbox: false 。

如果预加载脚本不依赖于 Node，则无需执行任何操作。 如果 preload 脚本依赖于 Node，请重构代码，或从渲染器中删除 Node 用法 ，或者显式指定相关渲染器 sandbox: false 。

已删除：Linux 上的 skipTaskbar

在 X11上, skipTaskbar 向 X11 窗口管理器发送一条 _NET_WM_STATE_SKIP_TASKBAR 消息。 Wayland没有与其一致的功能，并且已知的 变通办法具有不可接受的理由(如，在GNOME中Window.is_skip_taskbar 需要不安全模式)，因此Electron无法在Linux上支持此功能。

API Changed: session.setDevicePermissionHandler(handler)

当使用 session.setDevicePermissionHandler(handler) 时，调用的处理程序对其参数进行了更改。 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)

已删除：IA32 Linux 二进制文件

这是由于Chromium 102.0.4999.0放弃了对IA32 Linux的支持。 因此， 的支持。

计划重写的 API (18.0)

已移除： nativeWindowOpen

在 Electron 15之前， window.open 默认使用 BrowserWindowProxy。 This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. 自 Electron 15 起, nativeWindowOpen 将默认启用。

更多详细信息: window.open

计划重写的 API (17.0)

已移除：渲染器中的 desktopCapturer.getSources

desktopCapturer.getSources API 现在仅在主进程中可用。 为了提高Electron 应用程序在默认情况下的安全性，已对此做了修改。

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

  1. // 主进程
  2. const { ipcMain, desktopCapturer } = require('electron')
  4. ipcMain.handle(
  5.   'DESKTOP_CAPTURER_GET_SOURCES',
  6.   (event, opts) => desktopCapturer.getSources(opts)
  7. )
  1. // 渲染器进程
  2. const { ipcRenderer } = require('electron')
  4. const desktopCapturer = {
  5.   getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
  6. }

然而，您应该考虑进一步限制返回到 渲染器的信息； 例如向用户显示源选择器并只 返回选定的源。

已废弃：nativeWindowOpen

在 Electron 15之前， window.open 默认使用 BrowserWindowProxy。 This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. 自 Electron 15 起, nativeWindowOpen 将默认启用。

更多详细信息: window.open

Behavior Changed: crashReporter implementation switched to Crashpad on Linux

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

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

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

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

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

计划重写的 API (15.0)

默认更改： nativeWindowOpen 默认为 true

在 Electron 15之前， window.open 默认使用 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.

更多详细信息:

计划重写的 API (14.0)

Removed: remote module

remote 模块在 Electron 12 废弃，并将在 Electron 14 被移除. 由@electronic/remote 模块替代。

  1. // 在 Electron 12 废除:
  2. const { BrowserWindow } = require('electron').remote
  1. // 替换为：
  2. const { BrowserWindow } = require('@electron/remote')
  4. require('@electron/remote/main').initialize()

已移除： app.allowRendererProcessReuse

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

For more detailed information see #18397.

Removed: Browser Window Affinity

构建新的 BrowserWindow 对象时的 affinity 选项将会被删除, 这一点将作为我们计划的一部分，以更紧密地与Chromium的流程模型保持一致，以实现安全性，高性能和可维护性。

For more detailed information see #18397.

API 更改： window.open()

可选参数 frameName 将不再设置窗口的标题。 该功能现在遵循 原生文档 中的约束，由名为 windowName 的参数控制。

如果您正在使用此参数来设置窗口的标题，您可以使用 。

已移除： worldSafeExecuteJavaScript

在 Electron 14, worldSafeExecuteJavaScript 将被移除。 除此之外没有其他方式，请保证您的代码中包含该属性。 Electron 12中默认启用该属性。 12.

若您使用了 webFrame.executeJavaScript 或 webFrame.executeJavaScriptInIsolatedWorld，这个改动会对您造成影响。 您将需要确保这些方法中任何一种返回的值都被 支持，因为这些方法使用相同的值传递语意。

Removed: BrowserWindowConstructorOptions inheriting from parent windows

Prior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. 从 Electron 14开始，此行为已被删除， 窗口将不会继承他们父窗口的任何 BrowserWindow constructor 选项。

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

  1. webContents.setWindowOpenHandler((details) => {
  2.   return {
  3.     action: 'allow',
  4.     overrideBrowserWindowOptions: {
  5.       // ...
  6.     }
  7.   }
  8. })

已移除： additionalFeatures

  1. // Removed in Electron 14
  2. // Triggered by window.open('...', '', 'my-key')
  3. webContents.on('did-create-window', (window, details) => {
  4.   if (details.additionalFeatures.includes('my-key')) {
  5.     // ...
  6.   }
  7. })
  9. // Replace with
  10. webContents.on('did-create-window', (window, details) => {
  11.   if (details.options['my-key']) {
  12.     // ...
  13.   }
  14. })

计划重写的 API (13.0)

API 更改： session.setPermissionCheckHandler(handler)

handler 方法的第一个参数曾是 webContents，但现在可以为 null。 为正确响应权限检查，您需要使用requestingOrigin、embeddingOrigin 和 securityOrigin 这些属性。 因为 webContents 现在可能为 null，您不应当依赖此参数。

  1. // 旧代码
  2. session.setPermissionCheckHandler((webContents, permission) => {
  3.   if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
  4.     return true
  5.   }
  6.   return false
  7. })
  9. // 变更为
  11.   if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
  12.     return true
  13.   }
  14.   return false
  15. })

已移除：shell.moveItemToTrash()

已废弃的同步方法 shell.moveItemToTrash() 已移除。 作为替代，您应当使用异步的 shell.trashItem()。

  1. // 在 Electron 13 移除
  2. shell.moveItemToTrash(path)
  3. // 替换为
  4. shell.trashItem(path).then(/* ... */)

已移除： BrowserWindow 扩展 API

移除已弃用的扩展 API：

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

改为使用 session API：

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
  1. // 在 Electron 13 移除
  2. BrowserWindow.addExtension(path)
  3. BrowserWindow.addDevToolsExtension(path)
  4. // 替换为
  5. session.defaultSession.loadExtension(path)
  1. // 在 Electron 13 移除
  2. BrowserWindow.removeExtension(name)
  3. BrowserWindow.removeDevToolsExtension(name)
  4. // 替换为
  5. session.defaultSession.removeExtension(extension_id)
  1. // 在 Electron 13 移除
  2. BrowserWindow.getExtensions()
  3. BrowserWindow.getDevToolsExtensions()
  4. // 替换为
  5. session.defaultSession.getAllExtensions()

已移除： systemPreferences 中的方法

systemPreferences 方法已经被废弃：

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

使用 nativeTheme 属性作为替代：

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
  1. // 在 Electron 13 移除
  2. systemPreferences.isDarkMode()
  3. // 替换为
  4. nativeTheme.shouldUseDarkColors
  6. // 在 Electron 13 移除
  7. systemPreferences.isInvertedColorScheme()
  8. // 替换为
  9. nativeTheme.shouldUseInvertedColorScheme
  11. // 在 Electron 13 移除
  12. systemPreferences.isHighContrastColorScheme()
  13. // 替换为
  14. nativeTheme.shouldUseHighContrastColors

已废弃: WebContents new-window 事件

WebContents 中的 new-window 事件已经被废弃。 已弃用：webContents.setWindowOpenHandler()。

  1. // 在 Electron 13 废弃
  2. webContents.on('new-window', (event) => {
  3.   event.preventDefault()
  4. })
  6. // 替换为
  7. webContents.setWindowOpenHandler((details) => {
  8.   return { action: 'deny' }
  9. })

计划重写的 API (12.0)

已移除：Pepper Flash 支持

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

默认更改： worldSafeExecuteJavaScript 默认为 true

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

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

Default Changed: contextIsolation defaults to true

In Electron 12, contextIsolation will be enabled by default. 要恢复 上一个行为， contextIsolation: false 必须在 Web 首选项中指定。

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

另一个含义是 require() 不能在 renderer process 中使用，除非 nodeIntegration 是 true 和 contextIsolation 是 false.

更多信息请参阅：

Removed: crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory 方法已被删除。 这个方法 应该被 app.getPath('crashDumps')替换。

  1. // 在 Electron 12 移除
  2. crashReporter.getCrashesDirectory()
  3. // 替换为
  4. app.getPath('crashDumps')

已移除：渲染进程中的 crashReporter 方法

crashReporter 方法在渲染进程中不再能使用：

  • crashReporter.start
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

它们只应从主要进程中调用。

更多详细信息请访问 #23265

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

crashReporter.start 中的 compress 选项的默认值已经从 false 改为 true。 这意味着崩溃 dumps 将使用 Content-Encoding: gzip header，上传到崩溃服务器，并进行压缩。

如果 crash 服务器不支持压缩负载，则可以通过在 crash reporter 选项中指定 { compress: false } 来 关闭压缩。

remote 模块在 Electron 12 废弃，并将在 Electron 14 被移除 由 模块替代。

  1. // 在 Electron 12 废除:
  2. const { BrowserWindow } = require('electron').remote
  1. // 替换为：
  2. const { BrowserWindow } = require('@electron/remote')
  4. // 在主进程中：
  5. require('@electron/remote/main').initialize()

已废弃：shell.moveItemToTrash()

新的异步shell.trashItem()方法替代了同步的shell.moveItemToTrash()方法。

  1. // 在 Electron 12 废弃
  2. shell.moveItemToTrash(path)
  3. // 替换为
  4. shell.trashItem(path).then(/* ... */)

计划重写的 API (11.0)

移除: BrowserView 中的 BrowserView.{destroy, fromId, fromWebContents, getAllViews} 和 id 属性

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

更多信息见 。

计划重写的 API (10.0)

已废弃：crashReporter.start() 中的 companyName 参数

crashReporter.start() 中的 companyName 参数之前是必选的，现在是可选的，并且在未来将会被废弃。 如果要以不推荐的方式获得相同的行为，可以在 globalExtra 中传递 companyName 值。

  1. // 在 Electron 10 废除
  2. crashReporter.start({ companyName: 'Umbrella Corporation' })
  3. // 替换为
  4. crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

已废弃：crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory 方法已经被废除。 这个方法 应该被 app.getPath('crashDumps')替换。

  1. // 在 Electron 10 废除
  2. crashReporter.getCrashesDirectory()
  3. // 替换为
  4. app.getPath('crashDumps')

已废弃：渲染进程中的 crashReporter 方法

从 renderer process 调用 crashReporter，已经被废弃

  • crashReporter.start
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

在渲染器的 crashReporter 模块中，未弃用的方法是 addExtraParameter、 removeExtraParameter 和 getParameters。

当从主要进程调用时，上述所有方法均未被弃用。

更多详细信息请访问 #23265

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

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

默认更改： enableRemoteModule 默认为 false

在 Electron 9，如果不在 WebPreferences 中显式开启 enableRemoteModule 参数，就使用 remote 模块，将会开始发出警告。 在 Electron 10 中，remote 模块默认处于禁用状态。 如果要使用 remote 模块，必须在 WebPreferences 中指定 enableRemoteModule: true :

我们 。

protocol.unregisterProtocol

protocol.uninterceptProtocol

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

  1. // 已废弃
  2. protocol.unregisterProtocol(scheme, () => { /* ... */ })
  3. // 替换为
  4. protocol.unregisterProtocol(scheme)

protocol.registerFileProtocol

protocol.registerBufferProtocol

protocol.registerStringProtocol

protocol.registerHttpProtocol

protocol.registerStreamProtocol

protocol.interceptFileProtocol

protocol.interceptStringProtocol

protocol.interceptBufferProtocol

protocol.interceptHttpProtocol

protocol.interceptStreamProtocol

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

  1. // 已废弃
  2. protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
  3. // 替换为
  4. protocol.registerFileProtocol(scheme, handler)

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

protocol.isProtocolHandled

此 API 已废弃，用户应该使用 protocol.isProtocolRegistered 和 protocol.isProtocolIntercepted。

  1. // 废弃
  2. protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
  3. // 替换为
  4. const isRegistered = protocol.isProtocolRegistered(scheme)
  5. const isIntercepted = protocol.isProtocolIntercepted(scheme)

默认更改：默认在 renderer process 中禁用加载 non-context-aware native modules

从Electron 9开始，我们不允许在 renderer process 加载 non-context-aware native modules。 这是为了提高 Electron 作为一个项目的安全性、性能性和维护性。

如果这对你有影响，你可以临时将 app.allowRendererProcessReuse 设置为 false，这将恢复到旧的行为。 在 Electron 11 之前，此标志只是一个选项，因此你应该计划更换你的 native modules 模块，已进行 context aware。

For more detailed information see .

已废弃： BrowserWindow 扩展 API

以下扩展 APIs 已废弃:

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

改为使用 session API：

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
  1. // 在 Electron 9 废弃
  2. BrowserWindow.addExtension(path)
  3. BrowserWindow.addDevToolsExtension(path)
  4. // 替换为
  5. session.defaultSession.loadExtension(path)
  1. // 在 Electron 9 废弃
  2. BrowserWindow.removeExtension(name)
  3. BrowserWindow.removeDevToolsExtension(name)
  4. // 替换为
  5. session.defaultSession.removeExtension(extension_id)
  1. // 在 Electron 9 废弃
  2. BrowserWindow.getExtensions()
  3. BrowserWindow.getDevToolsExtensions()
  4. // 替换为
  5. session.defaultSession.getAllExtensions()

已移除： <webview>.getWebContents()

此API在 Electron 8.0中被废弃，现已删除。

  1. // 在 Electron 9.0 移除
  2. webview.getWebContents()
  3. // 替换为
  4. const { remote } = require('electron')
  5. remote.webContents.fromId(webview.getWebContentsId())

已移除：webFrame.setLayoutZoomLevelLimits()

Chromium 已经取消了对更改布局缩放级别限制的支持，它超出了 Electron 维护它的能力。 此函数在 Electron 8.x 废弃，并将在 Electron 9.x 被移除。 布局缩放级别限制现在已固定为最小 0.25 最大 5.0，定义在:

行为改变: 通过 IPC 发送非 JS 对象，现在将引发异常

在 Electron 9 中，旧的序列化算法已被删除，并且此类不可序列化的对象现在将会抛出一个“object could not be cloned”（对象无法被克隆） 错误。

API 变化：shell.openItem 变化为 shell.openPath

shell.openItem API 已被替换成异步的 shell.openPath API。 你可以在这里查看原始 API 提案和推理

计划重写的 API (8.0)

行为改变：通过 IPC 发送的值现在已经使用结构化克隆（Structured Clone Algorithm）算法进行序列化。

用于序列化通过 IPC 发送的对象（通过 ipcRenderer.send、ipcRenderer.sendSync、WebContents.send 以及相关方法）已经从自定义算法切换到 V8 内置的 ，和 postMessage 使用序列化消息的算法相同。 这将为大型消息带来了 2 倍的性能改进，但也带来一些行为上的重大变化。

  • 通过 IPC 发送的 Function、Promise、WeakMaps、WeakSets 或者包含任何此类值的对象现在将引发异常，而不是静默地将函数转换为 undefined
  1. // 之前:
  2. ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
  3. // => results in { value: 3 } arriving in the main process
  5. // 从 Electron 8 开始:
  6. ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
  7. // => throws Error("() => {} could not be cloned.")
  • NaN、Infinity、-Infinity 现在将被正确的序列化，而不是转换为 null。
  • 包含循环引用的对象现在将被正确的序列化，而不是转换为 null。
  • Set、Map、Error、RegExp 值将被正确的序列化，而不是转换为 {}。
  • BigInt 值将被正确的序列化，而不是转换为 null。
  • Sparse 数组将按照本身去序列化，而不是转换为具有 null 的数组。
  • Date 对象将被转换成 Date 对象，而不是转换成 ISO 字符串表达形式。
  • Typed Arrays (such as Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.
  • Node.js Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:
  1. Buffer.from(value.buffer, value.byteOffset, value.byteLength)

Sending any objects that aren’t native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a ‘could not be cloned’ error.

已废弃： <webview>.getWebContents()

This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.

  1. // Deprecated
  2. webview.getWebContents()
  3. // Replace with
  4. const { remote } = require('electron')
  5. remote.webContents.fromId(webview.getWebContentsId())

然而，建议完全避免使用 remote 模块

  1. // main
  2. const { ipcMain, webContents } = require('electron')
  4. const getGuestForWebContents = (webContentsId, contents) => {
  5.   const guest = webContents.fromId(webContentsId)
  6.   if (!guest) {
  7.     throw new Error(`Invalid webContentsId: ${webContentsId}`)
  8.   }
  9.   if (guest.hostWebContents !== contents) {
  10.     throw new Error('Access denied to webContents')
  11.   }
  12.   return guest
  13. }
  15. ipcMain.handle('openDevTools', (event, webContentsId) => {
  16.   const guest = getGuestForWebContents(webContentsId, event.sender)
  17.   guest.openDevTools()
  18. })
  20. // renderer
  21. const { ipcRenderer } = require('electron')
  23. ipcRenderer.invoke('openDevTools', webview.getWebContentsId())

Deprecated: webFrame.setLayoutZoomLevelLimits()

Chromium 已经取消了对更改布局缩放级别限制的支持，它超出了 Electron 维护它的能力。 The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

Deprecated events in systemPreferences

systemPreferences 事件已经被废弃：

  • inverted-color-scheme-changed
  • high-contrast-color-scheme-changed

Use the new updated event on the nativeTheme module instead.

  1. // Deprecated
  2. systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
  3. systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
  5. // Replace with
  6. nativeTheme.on('updated', () => { /* ... */ })

已废弃：systemPreferences 中的方法

systemPreferences 方法已经被废弃：

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

使用 nativeTheme 属性作为替代：

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
  1. // 已废弃
  2. systemPreferences.isDarkMode()
  3. // 替换为
  4. nativeTheme.shouldUseDarkColors
  6. // 已废弃
  7. systemPreferences.isInvertedColorScheme()
  8. // 替换为
  9. nativeTheme.shouldUseInvertedColorScheme
  11. // 已废弃
  12. systemPreferences.isHighContrastColorScheme()
  13. // 替换为
  14. nativeTheme.shouldUseHighContrastColors

重大的API更新 (7.0)

Deprecated: Atom.io Node Headers URL

这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志. Both will be supported for the foreseeable future but it is recommended that you switch.

Deprecated:

Replace with: https://electronjs.org/headers

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

The session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.

  1. // Deprecated
  2. session.clearAuthCache({ type: 'password' })
  3. // Replace with
  4. session.clearAuthCache()

API Changed: powerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState

  1. // Removed in Electron 7.0
  2. powerMonitor.querySystemIdleState(threshold, callback)
  3. // Replace with synchronous API
  4. const idleState = powerMonitor.getSystemIdleState(threshold)

API Changed: powerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime

  1. // Removed in Electron 7.0
  2. powerMonitor.querySystemIdleTime(callback)
  3. // Replace with synchronous API
  4. const idleTime = powerMonitor.getSystemIdleTime()

API Changed: webFrame.setIsolatedWorldInfo replaces separate methods

  1. // Removed in Electron 7.0
  2. webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
  3. webFrame.setIsolatedWorldHumanReadableName(worldId, name)
  4. webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
  5. // Replace with
  6. webFrame.setIsolatedWorldInfo(
  7.   worldId,
  8.   {
  9.     securityOrigin: 'some_origin',
  10.     name: 'human_readable_name',
  11.     csp: 'content_security_policy'

Removed: marked property on getBlinkMemoryInfo

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

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

The webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.

As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge ().

As an illustration, take a folder with this structure:

  1. folder
  2. ├── file1
  3. ├── file2
  4. └── file3

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

  1. path/to/folder

In Electron 7, this now returns a FileList with a File object for:

  1. /path/to/folder/file3
  2. /path/to/folder/file2
  3. /path/to/folder/file1

Note that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.

These functions now only return Promises:

  • app.dock.show() #16904
  • contentTracing.getCategories()
  • contentTracking.getTraceBufferUs() #16600
  • contentTracing.startRecording()
  • contentTracing.stopRecording() #16584
  • contents.executeJavaScript()
  • cookies.flushStore() #16464
  • cookies.get()
  • cookies.remove() #16464
  • cookies.set()
  • debugger.sendCommand() #16861
  • dialog.showCertificateTrustDialog()
  • inAppPurchase.getProducts() #17355
  • inAppPurchase.purchaseProduct()
  • netLog.stopLogging() #16862
  • session.clearAuthCache()
  • session.clearCache() #17185
  • session.clearHostResolverCache()
  • session.clearStorageData() #17249
  • session.getBlobData()
  • session.getCacheSize() #17185
  • session.resolveProxy()
  • session.setProxy() #17222
  • shell.openExternal()
  • webContents.loadFile() #15855
  • webContents.loadURL()
  • webContents.hasServiceWorker() #16535
  • webContents.printToPDF()
  • webContents.savePage() #16742
  • webFrame.executeJavaScript()
  • webFrame.executeJavaScriptInIsolatedWorld() #17312
  • webviewTag.executeJavaScript()
  • win.capturePage() #15743

这些功能现在有两种形式，即同步和基于Promise的异步：

  • dialog.showMessageBox()/dialog.showMessageBoxSync()
  • dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973
  • dialog.showSaveDialog()/dialog.showSaveDialogSync()

重大的API更新 (6.0)

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

  1. // 不推荐
  2. win.setMenu(null)
  3. // 替换为
  4. win.removeMenu()

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

  1. // 不推荐
  2. require('electron').screen
  3. // 替换为
  4. require('electron').remote.screen

API Changed: require()ing node builtins in sandboxed renderers no longer implicitly loads the remote version

  1. // 不推荐
  2. require('child_process')
  3. // 替换为
  4. require('electron').remote.require('child_process')
  6. // 不推荐
  7. require('fs')
  8. // 替换为
  9. require('electron').remote.require('fs')
  11. // 不推荐
  12. require('os')
  13. // 替换为
  14. require('electron').remote.require('os')
  16. // 不推荐
  17. require('path')
  18. // 替换为
  19. require('electron').remote.require('path')

Deprecated: powerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState

  1. // 废弃
  2. powerMonitor.querySystemIdleState(threshold, callback)
  3. // 替换为 synchronous API
  4. const idleState = powerMonitor.getSystemIdleState(threshold)

Deprecated: powerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime

  1. // 废弃
  2. powerMonitor.querySystemIdleTime(callback)
  3. // 替换为 synchronous API
  4. const idleTime = powerMonitor.getSystemIdleTime()

Deprecated: app.enableMixedSandbox() is no longer needed

  1. // 废弃
  2. app.enableMixedSandbox()

混合沙盒模式已默认启用。

Deprecated: Tray.setHighlightMode

Under macOS Catalina our former Tray implementation breaks. Apple’s native substitute doesn’t support changing the highlighting behavior.

重大的API更新 (5.0)

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

不推荐使用以下 webPreferences 选项默认值，以支持下面列出的新默认值。

如下: 重新开启 webviewTag

  1. const w = new BrowserWindow({
  2.   webPreferences: {
  3.     webviewTag: true
  4.   }
  5. })

Behavior Changed: nodeIntegration in child windows opened via nativeWindowOpen

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

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

Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. 新的 API protocol.registerSchemeasviliged 已被添加，并用于注册具有必要权限的自定义 scheme。 自定义 scheme 需要在 app 触发 ready 事件之前注册。

已废弃: webFrame.setIsolatedWorld* 已替换为 webFrame.setIsolatedWorldInfo

  1. // 弃用
  2. webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
  3. webFrame.setIsolatedWorldHumanReadableName(worldId, name)
  4. webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
  5. // 替换为
  6. webFrame.setIsolatedWorldInfo(
  7.   worldId,
  8.   {
  9.     securityOrigin: 'some_origin',
  10.     name: 'human_readable_name',
  11.     csp: 'content_security_policy'
  12.   })

API Changed: webFrame.setSpellCheckProvider now takes an asynchronous callback

The spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.

  1. // Deprecated
  2. webFrame.setSpellCheckProvider('en-US', true, {
  3.   spellCheck: (text) => {
  4.     return !spellchecker.isMisspelled(text)
  5.   }
  6. })
  7. // Replace with
  8. webFrame.setSpellCheckProvider('en-US', {
  9.   spellCheck: (words, callback) => {
  10.     callback(words.filter(text => spellchecker.isMisspelled(text)))
  11.   }
  12. })

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

webContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.

  1. // 废弃
  2. webContents.getZoomLevel((level) => {
  3.   console.log(level)
  4. })
  5. // 替换成
  6. const level = webContents.getZoomLevel()
  7. console.log(level)
  1. // 废弃
  2. webContents.getZoomFactor((factor) => {
  3.   console.log(factor)
  4. })
  5. // 替换成
  6. const factor = webContents.getZoomFactor()
  7. console.log(factor)

计划重写的 API (4.0)

以下列表包含了Electron4.0中重大的API更新

app.makeSingleInstance

  1. // 已废弃
  2. app.makeSingleInstance((argv, cwd) => {
  3.   /* ... */
  4. })
  5. // 替换为
  6. app.requestSingleInstanceLock()
  7. app.on('second-instance', (event, argv, cwd) => {
  8.   /* ... */
  9. })

app.releaseSingleInstance

  1. // 废弃
  2. app.releaseSingleInstance()
  3. // 替换为
  4. app.releaseSingleInstanceLock()

app.getGPUInfo

  1. app.getGPUInfo('complete')
  2. // 现在的行为将与macOS下的`basic`设置一样
  3. app.getGPUInfo('basic')

win_delay_load_hook

在为 Windows 构建本机模块时，将使 win_delay_load_hook 变量值 位于 binding.gyp 模块，必须为 true (这是默认值)。 如果这个钩子 不存在，那么本机模块将无法在 Windows 上加载，并出现错误 消息如 无法找到模块。 See the native module guide for more.

移除: IA32 Linux 支持

Electron 18 将不再支持在 32 位 Linux 系统上运行。 有关详细信息，请参阅停止支持 32 位 Linux。

重大的API更新 (3.0)

以下包含了Electron 3.0中重大的API更新

app

  1. // 弃用
  2. app.getAppMemoryInfo()
  3. // 替换为
  4. app.getAppMetrics()
  6. // 弃用
  7. const metrics = app.getAppMetrics()
  8. const { memory } = metrics[0] // 弃用的属性

BrowserWindow

  1. // 已废弃
  2. const optionsA = { webPreferences: { blinkFeatures: '' } }
  3. const windowA = new BrowserWindow(optionsA)
  4. // 替换为
  5. const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
  6. const windowB = new BrowserWindow(optionsB)
  8. // 已废弃
  9. window.on('app-command', (e, cmd) => {
  10.   if (cmd === 'media-play_pause') {
  11.     // do something
  12.   }
  13. })
  14. // 替换为
  15. window.on('app-command', (e, cmd) => {
  16.   if (cmd === 'media-play-pause') {
  17.     // do something
  18.   }
  19. })

clipboard

  1. // 过时的
  2. clipboard.readRtf()
  3. // 替换为
  4. clipboard.readRTF()
  6. // 过时的
  7. clipboard.writeRtf()
  8. // 替换为
  9. clipboard.writeRTF()
  11. // 过时的
  12. clipboard.readHtml()
  13. // 替换为
  14. clipboard.readHTML()
  16. // 过时的
  17. clipboard.writeHtml()
  18. //替换为
  19. clipboard.writeHTML()

crashReporter

  1. // 过时的
  2. crashReporter.start({
  3.   companyName: 'Crashly',
  4.   submitURL: 'https://crash.server.com',
  5.   autoSubmit: true
  6. })
  7. // 替换为
  8. crashReporter.start({
  9.   companyName: 'Crashly',
  10.   submitURL: 'https://crash.server.com',
  11.   uploadToServer: true
  12. })

nativeImage

  1. // 弃用
  2. nativeImage.createFromBuffer(buffer, 1.0)
  3. // 替换为
  4. nativeImage.createFromBuffer(buffer, {
  5.   scaleFactor: 1.0
  6. })

process

  1. // 弃用
  2. const info = process.getProcessMemoryInfo()

screen

  1. // 弃用
  2. screen.getMenuBarHeight()
  3. // 替换为
  4. screen.getPrimaryDisplay().workArea

session

  1. // 弃用
  2. ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  3.   callback(true)
  4. })
  5. // 替换为
  6. ses.setCertificateVerifyProc((request, callback) => {
  7.   callback(0)
  8. })

Tray

  1. // 过时的
  2. tray.setHighlightMode(true)
  3. // 替换为
  4. tray.setHighlightMode('on')
  6. // 过时的
  7. tray.setHighlightMode(false)
  8. // 替换为
  9. tray.setHighlightMode('off')

webContents

  1. // 弃用
  2. webContents.openDevTools({ detach: true })
  3. // 替换为
  4. webContents.openDevTools({ mode: 'detach' })
  6. // 移除
  7. webContents.setSize(options)
  8. // 没有该API的替代

webFrame

  1. // 弃用
  2. webFrame.registerURLSchemeAsSecure('app')
  3. // 替换为
  4. protocol.registerStandardSchemes(['app'], { secure: true })
  6. // 弃用
  7. webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
  8. // 替换为
  9. protocol.registerStandardSchemes(['app'], { secure: true })

<webview>

  1. // 移除
  2. webview.setAttribute('disableguestresize', '')
  3. // 没有该API的替代
  5. // 移除
  6. webview.setAttribute('guestinstance', instanceId)
  7. // 没有该API的替代
  9. // 键盘监听器在webview标签中不再起效
  10. webview.onkeydown = () => { /* handler */ }
  11. webview.onkeyup = () => { /* handler */ }

Node Headers URL

这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志.

过时的:

替换为: https://atom.io/download/electron

以下包含了Electron 2.0中重大的API更新

BrowserWindow

  1. // 已废弃
  2. const optionsA = { titleBarStyle: 'hidden-inset' }
  3. const windowA = new BrowserWindow(optionsA)
  4. // 替换为
  5. const optionsB = { titleBarStyle: 'hiddenInset' }
  6. const windowB = new BrowserWindow(optionsB)

menu

  1. // 移除
  2. menu.popup(browserWindow, 100, 200, 2)
  3. // 替换为
  4. menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage

  1. // 移除
  2. nativeImage.toPng()
  3. // 替换为
  4. nativeImage.toPNG()
  6. // 移除
  7. nativeImage.toJpeg()
  8. // 替换为
  9. nativeImage.toJPEG()

process

  • process.versions.electron 和 process.version.chrome 将成为只读属性, 以便与其他 process.versions 属性由Node设置。

webContents

  1. // 移除
  2. webContents.setZoomLevelLimits(1, 2)
  3. // 替换为
  4. webContents.setVisualZoomLevelLimits(1, 2)

webFrame

  1. // 被废弃
  2. webFrame.setZoomLevelLimits(1, 2)
  3. // 替换为
  4. webFrame.setVisualZoomLevelLimits(1, 2)

<webview>

  1. // 移除
  2. webview.setZoomLevelLimits(1, 2)
  3. webview.setVisualZoomLevelLimits(1, 2)

每个 Electron 发布版本包含两个相同的ARM版本，文件名略有不同，如electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip 添加包含v7l前缀的资源向用户明确其支持的ARM版本，并消除由未来armv6l 和 arm64 资源可能产生的歧义。

为了防止可能导致安装器毁坏的中断，不带前缀的文件仍然将被发布。 从2.0版本起，不带前缀的文件将不再发布。

更多详细情况，查看 6986 和 。