重大更改

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.

重大更改的类型

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

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

计划重写的 API (33.0)

Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all

APIs which provide access to a WebFrameMain instance may return an instance with frame.detached set to true, or possibly return null.

When a frame performs a cross-origin navigation, it enters into a detached state in which it's no longer attached to the page. In this state, it may be running unload handlers prior to being deleted. In the event of an IPC sent during this state, frame.detached will be set to true with the frame being destroyed shortly thereafter.

When receiving an event, it's important to access WebFrameMain properties immediately upon being received. Otherwise, it's not guaranteed to point to the same webpage as when received. To avoid misaligned expectations, Electron will return null in the case of late access where the webpage has changed.

ipcMain.on('unload-event', (event) => {
  event.senderFrame; // ✅ accessed immediately
});

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise;
  event.senderFrame; // ❌ returns `null` due to late access
});

行为变化：Windows 上的自定义协议 URL 处理

Due to changes made in Chromium to support Non-Special Scheme URLs, custom protocol URLs that use Windows file paths will no longer work correctly with the deprecated protocol.registerFileProtocol and the baseURLForDataURL property on BrowserWindow.loadURL, WebContents.loadURL, and <webview>.loadURL. protocol.handle will also not work with these types of URLs but this is not a change since it has always worked that way.

// No longer works
protocol.registerFileProtocol('other', () => {
  callback({ filePath: '/path/to/my/file' })
})

const mainWindow = new BrowserWindow()
mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://C:\\myapp' })
mainWindow.loadURL('other://C:\\myapp\\index.html')

// Replace with
const path = require('node:path')
const nodeUrl = require('node:url')
protocol.handle(other, (req) => {
  const srcPath = 'C:\\myapp\\'
  const reqURL = new URL(req.url)
  return net.fetch(nodeUrl.pathToFileURL(path.join(srcPath, reqURL.pathname)).toString())
})

mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://' })
mainWindow.loadURL('other://index.html')

Behavior Changed: `webContents` property on `login` on `app`

The webContents property in the login event from app will be null when the event is triggered for requests from the utility process created with respondToAuthRequestsFromMainProcess option.

Deprecated: `textured` option in `BrowserWindowConstructorOption.type`

The textured option of type in BrowserWindowConstructorOptions has been deprecated with no replacement. This option relied on the NSWindowStyleMaskTexturedBackground style mask on macOS, which has been deprecated with no alternative.

移除：macOS 10.15 支持

macOS 10.15 (Catalina) is no longer supported by Chromium.

旧版本的 Electron 将继续在 Catalina 上运行，但要运行 Electron v33.0.0 及更高版本，将需要 macOS 11（Big Sur）或更高版本。

已废弃：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

The systemPreferences.accessibilityDisplayShouldReduceTransparency property is now deprecated in favor of the new nativeTheme.prefersReducedTransparency, which provides identical information and works cross-platform.

// Deprecated
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency

// Replace with:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency

计划重写的 API (32.0)

Removed: `File.path`

The nonstandard path property of the Web File object was added in an early version of Electron as a convenience method for working with native files when doing everything in the renderer was more common. However, it represents a deviation from the standard and poses a minor security risk as well, so beginning in Electron 32.0 it has been removed in favor of the webUtils.getPathForFile method.

// Before (renderer)

const file = document.querySelector('input[type=file]').files[0]
alert(`Uploaded file path was: ${file.path}`)

// After (renderer)

const file = document.querySelector('input[type=file]').files[0]
electron.showFilePath(file)

// (preload)
const { contextBridge, webUtils } = require('electron')

contextBridge.exposeInMainWorld('electron', {
  showFilePath (file) {
    // It's best not to expose the full file path to the web content if
    // possible.
    const path = webUtils.getPathForFile(file)
    alert(`Uploaded file path was: ${path}`)
  }
})

Deprecated: `clearHistory`, `canGoBack`, `goBack`, `canGoForward`, `goForward`, `goToIndex`, `canGoToOffset`, `goToOffset` on `WebContents`

The navigation-related APIs are now deprecated.

These APIs have been moved to the navigationHistory property of WebContents to provide a more structured and intuitive interface for managing navigation history.

// Deprecated
win.webContents.clearHistory()
win.webContents.canGoBack()
win.webContents.goBack()
win.webContents.canGoForward()
win.webContents.goForward()
win.webContents.goToIndex(index)
win.webContents.canGoToOffset()
win.webContents.goToOffset(index)

// Replace with
win.webContents.navigationHistory.clear()
win.webContents.navigationHistory.canGoBack()
win.webContents.navigationHistory.goBack()
win.webContents.navigationHistory.canGoForward()
win.webContents.navigationHistory.goForward()
win.webContents.navigationHistory.canGoToOffset()
win.webContents.navigationHistory.goToOffset(index)

计划重写的 API (31.0)

Removed: `WebSQL` support

Chromium has removed support for WebSQL upstream, transitioning it to Android only. See Chromium's intent to remove discussion for more information.

Behavior Changed: `nativeImage.toDataURL` will preserve PNG colorspace

PNG decoder implementation has been changed to preserve colorspace data, the encoded data returned from this function now matches it.

See crbug.com/332584706 for more information.

Behavior Changed: `window.flashFrame(bool)` will flash dock icon continuously on macOS

This brings the behavior to parity with Windows and Linux. Prior behavior: The first flashFrame(true) bounces the dock icon only once (using the NSInformationalRequest level) and flashFrame(false) does nothing. New behavior: Flash continuously until flashFrame(false) is called. This uses the NSCriticalRequest level instead. To explicitly use NSInformationalRequest to cause a single dock icon bounce, it is still possible to use dock.bounce('informational').

计划重写的 API (30.0)

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

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

See documentation for more information.

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

This switch was never formally documented but it's removal is being noted here regardless. Chromium itself now has better support for color spaces so this flag should not be needed.

Behavior Changed: `BrowserView.setAutoResize` behavior on macOS

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

Previously, the setAutoResize function of the BrowserView API was backed by autoresizing on macOS, and by a custom algorithm on Windows and Linux. For simple use cases such as making a BrowserView fill the entire window, the behavior of these two approaches was identical. However, in more advanced cases, BrowserViews would be autoresized differently on macOS than they would be on other platforms, as the custom resizing algorithm for Windows and Linux did not perfectly match the behavior of macOS's autoresizing API. The autoresizing behavior is now standardized across all platforms.

If your app uses BrowserView.setAutoResize to do anything more complex than making a BrowserView fill the entire window, it's likely you already had custom logic in place to handle this difference in behavior on macOS. If so, that logic will no longer be needed in Electron 30 as autoresizing behavior is consistent.

Deprecated: `BrowserView`

The BrowserView class has been deprecated and replaced by the new WebContentsView class.

BrowserView related methods in BrowserWindow have also been deprecated:

BrowserWindow.fromBrowserView(browserView)
win.setBrowserView(browserView)
win.getBrowserView()
win.addBrowserView(browserView)
win.removeBrowserView(browserView)
win.setTopBrowserView(browserView)
win.getBrowserViews()

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

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

Removed: `process.getIOCounters()`

Chromium has removed access to this information.

计划重写的 API (29.0)

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

Attempting to send the entire ipcRenderer module as an object over the contextBridge will now result in an empty object on the receiving side of the bridge. 此更改是为了消除/减轻一种安全隐患。你不应该直接暴露 bridge 上的 ipcRenderer 或它的方法。相反，应该提供一个像下面这样的安全包装器：

contextBridge.exposeInMainWorld('app', {
  onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})

Removed: `renderer-process-crashed` event on `app`

The renderer-process-crashed event on app has been removed. Use the new render-process-gone event instead.

// Removed
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })

// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

Removed: `crashed` event on `WebContents` and `<webview>`

The crashed events on WebContents and <webview> have been removed. Use the new render-process-gone event instead.

// Removed
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })

// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })

Removed: `gpu-process-crashed` event on `app`

The gpu-process-crashed event on app has been removed. Use the new child-process-gone event instead.

// Removed
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })

// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })

计划重写的 API (28.0)

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

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

已移除: `BrowserWindow.setTrafficLightPosition(position)`

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

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

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

已移除: `BrowserWindow.getTrafficLightPosition()`

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

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

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

已移除: `ipcRenderer.sendTo()`

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

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

已移除: `app.runningUnderRosettaTranslation`

The app.runningUnderRosettaTranslation property has been removed. 替换为 app.runningUnderARM64Translation。

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

Deprecated: `renderer-process-crashed` event on `app`

The renderer-process-crashed event on app has been deprecated. Use the new render-process-gone event instead.

// Deprecated
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })

// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

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

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

Deprecated: `crashed` event on `WebContents` and `<webview>`

The crashed events on WebContents and <webview> have been deprecated. Use the new render-process-gone event instead.

// Deprecated
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })

// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })

Deprecated: `gpu-process-crashed` event on `app`

The gpu-process-crashed event on app has been deprecated. Use the new child-process-gone event instead.

// Deprecated
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })

// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })

计划重写的 API (27.0)

已移除：macOS 10.13 / 10.14 / 支援

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

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

弃用：`ipcRenderer.sendTo()`

ipcRenderer.sendTo() 已被弃用。 It should be replaced by setting up a MessageChannel between the renderers.

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

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

以下 systemPreferences 事件已被删除：

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

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

// Removed
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

Removed: Some `window.setVibrancy` options on macOS

The following vibrancy options have been removed:

'浅色'
'medium-light'
'深色'
'ultra-dark'
'appearance-based'

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

已删除: `webContents.getPrinters`

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

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

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

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

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

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

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

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

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

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

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

计划重写的 API (26.0)

弃用：`webContents.getPrinters`

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

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

// 被弃用
console.log(w.webContents.getPrinters())
// 替换为
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

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

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

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

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

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

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

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

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

计划重写的 API (25.0)

Deprecated: `protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` and `protocol.isProtocol{Registered,Intercepted}`

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

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

// 在 Electron 25 中弃用
protocol.registerBufferProtocol('some-protocol', () => {
  callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') });
});

// 替代为
protocol.handle('some-protocol', () => {
  return new Response(
    Buffer.from('<h5>Response</h5>'), // 也可以是 string 或 ReadableStream.
    { headers: { 'content-type': 'text/html' } }
  );
})

// 在 Electron 25 中弃用
protocol.registerHttpProtocol('some-protocol', () => {
  callback({ url: 'https://electronjs.org' });
});

// 替代为
protocol.handle('some-protocol', () => {
  return net.fetch('https://electronjs.org');
})

// 在 Electron 25 中弃用
protocol.registerFileProtocol('some-protocol', () => {
  callback({ filePath: '/path/to/my/file' });
});

// 替代为
protocol.handle('some-protocol', () => {
  return net.fetch('file:///path/to/my/file');
})

弃用：`BrowserWindow.setTrafficLightPosition(position)`

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

// 在 Electron 25 中弃用
win.setTrafficLightPosition({ x: 10, y: 10 });
win.setTrafficLightPosition({ x: 0, y: 0 });

// 替代为
win.setWindowButtonPosition({ x: 10, y: 10 });
win.setWindowButtonPosition(null)

弃用：`BrowserWindow.getTrafficLightPosition()`

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

// 在 Electron 24 中被移除
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)

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

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

更新行为：

// 一张 128x128 的图片。
const imagePath = path.join('path', 'to', 'capybara.png')

// 放大较小的图像。
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
  console.log(result.getSize()) // { width: 256, height: 256 }
})

// 缩小更大的图像。
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
  console.log(result.getSize()) // { width: 64, height: 64 }
})

以前的行为 (在 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)

行为改变：在 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 事件已被删除。 Instead, use the newly available input-event event on WebContents.

// 在 Electron 23.0 被移除
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// 可替换为
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)`

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

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

// 在 Electron 23 被移除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// 可替换为
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已移除: `webContents.decrementCapturerCount(stayHidden, stayAwake)`

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

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

// 在 Electron 23 被移除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// 可替换为
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

计划重写的 API (22.0)

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

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

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

// 在 Electron 23 被移除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// 可替换为
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

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

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

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

// 在 Electron 23 被移除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// 可替换为
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已废弃: WebContents `new-window` 事件

WebContents 中的 new-window 事件已经被废弃。 It is replaced by webContents.setWindowOpenHandler().

// 在 Electron 22 已移除
webContents.on('new-window', (event) => {
  event.preventDefault()
})

// 可替换为
webContents.setWindowOpenHandler((details) => {
  return { action: 'deny' }
})

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

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

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

// 替代为

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

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

// 已废弃
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// 可替换为
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)

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

V8内存隔离已启用，这会影响原生模块 native modules 将非V8内存包裹上 ArrayBuffer 或 Buffer 对象。 See the blog post about the V8 memory cage for more details.

API Changed: `webContents.printToPDF()`

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

参数更改

pageRanges

参数移除

printSelectionOnly
marginsType
headerFooter
scaleFactor

参数添加

headerTemplate
footerTemplate
displayHeaderFooter
margins
scale
preferCSSPageSize

// 主进程
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)

已移除：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) 时，调用的处理程序对其参数进行了更改。 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的支持。因此，删除了对IA32 Linux的支持。

计划重写的 API (18.0)

已移除： `nativeWindowOpen`

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

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

计划重写的 API (17.0)

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

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

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

// 主进程
const { ipcMain, desktopCapturer } = require('electron')

ipcMain.handle(
  'DESKTOP_CAPTURER_GET_SOURCES',
  (event, opts) => desktopCapturer.getSources(opts)
)

// 渲染器进程
const { ipcRenderer } = require('electron')

const desktopCapturer = {
  getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
}

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

已废弃：`nativeWindowOpen`

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

计划重写的 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 不再是实验性的，现在是默认值

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

弃用：`app.runningUnderRosettaTranslation`

The app.runningUnderRosettaTranslation property has been deprecated. 替换为 app.runningUnderARM64Translation。

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

计划重写的 API (14.0)

移除: `remote` 模块

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

// 在 Electron 12 废除:
const { BrowserWindow } = require('electron').remote

// 替换为：
const { BrowserWindow } = require('@electron/remote')

// 在主进程中：
require('@electron/remote/main').initialize()

已移除： `app.allowRendererProcessReuse`

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

更多信息见：#18397。

移除: Browser Window Affinity

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

更多信息见：#18397。

API 更改： `window.open()`

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

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

已移除： `worldSafeExecuteJavaScript`

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

若您使用了 webFrame.executeJavaScript 或 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

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

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

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

已移除： `additionalFeatures`

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

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

// 可替换为
webContents.on('did-create-window', (window, details) => {
  if (details.options['my-key']) {
    // ...
  }
})

计划重写的 API (13.0)

API 更改： `session.setPermissionCheckHandler(handler)`

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

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

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

已移除：`shell.moveItemToTrash()`

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

// 在 Electron 13 移除
shell.moveItemToTrash(path)
// 替换为
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()

// 在 Electron 13 移除
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// 替换为
session.defaultSession.loadExtension(path)

// 在 Electron 13 移除
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// 替换为
session.defaultSession.removeExtension(extension_id)

// 在 Electron 13 移除
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// 替换为
session.defaultSession.getAllExtensions()

已移除： `systemPreferences` 中的方法

systemPreferences 方法已经被废弃：

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

使用 nativeTheme 属性作为替代：

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

// 在 Electron 13 移除
systemPreferences.isDarkMode()
// 替换为
nativeTheme.shouldUseDarkColors

// 在 Electron 13 移除
systemPreferences.isInvertedColorScheme()
// 替换为
nativeTheme.shouldUseInvertedColorScheme

// 在 Electron 13 移除
systemPreferences.isHighContrastColorScheme()
// 替换为
nativeTheme.shouldUseHighContrastColors

已废弃: WebContents `new-window` 事件

WebContents 中的 new-window 事件已经被废弃。 It is replaced by webContents.setWindowOpenHandler().

// 在 Electron 13 废弃
webContents.on('new-window', (event) => {
  event.preventDefault()
})

// 替换为
webContents.setWindowOpenHandler((details) => {
  return { action: 'deny' }
})

计划重写的 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 首选项中指定。

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

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

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

已移除: `crashReporter.getCrashesDirectory()`

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

// 在 Electron 12 移除
crashReporter.getCrashesDirectory()
// 替换为
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 模块替代。

// 在 Electron 12 废除:
const { BrowserWindow } = require('electron').remote

// 替换为：
const { BrowserWindow } = require('@electron/remote')

// 在主进程中：
require('@electron/remote/main').initialize()

已废弃：`shell.moveItemToTrash()`

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

// 在 Electron 12 废弃
shell.moveItemToTrash(path)
// 替换为
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 值。

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

已废弃：`crashReporter.getCrashesDirectory()`

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

// 在 Electron 10 废除
crashReporter.getCrashesDirectory()
// 替换为
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 :

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

We recommend moving away from the remote module.

`protocol.unregisterProtocol`

`protocol.uninterceptProtocol`

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

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

`protocol.registerFileProtocol`

`protocol.registerBufferProtocol`

`protocol.registerStringProtocol`

`protocol.registerHttpProtocol`

`protocol.registerStreamProtocol`

`protocol.interceptFileProtocol`

`protocol.interceptStringProtocol`

`protocol.interceptBufferProtocol`

`protocol.interceptHttpProtocol`

`protocol.interceptStreamProtocol`

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

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

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

`protocol.isProtocolHandled`

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

// 废弃
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// 替换为
const isRegistered = protocol.isProtocolRegistered(scheme)
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()

// 在 Electron 9 废弃
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// 替换为
session.defaultSession.loadExtension(path)

// 在 Electron 9 废弃
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// 替换为
session.defaultSession.removeExtension(extension_id)

// 在 Electron 9 废弃
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// 替换为
session.defaultSession.getAllExtensions()

已移除： `<webview>.getWebContents()`

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

// 在 Electron 9.0 移除
webview.getWebContents()
// 替换为
const { remote } = require('electron')
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）算法进行序列化。

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 发送的 Function、Promise、WeakMaps、WeakSets 或者包含任何此类值的对象现在将引发异常，而不是静默地将函数转换为 undefined

// 之前:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => results in { value: 3 } arriving in the main process

// 从 Electron 8 开始:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => 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：

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 模块实现，兼具性能和安全影响。因此，它的用法应该是明确的。

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

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

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

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

// Deprecated
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

已废弃：`systemPreferences` 中的方法

systemPreferences 方法已经被废弃：

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

使用 nativeTheme 属性作为替代：

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

// 已废弃
systemPreferences.isDarkMode()
// 替换为
nativeTheme.shouldUseDarkColors

// 已废弃
systemPreferences.isInvertedColorScheme()
// 替换为
nativeTheme.shouldUseInvertedColorScheme

// 已废弃
systemPreferences.isHighContrastColorScheme()
// 替换为
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 不再接受需要清除的选项，而是无条件清除整个缓存。

// Deprecated
session.clearAuthCache({ type: 'password' })
// Replace with
session.clearAuthCache()

API 变化：`powerMonitor.querySystemIdleState` 变化为 `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`

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

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

// 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` 属性

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

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

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

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

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

folder
├── file1
├── file2
└── file3

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

path/to/folder

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

/path/to/folder/file3
/path/to/folder/file2
/path/to/folder/file1

请注意， webkitdirectory 不再显示选中文件夹的路径。 If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

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

// 不推荐
win.setMenu(null)
// 替换为
win.removeMenu()

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

// 不推荐
require('electron').screen
// 替换为
require('electron').remote.screen

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

// 不推荐
require('child_process')
// 替换为
require('electron').remote.require('child_process')

// 不推荐
require('fs')
// 替换为
require('electron').remote.require('fs')

// 不推荐
require('os')
// 替换为
require('electron').remote.require('os')

// 不推荐
require('path')
// 替换为
require('electron').remote.require('path')

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

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

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

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

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

// 废弃
app.enableMixedSandbox()

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

弃用：`Tray.setHighlightMode`

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

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

重大的API更新 (5.0)

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

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

属性	不推荐使用的默认值	新的默认值
`contextIsolation`	`false`	`true`
`nodeIntegration`	`true`	`false`
`webviewTag`	`nodeIntegration` 未设置过则是 `true`	`false`

如下: 重新开启 webviewTag

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

行为已更改：`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`

// 弃用
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// 替换为
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

API 更改：`webFrame.setSpellCheckProvider` 现在采用异步回调

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

// 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` 现在是同步的

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

// 废弃
webContents.getZoomLevel((level) => {
  console.log(level)
})
// 替换成
const level = webContents.getZoomLevel()
console.log(level)

// 废弃
webContents.getZoomFactor((factor) => {
  console.log(factor)
})
// 替换成
const factor = webContents.getZoomFactor()
console.log(factor)

计划重写的 API (4.0)

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

`app.makeSingleInstance`

// 已废弃
app.makeSingleInstance((argv, cwd) => {
  /* ... */
})
// 替换为
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
  /* ... */
})

`app.releaseSingleInstance`

// 废弃
app.releaseSingleInstance()
// 替换为
app.releaseSingleInstanceLock()

`app.getGPUInfo`

app.getGPUInfo('complete')
// 现在的行为将与macOS下的`basic`设置一样
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`

// 弃用
app.getAppMemoryInfo()
// 替换为
app.getAppMetrics()

// 弃用
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // 弃用的属性

`BrowserWindow`

// 已废弃
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// 替换为
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)

// 已废弃
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play_pause') {
    // do something
  }
})
// 替换为
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play-pause') {
    // do something
  }
})

`clipboard`

// 过时的
clipboard.readRtf()
// 替换为
clipboard.readRTF()

// 过时的
clipboard.writeRtf()
// 替换为
clipboard.writeRTF()

// 过时的
clipboard.readHtml()
// 替换为
clipboard.readHTML()

// 过时的
clipboard.writeHtml()
//替换为
clipboard.writeHTML()

`crashReporter`

// 过时的
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  autoSubmit: true
})
// 替换为
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  uploadToServer: true
})

`nativeImage`

// 弃用
nativeImage.createFromBuffer(buffer, 1.0)
// 替换为
nativeImage.createFromBuffer(buffer, {
  scaleFactor: 1.0
})

`process`

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

`screen`

// 弃用
screen.getMenuBarHeight()
// 替换为
screen.getPrimaryDisplay().workArea

`session`

// 弃用
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  callback(true)
})
// 替换为
ses.setCertificateVerifyProc((request, callback) => {
  callback(0)
})

`Tray`

// 过时的
tray.setHighlightMode(true)
// 替换为
tray.setHighlightMode('on')

// 过时的
tray.setHighlightMode(false)
// 替换为
tray.setHighlightMode('off')

`webContents`

// 弃用
webContents.openDevTools({ detach: true })
// 替换为
webContents.openDevTools({ mode: 'detach' })

// 移除
webContents.setSize(options)
// 没有该API的替代

`webFrame`

// 弃用
webFrame.registerURLSchemeAsSecure('app')
// 替换为
protocol.registerStandardSchemes(['app'], { secure: true })

// 弃用
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// 替换为
protocol.registerStandardSchemes(['app'], { secure: true })

`<webview>`

// 移除
webview.setAttribute('disableguestresize', '')
// 没有该API的替代

// 移除
webview.setAttribute('guestinstance', instanceId)
// 没有该API的替代

// 键盘监听器在webview标签中不再起效
webview.onkeydown = () => { /* handler */ }
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`

// 已废弃
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// 替换为
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)

`menu`

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

`nativeImage`

// 移除
nativeImage.toPng()
// 替换为
nativeImage.toPNG()

// 移除
nativeImage.toJpeg()
// 替换为
nativeImage.toJPEG()

`process`

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

`webContents`

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

`webFrame`

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

`<webview>`

// 移除
webview.setZoomLevelLimits(1, 2)
// 替换为
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。

重大更改的类型
计划重写的 API (33.0)
- Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all
- 行为变化：Windows 上的自定义协议 URL 处理
- Behavior Changed: webContents property on login on app
- Deprecated: textured option in BrowserWindowConstructorOption.type
- 移除：macOS 10.15 支持
- 已废弃：systemPreferences.accessibilityDisplayShouldReduceTransparency
计划重写的 API (32.0)
- Removed: File.path
- Deprecated: clearHistory, canGoBack, goBack, canGoForward, goForward, goToIndex, canGoToOffset, goToOffset on WebContents
计划重写的 API (31.0)
- Removed: WebSQL support
- Behavior Changed: nativeImage.toDataURL will preserve PNG colorspace
- Behavior Changed: window.flashFrame(bool) will flash dock icon continuously on macOS
计划重写的 API (30.0)
- Behavior Changed: cross-origin iframes now use Permission Policy to access features
- Removed: The --disable-color-correct-rendering switch
- Behavior Changed: BrowserView.setAutoResize behavior on macOS
- Deprecated: BrowserView
- Removed: params.inputFormType property on context-menu on WebContents
- Removed: process.getIOCounters()
计划重写的 API (29.0)
- Behavior Changed: ipcRenderer can no longer be sent over the contextBridge
- Removed: renderer-process-crashed event on app
- Removed: crashed event on WebContents and <webview>
- Removed: gpu-process-crashed event on app
计划重写的 API (28.0)
- Behavior Changed: WebContents.backgroundThrottling set to false affects all WebContents in the host BrowserWindow
- 已移除: BrowserWindow.setTrafficLightPosition(position)
- 已移除: BrowserWindow.getTrafficLightPosition()
- 已移除: ipcRenderer.sendTo()
- 已移除: app.runningUnderRosettaTranslation
- Deprecated: renderer-process-crashed event on app
- Deprecated: params.inputFormType property on context-menu on WebContents
- Deprecated: crashed event on WebContents and <webview>
- Deprecated: gpu-process-crashed event on app
计划重写的 API (27.0)
- 已移除：macOS 10.13 / 10.14 / 支援
- 弃用：ipcRenderer.sendTo()
- 已删除： systemPreferences 中的 color scheme 相关事件
- Removed: Some window.setVibrancy options on macOS
- 已删除: webContents.getPrinters
- 已删除：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance
- 已删除：systemPreferences.getColor 的 alternate-selected-control-text 值
计划重写的 API (26.0)
- 弃用：webContents.getPrinters
- 弃用：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance
- 弃用：systemPreferences.getColor 的 alternate-selected-control-text 值
计划重写的 API (25.0)
- Deprecated: protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol and protocol.isProtocol{Registered,Intercepted}
- 弃用：BrowserWindow.setTrafficLightPosition(position)
- 弃用：BrowserWindow.getTrafficLightPosition()
计划重写的 API (24.0)
- API Changed: nativeImage.createThumbnailFromPath(path, size)
计划重写的 API (23.0)
- 行为改变：在 macOS 上的可拖动区域
- 已移除：Windows 7 / 8 / 8.1 支持
- 已删除：BrowserWindow scroll-touch-* 事件
- 已移除: webContents.incrementCapturerCount(stayHidden, stayAwake)
- 已移除: webContents.decrementCapturerCount(stayHidden, stayAwake)
计划重写的 API (22.0)
- 已废弃：webContents.incrementCapturerCount(stayHidden, stayAwake)
- 已废弃：webContents.decrementCapturerCount(stayHidden, stayAwake)
- 已废弃: WebContents new-window 事件
- 已移除： <webview> new-window 事件
- 已废弃：Browserwindow scroll-touch-* 事件
计划重写的 API (21.0)
- 行为改变：启用V8内存隔离区
- API Changed: webContents.printToPDF()
计划重写的 API (20.0)
- 已移除：macOS 10.11 / 10.12 / 支持
- 默认值被更改：默认情况下，渲染器不为 nodeIntegration: true 将进行沙盒处理
- 已删除：Linux 上的 skipTaskbar
- API Changed: session.setDevicePermissionHandler(handler)
计划重写的 API (19.0)
- 已删除：IA32 Linux 二进制文件
计划重写的 API (18.0)
- 已移除： nativeWindowOpen
计划重写的 API (17.0)
- 已移除：渲染器中的 desktopCapturer.getSources
- 已废弃：nativeWindowOpen
计划重写的 API (16.0)
- 行为改变：crashReporter 实现切换到 Linux 上的 Crashpad
- 已弃用：在渲染器中的 desktopCapturer.getSources
计划重写的 API (15.0)
- 默认更改： nativeWindowOpen 默认为 true
- 弃用：app.runningUnderRosettaTranslation
计划重写的 API (14.0)
- 移除: remote 模块
- 已移除： app.allowRendererProcessReuse
- 移除: Browser Window Affinity
- API 更改： window.open()
- 已移除： worldSafeExecuteJavaScript
- 移除: 从父窗口继承的 BrowserWindowConstructorOptions
- 已移除： additionalFeatures
计划重写的 API (13.0)
- API 更改： session.setPermissionCheckHandler(handler)
- 已移除：shell.moveItemToTrash()
- 已移除： BrowserWindow 扩展 API
- 已移除： systemPreferences 中的方法
- 已废弃: WebContents new-window 事件
计划重写的 API (12.0)
- 已移除：Pepper Flash 支持
- 默认更改： worldSafeExecuteJavaScript 默认为 true
- 默认更改: contextIsolation 默认值为 true
- 已移除: crashReporter.getCrashesDirectory()
- 已移除：渲染进程中的 crashReporter 方法
- 默认值已更改：crashReporter.start({ compress: true })
- 已废弃： remote 模块
- 已废弃：shell.moveItemToTrash()
计划重写的 API (11.0)
- 移除: BrowserView 中的 BrowserView.{destroy, fromId, fromWebContents, getAllViews} 和 id 属性
计划重写的 API (10.0)
- 已废弃：crashReporter.start() 中的 companyName 参数
- 已废弃：crashReporter.getCrashesDirectory()
- 已废弃：渲染进程中的 crashReporter 方法
- 已废弃：crashReporter.start({ compress: false })
- 默认更改: enableRemoteModule 默认值为 false
- unregisterProtocol
- uninterceptProtocol
- registerFileProtocol
- registerBufferProtocol
- registerStringProtocol
- registerHttpProtocol
- registerStreamProtocol
- interceptFileProtocol
- interceptStringProtocol
- interceptBufferProtocol
- interceptHttpProtocol
- interceptStreamProtocol
- isProtocolHandled
计划重写的 API (9.0)
- 默认更改：默认在 renderer process 中禁用加载 non-context-aware native modules
- 已废弃： BrowserWindow 扩展 API
- 已移除： <webview>.getWebContents()
- 已移除: webFrame.setLayoutZoomLevelLimits()
- 行为改变: 通过 IPC 发送非 JS 对象，现在将引发异常
- API 变化：shell.openItem 变化为 shell.openPath
计划重写的 API (8.0)
- 行为改变：通过 IPC 发送的值现在已经使用结构化克隆（Structured Clone Algorithm）算法进行序列化。
- 已废弃： <webview>.getWebContents()
- 已废弃：webFrame.setLayoutZoomLevelLimits()
- systemPreferences 中弃用的事件
- 已废弃：systemPreferences 中的方法
重大的API更新 (7.0)
- 已弃用: Atom.io Node Headers URL
- API 更改: session.clearAuthCache() 不再接受选项
- API 变化：powerMonitor.querySystemIdleState 变化为 powerMonitor.getSystemIdleState
- API 变化：powerMonitor.querySystemIdleTime 更改为 powerMonitor.getSystemIdleTime
- API 更改：webFrame.setIsolatedWorldInfo 替换单独的方法
- 已移除: getBlinkMemoryInfo 中 marked 属性
- 行为改变: webkitdirectory 属性 <input type="file"/> 现在列出目录内容
- API 更改：基于回调的 promisified API 版本
重大的API更新 (6.0)
- API 更改：win.setMenu(null) 现在是 win.removeMenu()
- API 更改：渲染器进程中的 electron.screen 应通过 remote 访问
- API 更改：require()ing 沙盒渲染器中的节点内置不再隐式加载 remote 版本
- 弃用：powerMonitor.querySystemIdleState 替换为 powerMonitor.getSystemIdleState
- 弃用：powerMonitor.querySystemIdleTime 替换为 powerMonitor.getSystemIdleTime
- 弃用：不再需要 app.enableMixedSandbox()
- 弃用：Tray.setHighlightMode
重大的API更新 (5.0)
- 默认更改：nodeIntegration 和 webviewTag 默认为 false，contextIsolation 默认为 true
- 行为已更改：nodeIntegration 需要通过 nativeWindowOpen 的子窗口打开
- API 更改：注册 privileged schemes 现在必须在应用准备就绪之前完成
- 已废弃: webFrame.setIsolatedWorld* 已替换为 webFrame.setIsolatedWorldInfo
- API 更改：webFrame.setSpellCheckProvider 现在采用异步回调
- API 更改：webContents.getZoomLevel 和 webContents.getZoomFactor 现在是同步的
计划重写的 API (4.0)
- makeSingleInstance
- releaseSingleInstance
- getGPUInfo
- win_delay_load_hook
- 移除: IA32 Linux 支持
重大的API更新 (3.0)
- app
- BrowserWindow
- clipboard
- crashReporter
- nativeImage
- process
- screen
- session
- Tray
- webContents
- webFrame
- <webview>
- Node Headers URL
重大的API更新 (2.0)
- BrowserWindow
- menu
- nativeImage
- process
- webContents
- webFrame
- <webview>
- 重复的 ARM 资源

重大更改的类型​

计划重写的 API (33.0)​

Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all​

行为变化：Windows 上的自定义协议 URL 处理​

Behavior Changed: webContents property on login on app​

Deprecated: textured option in BrowserWindowConstructorOption.type​

移除：macOS 10.15 支持​

已废弃：systemPreferences.accessibilityDisplayShouldReduceTransparency​

计划重写的 API (32.0)​

Removed: File.path​

Deprecated: clearHistory, canGoBack, goBack, canGoForward, goForward, goToIndex, canGoToOffset, goToOffset on WebContents​

计划重写的 API (31.0)​

Removed: WebSQL support​

Behavior Changed: nativeImage.toDataURL will preserve PNG colorspace​

Behavior Changed: window.flashFrame(bool) will flash dock icon continuously on macOS​

计划重写的 API (30.0)​

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

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

Behavior Changed: BrowserView.setAutoResize behavior on macOS​

Deprecated: BrowserView​

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

Removed: process.getIOCounters()​

计划重写的 API (29.0)​

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

Removed: renderer-process-crashed event on app​

Removed: crashed event on WebContents and <webview>​

Removed: gpu-process-crashed event on app​

计划重写的 API (28.0)​

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

已移除: BrowserWindow.setTrafficLightPosition(position)​

已移除: BrowserWindow.getTrafficLightPosition()​

已移除: ipcRenderer.sendTo()​

已移除: app.runningUnderRosettaTranslation​

Deprecated: renderer-process-crashed event on app​

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

Deprecated: crashed event on WebContents and <webview>​

Deprecated: gpu-process-crashed event on app​

计划重写的 API (27.0)​

已移除：macOS 10.13 / 10.14 / 支援​

弃用：ipcRenderer.sendTo()​

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

Removed: Some window.setVibrancy options on macOS​

已删除: webContents.getPrinters​

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

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

计划重写的 API (26.0)​

弃用：webContents.getPrinters​

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

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

计划重写的 API (25.0)​

Deprecated: protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol and protocol.isProtocol{Registered,Intercepted}​

弃用：BrowserWindow.setTrafficLightPosition(position)​

弃用：BrowserWindow.getTrafficLightPosition()​

计划重写的 API (24.0)​

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

计划重写的 API (23.0)​

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

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

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

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

已移除: webContents.decrementCapturerCount(stayHidden, stayAwake)​

计划重写的 API (22.0)​

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

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

已废弃: WebContents new-window 事件​

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

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

计划重写的 API (21.0)​

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

API Changed: webContents.printToPDF()​

计划重写的 API (20.0)​

已移除：macOS 10.11 / 10.12 / 支持​

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

已删除：Linux 上的 skipTaskbar​

API Changed: session.setDevicePermissionHandler(handler)​

计划重写的 API (19.0)​

已删除：IA32 Linux 二进制文件​

计划重写的 API (18.0)​

已移除： nativeWindowOpen​

计划重写的 API (17.0)​

重大更改的类型

计划重写的 API (33.0)

Behavior Changed: frame properties may retrieve detached WebFrameMain instances or none at all

行为变化：Windows 上的自定义协议 URL 处理

Behavior Changed: `webContents` property on `login` on `app`

Deprecated: `textured` option in `BrowserWindowConstructorOption.type`

移除：macOS 10.15 支持

已废弃：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

计划重写的 API (32.0)

Removed: `File.path`

Deprecated: `clearHistory`, `canGoBack`, `goBack`, `canGoForward`, `goForward`, `goToIndex`, `canGoToOffset`, `goToOffset` on `WebContents`

计划重写的 API (31.0)

Removed: `WebSQL` support

Behavior Changed: `nativeImage.toDataURL` will preserve PNG colorspace

Behavior Changed: `window.flashFrame(bool)` will flash dock icon continuously on macOS

计划重写的 API (30.0)

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

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

Behavior Changed: `BrowserView.setAutoResize` behavior on macOS

Deprecated: `BrowserView`

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

Removed: `process.getIOCounters()`

计划重写的 API (29.0)

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

Removed: `renderer-process-crashed` event on `app`

Removed: `crashed` event on `WebContents` and `<webview>`

Removed: `gpu-process-crashed` event on `app`

计划重写的 API (28.0)

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

已移除: `BrowserWindow.setTrafficLightPosition(position)`

已移除: `BrowserWindow.getTrafficLightPosition()`

已移除: `ipcRenderer.sendTo()`

已移除: `app.runningUnderRosettaTranslation`

Deprecated: `renderer-process-crashed` event on `app`

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

Deprecated: `crashed` event on `WebContents` and `<webview>`

Deprecated: `gpu-process-crashed` event on `app`

计划重写的 API (27.0)

已移除：macOS 10.13 / 10.14 / 支援

弃用：`ipcRenderer.sendTo()`

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

Removed: Some `window.setVibrancy` options on macOS

已删除: `webContents.getPrinters`

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

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

计划重写的 API (26.0)

弃用：`webContents.getPrinters`

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

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

计划重写的 API (25.0)

Deprecated: `protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` and `protocol.isProtocol{Registered,Intercepted}`

弃用：`BrowserWindow.setTrafficLightPosition(position)`

弃用：`BrowserWindow.getTrafficLightPosition()`

计划重写的 API (24.0)

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

计划重写的 API (23.0)

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

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

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

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

已移除: `webContents.decrementCapturerCount(stayHidden, stayAwake)`

计划重写的 API (22.0)

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

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

已废弃: WebContents `new-window` 事件

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

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

计划重写的 API (21.0)

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

API Changed: `webContents.printToPDF()`

计划重写的 API (20.0)

已移除：macOS 10.11 / 10.12 / 支持

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

已删除：Linux 上的 `skipTaskbar`

API Changed: `session.setDevicePermissionHandler(handler)`

计划重写的 API (19.0)

已删除：IA32 Linux 二进制文件

计划重写的 API (18.0)

已移除： `nativeWindowOpen`

计划重写的 API (17.0)