重大更改

这里将记录重大更改,并在可能的情况下向JS代码添加弃用警告,在这更改之前至少会有一个重要版本.

重大更改的类型

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

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

计划重写的 API (27.0)

已移除：macOS 10.13 / 10.14 / 支援

macOS 10.13 (High Serria) 和 macOS 10.14 (Mojave) 不再支援Chromium.

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

弃用：ipcRenderer.sendTo()

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

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

已删除： systemPreferences 中的 color scheme 相关事件

以下 systemPreferences 事件已被删除：

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

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

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

已删除: webContents.getPrinters

webContents.getPrinters 方法已被删除。 使用webContents.getPrintersAsync代替。

  1. const w = new BrowserWindow({ show: false })
  3. // Removed
  4. console.log(w.webContents.getPrinters())
  5. // Replace with
  6. w.webContents.getPrintersAsync().then((printers) => {
  7.   console.log(printers)
  8. })

已删除：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance

方法 systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 已被删除，也包括属性 systemPreferences.appLevelAppearance。 请改用模块 nativeTheme。

  1. // Removed
  2. systemPreferences.getAppLevelAppearance()
  3. // Replace with
  4. nativeTheme.shouldUseDarkColors
  6. // Removed
  7. systemPreferences.appLevelAppearance
  8. // Replace with
  9. nativeTheme.shouldUseDarkColors
  11. // Removed
  12. systemPreferences.setAppLevelAppearance('dark')
  13. // Replace with
  14. nativeTheme.themeSource = 'dark'

已删除：systemPreferences.getColor 的 alternate-selected-control-text 值

systemPreferences.getColor 的 alternate-selected-control-text 值已被删除。 替换为 selected-content-background。

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

计划重写的 API (26.0)

弃用：webContents.getPrinters

webContents.getPrinters 方法已经被废除。 使用webContents.getPrintersAsync代替。

  1. const w = new BrowserWindow({ show: false })
  3. // 被弃用
  4. console.log(w.webContents.getPrinters())
  5. // 替换为
  6. w.webContents.getPrintersAsync().then((printers) => {
  7.   console.log(printers)
  8. })

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

方法systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 已被弃用，也包括属性 systemPreferences.appLevelAppearance。 请改用模块 nativeTheme。

  1. // Deprecated
  2. systemPreferences.getAppLevelAppearance()
  3. // Replace with
  4. nativeTheme.shouldUseDarkColors
  6. // Deprecated
  7. systemPreferences.appLevelAppearance
  8. // Replace with
  9. nativeTheme.shouldUseDarkColors
  11. // Deprecated
  12. systemPreferences.setAppLevelAppearance('dark')
  13. // Replace with
  14. nativeTheme.themeSource = 'dark'

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

systemPreferences.getColor 的 alternate-selected-control-text 值已被弃用。 替换为 selected-content-background。

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

计划重写的 API (25.0)

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

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

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

  1. // 在 Electron 25 中弃用
  2. protocol.registerBufferProtocol('some-protocol', () => {
  3.   callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') });
  4. });
  6. // 替代为
  7. protocol.handle('some-protocol', () => {
  8.   return new Response(
  9.     Buffer.from('<h5>Response</h5>'), // 也可以是 string 或 ReadableStream.
  10.     { headers: { 'content-type': 'text/html' } }
  11.   );
  12. })
  1. // 在 Electron 25 中弃用
  2. protocol.registerHttpProtocol('some-protocol', () => {
  3.   callback({ url: 'https://electronjs.org' });
  4. });
  6. // 替代为
  7. protocol.handle('some-protocol', () => {
  8.   return net.fetch('https://electronjs.org');
  9. })
  1. // 在 Electron 25 中弃用
  2. protocol.registerFileProtocol('some-protocol', () => {
  3.   callback({ filePath: '/path/to/my/file' });
  4. });
  6. // 替代为
  7. protocol.handle('some-protocol', () => {
  8.   return net.fetch('file:///path/to/my/file');
  9. })

弃用：BrowserWindow.setTrafficLightPosition(position)

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

  1. // 在 Electron 25 中弃用
  2. win.setTrafficLightPosition({ x: 10, y: 10 });
  3. win.setTrafficLightPosition({ x: 0, y: 0 });
  5. // 替代为
  6. win.setWindowButtonPosition({ x: 10, y: 10 });
  7. win.setWindowButtonPosition(null)

弃用：BrowserWindow.getTrafficLightPosition()

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

  1. // 在 Electron 24 中被移除
  2. const pos = win.getTrafficLightPosition()
  3. if (pos.x === 0 && pos.y === 0) {
  4.   // No custom position.
  5. }
  7. // Replace with
  8. const ret = win.getWindowButtonPosition()
  9. if (ret === null) {
  10.   // No custom position.
  11. }

计划重写的 API (24.0)

API Changed: nativeImage.createThumbnailFromPath(path, size)

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

更新行为：

  1. // 一张 128x128 的图片。
  2. const imagePath = path.join('path', 'to', 'capybara.png')
  4. // 放大较小的图像。
  5. const upSize = { width: 256, height: 256 }
  6. nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
  7.   console.log(result.getSize()) // { width: 256, height: 256 }
  8. })
  10. // 缩小更大的图像。
  11. const downSize = { width: 64, height: 64 }
  12. nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
  13.   console.log(result.getSize()) // { width: 64, height: 64 }
  14. })

以前的行为 (在 Windows 上)：

  1. // a 128x128 image
  2. const imagePath = path.join('path', 'to', 'capybara.png')
  3. const size = { width: 256, height: 256 }
  4. nativeImage.createThumbnailFromPath(imagePath, size).then(result => {
  5.   console.log(result.getSize()) // { width: 128, height: 128 }
  6. })

计划重写的 API (23.0)

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

可拖拉区域 (使用 CSS 属性 -webkit-app-region: drag) 的实现已经在 macOS 上改变了，以便使其与 Windows 和 Linux 保持一致。 以前，当 -webkit-app-region: no-drag 的区域与 -webkit-app-region: drag 区域重叠时， no-drag 区域总是优先于 macOS 的实现，而不论 CSS 层次。 也就是说，如果一个 drag 区域在一个 no-drag 区域以上，它将无法被拖动。 从 Electron 23 开始，一个位于 no-drag 上面的 drag 区域将会正确地执行该区域的拖拽效果。

此外， customButtonsOnHover BrowserWindow 属性先前创建了一个可拖动区域，区域内默认忽略了 -webkit-app-region 的 CSS 属性。 这个问题现已修复(见 #37210 供讨论)。

因此，如果你的 app 在 macOS 上使用了一个带有可拖动区域的无边框窗口。app 中可拖动的区域或许会在 Electron 23 中发生改变。

已移除：Windows 7 / 8 / 8.1 支持

Windows 7，Windows 8，Windows 8.1 不再支持。 Electron 遵循 Chromium 计划中的弃用政策，该政策将 [在 Chromium 109 中弃用 Windows 7 支持](https://support.google.com/chrome/thread/185534985/sunsetting-support-for-windows-7-8-8-1-in-early -2023?hl=en)。

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

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

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

  1. // 在 Electron 23.0 被移除
  2. win.on('scroll-touch-begin', scrollTouchBegin)
  3. win.on('scroll-touch-edge', scrollTouchEdge)
  4. win.on('scroll-touch-end', scrollTouchEnd)
  6. // 可替换为
  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. })

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

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

  1. const w = new BrowserWindow({ show: false })
  3. // 在 Electron 23 被移除
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // 可替换为
  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. // 在 Electron 23 被移除
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // 可替换为
  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. // 在 Electron 23 被移除
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // 可替换为
  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. // 在 Electron 23 被移除
  4. w.webContents.incrementCapturerCount()
  5. w.capturePage().then(image => {
  6.   console.log(image.toDataURL())
  7.   w.webContents.decrementCapturerCount()
  8. })
  10. // 可替换为
  11. w.capturePage().then(image => {
  12.   console.log(image.toDataURL())
  13. })

已废弃: WebContents new-window 事件

WebContents 中的 new-window 事件已经被废弃。 它被替换为 webContents.setWindowOpenHandler().

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

已移除： <webview> new-window 事件

new-window <webview> 事件已被移除。 没有直接替换的方案。

  1. // 在 Electron 22 中移除
  2. webview.addEventListener('new-window', (event) =>{})

docs/fiddles/ipc/webview-new-window (27.0.1)Open in Fiddle

  • child.html
  • main.js
  • preload.js
  • index.html
  • renderer.js
  1. <body>
  2.   <a href="child.html" target="_blank">new window</a>
  3. </body>
  1. // Modules to control application life and create native browser window
  2. const { app, BrowserWindow } = require('electron')
  3. const path = require('node:path')
  5. function createWindow () {
  6.   // Create the browser window.
  7.   const mainWindow = new BrowserWindow({
  8.     width: 800,
  9.     height: 600,
  10.     webPreferences: {
  11.       preload: path.join(__dirname, 'preload.js'),
  12.       webviewTag: true
  13.     }
  14.   })
  16.   mainWindow.webContents.on('did-attach-webview', (event, wc) => {
  17.     wc.setWindowOpenHandler((details) => {
  18.       mainWindow.webContents.send('webview-new-window', wc.id, details)
  19.       return { action: 'deny' }
  20.     })
  21.   })
  23.   // and load the index.html of the app.
  24.   mainWindow.loadFile('index.html')
  26.   // Open the DevTools.
  27.   // mainWindow.webContents.openDevTools()
  28. }
  30. // This method will be called when Electron has finished
  31. // initialization and is ready to create browser windows.
  32. // Some APIs can only be used after this event occurs.
  33. app.whenReady().then(() => {
  34.   createWindow()
  36.   app.on('activate', function () {
  37.     // On macOS it's common to re-create a window in the app when the
  38.     // dock icon is clicked and there are no other windows open.
  39.     if (BrowserWindow.getAllWindows().length === 0) createWindow()
  40.   })
  41. })
  43. // Quit when all windows are closed, except on macOS. There, it's common
  44. // for applications and their menu bar to stay active until the user quits
  45. // explicitly with Cmd + Q.
  46. app.on('window-all-closed', function () {
  47.   if (process.platform !== 'darwin') app.quit()
  48. })
  50. // In this file you can include the rest of your app's specific main process
  51. // code. You can also put them in separate files and require them here.
  1. const { ipcRenderer } = require('electron')
  2. const webview = document.getElementById('webview')
  3. ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
  4.   console.log('webview-new-window', webContentsId, details)
  5.   webview.dispatchEvent(new Event('new-window'))
  6. })
  1. <body>
  2.   <webview id=webview src="child.html" allowpopups></webview>
  3.   <script src="renderer.js"></script>
  4. </body>
  1. const webview = document.getElementById('webview')
  2. webview.addEventListener('new-window', () => {
  3.   console.log('got new-window event')
  4. })

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

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

  1. // 已废弃
  2. win.on('scroll-touch-begin', scrollTouchBegin)
  3. win.on('scroll-touch-edge', scrollTouchEdge)
  4. win.on('scroll-touch-end', scrollTouchEnd)
  6. // 可替换为
  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)

行为改变：启用V8内存隔离区

V8内存隔离已启用，这会影响原生模块 native modules 将非V8内存包裹上 ArrayBuffer 或 Buffer 对象。 查阅 V8 内存隔离区博客 浏览更多细节.

API Changed: webContents.printToPDF()

webContents.printToPDF() 已被修改，以符合 Chrome DevTools Protocol 中的 Page.printToPDF。 这是为了解决上游的更改，这些更改使我们以前的实现无法维持，充满了bug。

参数更改

  • pageRanges

参数移除

  • printSelectionOnly
  • marginsType
  • headerFooter
  • scaleFactor

参数添加

  • headerTemplate
  • footerTemplate
  • displayHeaderFooter
  • margins
  • scale
  • preferCSSPageSize
  1. // 主进程
  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)

已移除：macOS 10.11 / 10.12 / 支持

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

旧版本的 Electron 将继续在这些操作系统上运行，但 macOS 10.13 (High Sierra) 或更高版本将需要运行在 Electron v20.0.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) 时，调用的处理程序对其参数进行了更改。 这个处理程序不再被传递一个 frame WebFrameMain，而是通过传递 origin 来检查设备权限。

计划重写的 API (19.0)

已删除：IA32 Linux 二进制文件

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

计划重写的 API (18.0)

已移除： nativeWindowOpen

在 Electron 15之前， window.open 默认使用 BrowserWindowProxy。 这意味着 window.open('about:blank') 无法再来打开可同步脚本的子窗口，以及其他不兼容的情况。 自 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。 这意味着 window.open('about:blank') 无法再来打开可同步脚本的子窗口，以及其他不兼容的情况。 自 Electron 15 起, nativeWindowOpen 将默认启用。

更多详细信息: window.open

计划重写的 API (16.0)

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

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。 这意味着 window.open('about:blank') 无法再来打开可同步脚本的子窗口，以及其他不兼容的情况。 nativeWindowOpen 不再是实验性的，现在是默认值

更多详细信息: window.open

Deprecated: app.runningUnderRosettaTranslation

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

  1. // Deprecated
  2. console.log(app.runningUnderRosettaTranslation)
  3. // Replace with
  4. console.log(app.runningUnderARM64Translation)

计划重写的 API (14.0)

移除: remote 模块

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

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

已移除： app.allowRendererProcessReuse

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

更多信息见：#18397。

移除: Browser Window Affinity

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

更多信息见：#18397。

API 更改： window.open()

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

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

已移除： worldSafeExecuteJavaScript

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

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

移除: 从父窗口继承的 BrowserWindowConstructorOptions

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

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

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

已移除： additionalFeatures

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

  1. // 在 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. // 可替换为
  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. // 变更为
  10. session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  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 的 Flash Roadmap

默认更改： worldSafeExecuteJavaScript 默认为 true

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

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

默认更改: contextIsolation 默认值为 true

在 Electron 12, contextIsolation 将默认启用。 要恢复 上一个行为， contextIsolation: false 必须在 Web 首选项中指定。

我们 建议启用contextIsolation ，以保证您的应用程序的安全性。

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

更多信息请参阅：https://github.com/electron/electron/issues/23506

已移除: 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 模块

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

  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 属性也已被移除。

更多信息见 #23578。

计划重写的 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 :

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

我们 建议远离 remote 模块。

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)

计划重写的 API (9.0)

默认更改：默认在 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。

更多信息见：#18397。

已废弃： 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 8.0 中， IPC 被更改为使用结构化克隆算法(Structured Clone Algorithm)，显著提高了性能。 为了帮助简化转换，保留了旧的 IPC 序列化算法，并将其用于一些无法通过结构化克隆序列化的对象。 特别是 DOM 对象（例如：Element、Location、DOMMatrix），Node.js 中由 C++ 类支持的对象（例如：process.env、Stream 中的一些方法），和 Electron 中由 C++ 类支持的对象（例如：WebContents、BrowserWindow、WebFrame）无法使用使用结构化克隆序列化。 每当调用到旧算法时，都会打印弃用警告。

在 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 (例如 Uint8Array、Uint16Array、Uint32Array 等) 将这样传输，而不是转换为 Node.js Buffer。
  • Node.js Buffer 对象将作为 Uint8Array 进行传输。 你可以 通过包装底层将 Uint8Array 转换回 Node.js Buffer ArrayBuffer：
  1. Buffer.from(value.buffer, value.byteOffset, value.byteLength)

发送任何非原生 JS 类型的对象，例如 DOM 对象（例如 Element、Location、DOMMatrix、Node.js 对象（例如 process.env、 Stream）或 Electron 对象（例如 WebContents、BrowserWindow、 WebFrame) 已弃用。 在 Electron 8 中，这些对象将被序列化为 后带有过时警告消息， 但从 Electron 9开始，发送 这些对象将会导致一个“无法克隆”错误。

已废弃： <webview>.getWebContents()

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

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

已废弃：webFrame.setLayoutZoomLevelLimits()

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

systemPreferences 中弃用的事件

systemPreferences 事件已经被废弃：

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

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

  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)

已弃用: Atom.io Node Headers URL

这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志. 两者都将得到支持 可预见的未来，但建议您切换。

过时的: https://atom.io/download/electron

替换为: https://electronjs.org/headers

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

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

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

API 变化：powerMonitor.querySystemIdleState 变化为 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 变化：powerMonitor.querySystemIdleTime 更改为 powerMonitor.getSystemIdleTime

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

API 更改：webFrame.setIsolatedWorldInfo 替换单独的方法

  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'
  12.   })

已移除: getBlinkMemoryInfo 中 marked 属性

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

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

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

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

示例，以一个具有这种结构的文件夹为例：

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

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

  1. path/to/folder

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

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

请注意， webkitdirectory 不再显示选中文件夹的路径。 如果您需要所选文件夹的路径而不是文件夹内容， 请参阅 dialog.showOpenDialog API（链接）。

API 更改：基于回调的 promisified API 版本

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

这些函数现在只返回 Promises：

  • app.getFileIcon() #15742
  • app.dock.show() #16904
  • contentTracing.getCategories() #16583
  • contentTracking.getTraceBufferUs() #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的异步：

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

重大的API更新 (6.0)

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

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

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

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

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

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

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

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

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

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

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

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

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

弃用：Tray.setHighlightMode

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

  1. // 废弃
  2. tray.setHighlightMode(mode)
  3. // API will be removed in v7.0 without replacement.

重大的API更新 (5.0)

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

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

属性不推荐使用的默认值新的默认值
contextIsolationfalsetrue
nodeIntegrationtruefalse
webviewTagnodeIntegration 未设置过则是 truefalse

如下: 重新开启 webviewTag

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

行为已更改：nodeIntegration 需要通过 nativeWindowOpen 的子窗口打开

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

API 更改：注册 privileged schemes 现在必须在应用准备就绪之前完成

渲染器进程 API webFrame.registerURLSchemeAsPrivileged 和 webFrame.registerURLSchemeAsBypassingCSP 以及浏览器进程 API protocol.registerStandardSchemes 已被删除。 新的 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 更改：webFrame.setSpellCheckProvider 现在采用异步回调

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

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

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

  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 上加载，并出现错误 消息如 无法找到模块。 查看 原生模块指南 以获取更多信息.

移除: 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/atom-shell

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

重大的API更新 (2.0)

以下包含了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. // 替换为
  4. webview.setVisualZoomLevelLimits(1, 2)

重复的 ARM 资源

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

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

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