重大变更

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

重大变更类型

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

API 更改：API 发生了更改，导致未更新的代码肯定会抛出异常。
行为更改：Electron 的行为发生了更改，但不会必然抛出异常。
默认值更改：依赖于旧默认值的代码可能会中断，不一定会抛出异常。可以通过显式指定值来恢复旧行为。
已弃用：API 已标记为已弃用。API 将继续运行，但会发出弃用警告，并在将来的版本中删除。
已移除：API 或功能已被移除，不再受 Electron 支持。

计划中的重大 API 变更 (33.0)

行为更改：`app` 上的 `login` 事件中的 `webContents` 属性

当 app 的 login 事件触发来自使用 respondToAuthRequestsFromMainProcess 选项创建的实用程序进程的请求时，该事件中的 webContents 属性将为 null。

已弃用：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

systemPreferences.accessibilityDisplayShouldReduceTransparency 属性现已弃用，取而代之的是新的 nativeTheme.prefersReducedTransparency，后者提供相同的信息并在跨平台上工作。

// Deprecated
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency

// Replace with:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency

计划中的重大 API 变更 (32.0)

已移除：`File.path`

Web File 对象的非标准 path 属性在 Electron 的早期版本中作为一种便利方法添加，用于在渲染器中执行所有操作更为常见时处理本地文件。但是，它偏离了标准，并且也存在轻微的安全风险，因此从 Electron 32.0 开始，它已被移除，取而代之的是 webUtils.getPathForFile 方法。

// Before (renderer)

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

// After (renderer)

const file = document.querySelector('input[type=file]')
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}`)
  }
})

已弃用：`WebContents` 上的 `clearHistory`、`canGoBack`、`goBack`、`canGoForward`、`goForward`、`goToIndex`、`canGoToOffset`、`goToOffset`

与导航相关的 API 现已弃用。

这些 API 已移至 WebContents 的 navigationHistory 属性，以提供更结构化和直观的界面来管理导航历史记录。

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

已移除：`WebSQL` 支持

Chromium 已删除对 WebSQL 的上游支持，将其过渡到仅限 Android。有关更多信息，请参阅 Chromium 删除意图讨论。

行为更改：`nativeImage.toDataURL` 将保留 PNG 色彩空间

PNG 解码器实现已更改为保留色彩空间数据，此函数返回的编码数据现在与之匹配。

有关更多信息，请参阅 crbug.com/332584706。

行为更改：`window.flashFrame(bool)` 将在 macOS 上连续闪烁 Dock 图标

这使行为与 Windows 和 Linux 保持一致。先前行为：第一个 flashFrame(true) 只弹跳一次 Dock 图标（使用 NSInformationalRequest 级别），而 flashFrame(false) 则不执行任何操作。新行为：连续闪烁，直到调用 flashFrame(false) 为止。这使用 NSCriticalRequest 级别代替。要显式使用 NSInformationalRequest 来导致 Dock 图标弹跳一次，仍然可以使用 dock.bounce('informational')。

计划中的重大 API 变更 (30.0)

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

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

有关更多信息，请参阅文档。

已移除：`--disable-color-correct-rendering` 开关

此开关从未正式记录，但无论如何都会在此处记录其移除。Chromium 本身现在对色彩空间有更好的支持，因此不应该需要此标志。

行为更改：macOS 上 `BrowserView.setAutoResize` 的行为

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

以前，BrowserView API 的 setAutoResize 函数在 macOS 上由自动调整大小支持，在 Windows 和 Linux 上由自定义算法支持。对于简单用例（例如使 BrowserView 填充整个窗口），这两种方法的行为相同。但是，在更高级的用例中，BrowserView 在 macOS 上的自动调整大小方式与其他平台不同，因为 Windows 和 Linux 的自定义调整大小算法与 macOS 自动调整大小 API 的行为并不完全匹配。自动调整大小行为现在已在所有平台上标准化。

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

已弃用：`BrowserView`

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

BrowserWindow 中与 BrowserView 相关的方法也已弃用。

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

已移除：`WebContents` 上的 `context-menu` 事件中的 `params.inputFormType` 属性

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

已移除：`process.getIOCounters()`

Chromium 已删除对这些信息的访问权限。

计划中的重大 API 变更 (29.0)

行为更改：`ipcRenderer` 不能再通过 `contextBridge` 发送

尝试通过 contextBridge 将整个 ipcRenderer 模块作为对象发送现在会导致桥接接收端出现空对象。进行此更改是为了移除/减轻安全隐患。您不应直接通过桥接公开 ipcRenderer 或其方法。相反，请提供如下所示的安全包装器

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

已移除：`app` 上的 `renderer-process-crashed` 事件

app 上的 renderer-process-crashed 事件已被移除。请使用新的 render-process-gone 事件代替。

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

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

已移除：`WebContents` 和 `<webview>` 上的 `crashed` 事件

WebContents 和 <webview> 上的 crashed 事件已被移除。请使用新的 render-process-gone 事件代替。

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

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

已移除：`app` 上的 `gpu-process-crashed` 事件

app 上的 gpu-process-crashed 事件已被移除。请使用新的 child-process-gone 事件代替。

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

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

计划中的破坏性 API 更改 (28.0)

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

将 WebContents.backgroundThrottling 设置为 false 将禁用 BrowserWindow 中由其显示的所有 WebContents 的帧节流。

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

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

// 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() 已被移除，应使用 BrowserWindow.getWindowButtonPosition() API 代替，该 API 在没有自定义位置时返回 null 而不是 { x: 0, y: 0 }。

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

ipcRenderer.sendTo() API 已被移除。它应该被替换为在渲染器之间建立一个 MessageChannel。

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

已移除：`app.runningUnderRosettaTranslation`

app.runningUnderRosettaTranslation 属性已被移除。请使用 app.runningUnderARM64Translation 代替。

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

已弃用：`app` 上的 `renderer-process-crashed` 事件

app 上的 renderer-process-crashed 事件已弃用。请使用新的 render-process-gone 事件代替。

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

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

已弃用：`WebContents` 上 `context-menu` 的 `params.inputFormType` 属性

来自 WebContents 的 context-menu 事件中 params 对象的 inputFormType 属性已弃用。请使用新的 formControlType 属性代替。

已弃用：`WebContents` 和 `<webview>` 上的 `crashed` 事件

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

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

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

已弃用：`app` 上的 `gpu-process-crashed` 事件

app 上的 gpu-process-crashed 事件已弃用。请使用新的 child-process-gone 事件代替。

// 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 支持

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

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

已弃用：`ipcRenderer.sendTo()`

ipcRenderer.sendTo() API 已弃用。它应该被替换为在渲染器之间建立一个 MessageChannel。

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

已移除：`systemPreferences` 中的颜色方案事件

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

已移除：macOS 上的一些 `window.setVibrancy` 选项

以下活力选项已被移除

'light'
'medium-light'
'dark'
'ultra-dark'
'appearance-based'

这些选项之前已弃用，并在 10.15 中被 Apple 移除。

已移除：`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 })

// Deprecated
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 模块代替。

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

已弃用：`protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` 和 `protocol.isProtocol{Registered,Intercepted}`

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

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

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

// Replace with
protocol.handle('some-protocol', () => {
  return new Response(
    Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
    { headers: { 'content-type': 'text/html' } }
  )
})

// Deprecated in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
  callback({ url: 'https://www.electron.js.cn' })
})

// Replace with
protocol.handle('some-protocol', () => {
  return net.fetch('https://www.electron.js.cn')
})

// Deprecated in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
  callback({ filePath: '/path/to/my/file' })
})

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

已弃用：`BrowserWindow.setTrafficLightPosition(position)`

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

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

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

已弃用：`BrowserWindow.getTrafficLightPosition()`

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

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

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

计划中的破坏性 API 更改 (24.0)

API 变更：`nativeImage.createThumbnailFromPath(path, size)`

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

更新后的行为

// a 128x128 image.
const imagePath = path.join('path', 'to', 'capybara.png')

// Scaling up a smaller image.
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
  console.log(result.getSize()) // { width: 256, height: 256 }
})

// Scaling down a larger image.
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
  console.log(result.getSize()) // { width: 64, height: 64 }
})

以前的行为（在 Windows 上）

// 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 上的可拖动区域

macOS 上可拖动区域的实现（使用 CSS 属性-webkit-app-region: drag）已更改，使其与 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）。

因此，如果您的应用程序在 macOS 上使用无边框窗口和可拖动区域，则您的应用程序中可拖动区域可能会在 Electron 23 中发生变化。

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

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

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

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

BrowserWindow 上已弃用的scroll-touch-begin、scroll-touch-end 和scroll-touch-edge 事件已被移除。请改用 WebContents 上新提供的input-event 事件。

// Removed in Electron 23.0
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// Replace with
win.webContents.on('input-event', (_, event) => {
  if (event.type === 'gestureScrollBegin') {
    scrollTouchBegin()
  } else if (event.type === 'gestureScrollUpdate') {
    scrollTouchEdge()
  } else if (event.type === 'gestureScrollEnd') {
    scrollTouchEnd()
  }
})

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

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

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

// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

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

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

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

// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

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

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

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

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

// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

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

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

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

// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已移除：WebContents `new-window` 事件

WebContents 的new-window 事件已被移除。它被webContents.setWindowOpenHandler() 替换。

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

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

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

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

// Removed in Electron 22
webview.addEventListener('new-window', (event) => {})

// Replace with

// main.js
mainWindow.webContents.on('did-attach-webview', (event, wc) => {
  wc.setWindowOpenHandler((details) => {
    mainWindow.webContents.send('webview-new-window', wc.id, details)
    return { action: 'deny' }
  })
})

// preload.js
const { ipcRenderer } = require('electron')
ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
  console.log('webview-new-window', webContentsId, details)
  document.getElementById('webview').dispatchEvent(new Event('new-window'))
})

// renderer.js
document.getElementById('webview').addEventListener('new-window', () => {
  console.log('got new-window event')
})

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

BrowserWindow 上的scroll-touch-begin、scroll-touch-end 和scroll-touch-edge 事件已弃用。请改用 WebContents 上新提供的input-event 事件。

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

// Replace with
win.webContents.on('input-event', (_, event) => {
  if (event.type === 'gestureScrollBegin') {
    scrollTouchBegin()
  } else if (event.type === 'gestureScrollUpdate') {
    scrollTouchEdge()
  } else if (event.type === 'gestureScrollEnd') {
    scrollTouchEnd()
  }
})

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

行为更改：启用了 V8 内存沙箱

已启用 V8 内存沙箱，这对使用ArrayBuffer 或Buffer 包装非 V8 内存的原生模块有影响。有关更多详细信息，请参阅有关 V8 内存沙箱的博文。

API 更改：`webContents.printToPDF()`

webContents.printToPDF() 已修改为符合 Chrome 开发者工具协议中的Page.printToPDF。进行此更改是为了解决上游更改，这些更改使我们之前的实现变得不可维护且存在大量错误。

参数更改

pageRanges

已移除的参数

printSelectionOnly
marginsType
headerFooter
scaleFactor

已添加的参数

headerTemplate
footerTemplate
displayHeaderFooter
margins
scale
preferCSSPageSize

// Main process
const { webContents } = require('electron')

webContents.printToPDF({
  landscape: true,
  displayHeaderFooter: true,
  printBackground: true,
  scale: 2,
  pageSize: 'Ledger',
  margins: {
    top: 2,
    bottom: 2,
    left: 2,
    right: 2
  },
  pageRanges: '1-5, 8, 11-13',
  headerTemplate: '<h1>Title</h1>',
  footerTemplate: '<div><span class="pageNumber"></span></div>',
  preferCSSPageSize: true
}).then(data => {
  fs.writeFile(pdfPath, data, (error) => {
    if (error) throw error
    console.log(`Wrote PDF successfully to ${pdfPath}`)
  })
}).catch(error => {
  console.log(`Failed to write PDF to ${pdfPath}: `, error)
})

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

已移除：macOS 10.11 / 10.12 支持

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

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

默认值更改：默认情况下，没有`nodeIntegration: true` 的渲染器处于沙箱状态

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

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

已移除：Linux 上的`skipTaskbar`

在 X11 上，skipTaskbar 会向 X11 窗口管理器发送_NET_WM_STATE_SKIP_TASKBAR 消息。Wayland 没有直接的等效项，并且已知的解决方法具有不可接受的权衡（例如，GNOME 中的 Window.is_skip_taskbar 需要不安全模式），因此 Electron 无法在 Linux 上支持此功能。

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

使用session.setDevicePermissionHandler(handler) 时调用的处理程序对其参数进行了更改。此处理程序不再传递帧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 已默认启用。

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

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

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

desktopCapturer.getSources API 现在仅在主进程中可用。此更改是为了提高 Electron 应用程序的默认安全性。

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

// Main process
const { ipcMain, desktopCapturer } = require('electron')

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

// Renderer process
const { ipcRenderer } = require('electron')

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

但是，您应该考虑进一步限制返回给渲染器的信息；例如，向用户显示源选择器，并且仅返回所选源。

已弃用：`nativeWindowOpen`

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

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

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

Linux 上 crashReporter API 的底层实现已从 Breakpad 更改为 Crashpad，使其与 Windows 和 Mac 保持一致。因此，子进程现在会自动监控，并且不再需要在 Node 子进程中调用 process.crashReporter.start（也不建议这样做，因为它会启动 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 现在不再是实验性的，并且成为默认值。

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

已弃用：`app.runningUnderRosettaTranslation`

app.runningUnderRosettaTranslation 属性已被弃用。请使用 app.runningUnderARM64Translation 代替。

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

计划中的破坏性 API 更改 (14.0)

已移除：`remote` 模块

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

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

// Replace with:
const { BrowserWindow } = require('@electron/remote')

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

已移除：`app.allowRendererProcessReuse`

app.allowRendererProcessReuse 属性将被移除，这是我们计划更紧密地遵循 Chromium 的进程模型以提高安全性、性能和可维护性的一部分。

有关更详细的信息，请参阅#18397。

已移除：浏览器窗口关联性

构造新的 BrowserWindow 时，affinity 选项将被移除，这是我们计划更紧密地遵循 Chromium 的进程模型以提高安全性、性能和可维护性的一部分。

有关更详细的信息，请参阅#18397。

API 更改：`window.open()`

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

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

已移除：`worldSafeExecuteJavaScript`

在 Electron 14 中，worldSafeExecuteJavaScript 将被移除。没有替代方案，请确保您的代码能够在启用此属性的情况下正常工作。它从 Electron 12 开始默认启用。

如果您使用 webFrame.executeJavaScript 或 webFrame.executeJavaScriptInIsolatedWorld，则会受到此更改的影响。您需要确保这两种方法返回的值都受 Context Bridge API 支持，因为这些方法使用相同的传值语义。

已移除：从父窗口继承的 BrowserWindowConstructorOptions

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

请使用 setWindowOpenHandler 显式设置新窗口的选项。

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

已移除：`additionalFeatures`

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

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

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

计划中的破坏性 API 更改 (13.0)

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

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

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

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

已移除：`shell.moveItemToTrash()`

已弃用的同步 shell.moveItemToTrash() API 已被移除。请使用异步 shell.trashItem() 代替。

// Removed in Electron 13
shell.moveItemToTrash(path)
// Replace with
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()

// Removed in Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)

// Removed in Electron 13
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)

// Removed in Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

已移除：`systemPreferences` 中的方法

以下 systemPreferences 方法已被弃用

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

请改用以下 nativeTheme 属性

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

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

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

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

已弃用：WebContents `new-window` 事件

WebContents 的 new-window 事件已被弃用。它由 webContents.setWindowOpenHandler() 替换。

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

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

计划中的破坏性 API 更改 (12.0)

已移除：Pepper Flash 支持

Chromium 已移除对 Flash 的支持，因此我们也必须这样做。有关更多详细信息，请参阅 Chromium 的 Flash 路线图。

默认值更改：`worldSafeExecuteJavaScript` 默认值为 `true`

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

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

默认值更改：`contextIsolation` 默认值为 `true`

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

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

另一个影响是，除非 nodeIntegration 为 true 且 contextIsolation 为 false，否则渲染器进程中无法使用 require()。

有关更多详细信息，请参阅：https://github.com/electron/electron/issues/23506

已移除：`crashReporter.getCrashesDirectory()`

crashReporter.getCrashesDirectory 方法已被移除。使用 app.getPath('crashDumps') 代替。

// Removed in Electron 12
crashReporter.getCrashesDirectory()
// Replace with
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。这意味着崩溃转储将以 Content-Encoding: gzip 标头上传到崩溃摄取服务器，并且主体将被压缩。

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

已弃用：`remote` 模块

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

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

// Replace with:
const { BrowserWindow } = require('@electron/remote')

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

已弃用：`shell.moveItemToTrash()`

同步的 shell.moveItemToTrash() 已被新的异步 shell.trashItem() 替换。

// Deprecated in Electron 12
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)

计划中的破坏性 API 更改 (11.0)

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

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

有关更多详细信息，请参阅 #23578。

计划中的破坏性 API 更改 (10.0)

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

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

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

已弃用：`crashReporter.getCrashesDirectory()`

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

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

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

从渲染器进程调用以下 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 } 已弃用。几乎所有崩溃摄取服务器都支持 gzip 压缩。此选项将在 Electron 的未来版本中移除。

默认值已更改：`enableRemoteModule` 默认值为 `false`

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

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

我们建议停止使用远程模块。

`protocol.unregisterProtocol`

`protocol.uninterceptProtocol`

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

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

`protocol.registerFileProtocol`

`protocol.registerBufferProtocol`

`protocol.registerStringProtocol`

`protocol.registerHttpProtocol`

`protocol.registerStreamProtocol`

`protocol.interceptFileProtocol`

`protocol.interceptStringProtocol`

`protocol.interceptBufferProtocol`

`protocol.interceptHttpProtocol`

`protocol.interceptStreamProtocol`

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

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

已注册或拦截的协议在导航发生之前对当前页面无效。

`protocol.isProtocolHandled`

此 API 已弃用，用户应改用 protocol.isProtocolRegistered 和 protocol.isProtocolIntercepted。

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

计划中的破坏性 API 更改 (9.0)

默认值已更改：在渲染器进程中加载非上下文感知的本机模块默认情况下被禁用

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

如果这影响到您，您可以暂时将 app.allowRendererProcessReuse 设置为 false 以恢复到旧行为。此标志将仅在 Electron 11 之前可用，因此您应计划更新您的本机模块以使其具有上下文感知能力。

有关更详细的信息，请参阅#18397。

已弃用：`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()

// Deprecated in Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)

// Deprecated in Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)

// Deprecated in Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

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

此 API 在 Electron 8.0 中已弃用，现已移除。

// Removed in Electron 9.0
webview.getWebContents()
// Replace with
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 已更改为使用结构化克隆算法，从而带来了显着的性能改进。为了帮助简化过渡，保留了旧的 IPC 序列化算法并将其用于某些无法使用结构化克隆序列化的对象。特别是，DOM 对象（例如 Element、Location 和 DOMMatrix）、由 C++ 类支持的 Node.js 对象（例如 process.env、Stream 的某些成员）以及由 C++ 类支持的 Electron 对象（例如 WebContents、BrowserWindow 和 WebFrame）无法使用结构化克隆序列化。每当调用旧算法时，都会打印弃用警告。

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

API 已更改：`shell.openItem` 现在为 `shell.openPath`

shell.openItem API 已被异步 shell.openPath API 替换。您可以在此处查看原始 API 建议和原因。

计划中的破坏性 API 更改 (8.0)

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

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

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

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

// From Electron 8:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => throws Error("() => {} could not be cloned.")

NaN、Infinity 和 -Infinity 现在将被正确序列化，而不是转换为 null。
包含循环引用的对象现在将被正确序列化，而不是转换为 null。
Set、Map、Error 和 RegExp 值将被正确序列化，而不是转换为 {}。
BigInt 值将被正确序列化，而不是转换为 null。
稀疏数组将按此类序列化，而不是转换为包含 null 的密集数组。
Date 对象将作为 Date 对象传输，而不是转换为其 ISO 字符串表示形式。
类型化数组（例如 Uint8Array、Uint16Array、Uint32Array 等）将按此类传输，而不是转换为 Node.js Buffer。
Node.js 的 Buffer 对象将被转换为 Uint8Array。您可以通过包装底层的 ArrayBuffer 将 Uint8Array 转换回 Node.js 的 Buffer。

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

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

// Deprecated
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme

// Deprecated
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors

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

已弃用：Atom.io Node 头文件 URL

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

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

替换为：https://www.electron.js.cn/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 中移除，因此不再可用。

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

HTML 文件输入上的 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 不再公开所选文件夹的路径。如果您需要所选文件夹的路径而不是文件夹内容，请参阅 dialog.showOpenDialog API（链接）。

API 更改：已承诺 API 的基于回调的版本

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

这些函数现在仅返回 Promise

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

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

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

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

API 更改：`win.setMenu(null)` 现已更改为 `win.removeMenu()`

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

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

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

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

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

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

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

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

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

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

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

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

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

// Deprecated
app.enableMixedSandbox()

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

已弃用：`Tray.setHighlightMode`

在 macOS Catalina 上，我们之前的托盘实现会失效。Apple 的原生替代方案不支持更改突出显示行为。

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

行为更改：通过 `nativeWindowOpen` 打开的子窗口中的 `nodeIntegration`

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

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

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

已弃用：`webFrame.setIsolatedWorld*` 被 `webFrame.setIsolatedWorldInfo` 替换

// Deprecated
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

API 更改：`webFrame.setSpellCheckProvider` 现在接受异步回调

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 不再接受回调参数，而是直接返回其数值。

// Deprecated
webContents.getZoomLevel((level) => {
  console.log(level)
})
// Replace with
const level = webContents.getZoomLevel()
console.log(level)

// Deprecated
webContents.getZoomFactor((factor) => {
  console.log(factor)
})
// Replace with
const factor = webContents.getZoomFactor()
console.log(factor)

计划中的破坏性 API 更改 (4.0)

以下列表包含 Electron 4.0 中进行的破坏性 API 更改。

`app.makeSingleInstance`

// Deprecated
app.makeSingleInstance((argv, cwd) => {
  /* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
  /* ... */
})

`app.releaseSingleInstance`

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

`app.getGPUInfo`

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

`win_delay_load_hook`

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

已移除：IA32 Linux 支持

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

破坏性 API 更改 (3.0)

以下列表包含 Electron 3.0 中的破坏性 API 更改。

`app`

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

// Deprecated
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property

`BrowserWindow`

// Deprecated
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)

// Deprecated
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play_pause') {
    // do something
  }
})
// Replace with
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play-pause') {
    // do something
  }
})

`clipboard`

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

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

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

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

`crashReporter`

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

`nativeImage`

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

`process`

// Deprecated
const info = process.getProcessMemoryInfo()

`screen`

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

`session`

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

`Tray`

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

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

`webContents`

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

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

`webFrame`

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

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

`<webview>`

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

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

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

Node 头文件 URL

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

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

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

破坏性 API 更改 (2.0)

以下列表包含 Electron 2.0 中进行的破坏性 API 更改。

`BrowserWindow`

// Deprecated
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)

`menu`

// Removed
menu.popup(browserWindow, 100, 200, 2)
// Replaced with
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

`nativeImage`

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

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

`process`

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

`webContents`

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

`webFrame`

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

`<webview>`

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

重复的 ARM 资产

每个 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)
- 行为更改：app 上 login 事件的 webContents 属性
- 已弃用：systemPreferences.accessibilityDisplayShouldReduceTransparency
计划中的破坏性 API 更改 (32.0)
- 已移除：File.path
- 已弃用：WebContents 上的 clearHistory、canGoBack、goBack、canGoForward、goForward、goToIndex、canGoToOffset、goToOffset
计划中的破坏性 API 更改 (31.0)
- 已移除：WebSQL 支持
- 行为更改：nativeImage.toDataURL 将保留 PNG 颜色空间
- 行为更改：window.flashFrame(bool) 将在 macOS 上持续闪烁停靠图标
计划中的破坏性 API 更改 (30.0)
- 行为更改：跨源 iframe 现在使用权限策略来访问功能
- 已移除：--disable-color-correct-rendering 开关
- 行为更改：macOS 上 BrowserView.setAutoResize 的行为
- 已弃用：BrowserView
- 已移除：WebContents 上 context-menu 事件的 params.inputFormType 属性
- 已移除：process.getIOCounters()
计划中的破坏性 API 更改 (29.0)
- 行为更改：ipcRenderer 不能再通过 contextBridge 发送
- 已移除：app 上的 renderer-process-crashed 事件
- 已移除：WebContents 和 <webview> 上的 crashed 事件
- 已移除：app 上的 gpu-process-crashed 事件
计划中的破坏性 API 更改 (28.0)
- 行为更改：将 WebContents.backgroundThrottling 设置为 false 会影响主机 BrowserWindow 中的所有 WebContents
- 已移除：BrowserWindow.setTrafficLightPosition(position)
- 已移除：BrowserWindow.getTrafficLightPosition()
- 已移除：ipcRenderer.sendTo()
- 已移除：app.runningUnderRosettaTranslation
- 已弃用：app 上的 renderer-process-crashed 事件
- 已弃用：WebContents 上 context-menu 事件的 params.inputFormType 属性
- 已弃用：WebContents 和 <webview> 上的 crashed 事件
- 已弃用：app 上的 gpu-process-crashed 事件
计划中的破坏性 API 更改 (27.0)
- 已移除：macOS 10.13 / 10.14 支持
- 已弃用：ipcRenderer.sendTo()
- 已移除：systemPreferences 中的颜色方案事件
- 已移除：macOS 上的一些 window.setVibrancy 选项
- 已移除：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)
- 已弃用：protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol 和 protocol.isProtocol{Registered,Intercepted}
- 已弃用：BrowserWindow.setTrafficLightPosition(position)
- 已弃用：BrowserWindow.getTrafficLightPosition()
计划中的重大 API 更改 (24.0)
- API 更改：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 更改：webContents.printToPDF()
计划中的重大 API 更改 (20.0)
- 移除：macOS 10.11 / 10.12 支持
- 默认值更改：默认情况下，没有 nodeIntegration: true 的渲染器会被沙盒化
- 移除：Linux 上的 skipTaskbar
- API 更改：session.setDevicePermissionHandler(handler)
计划中的重大 API 更改 (19.0)
- 移除：IA32 Linux 二进制文件
计划中的重大 API 更改 (18.0)
- 移除：nativeWindowOpen
计划中的重大 API 更改 (17.0)
- 移除：渲染器中的 desktopCapturer.getSources
- 已弃用：nativeWindowOpen
计划中的重大 API 更改 (16.0)
- 行为更改：Linux 上的 crashReporter 实现切换到 Crashpad
- 已弃用：渲染器中的 desktopCapturer.getSources
计划中的重大 API 更改 (15.0)
- 默认值更改：nativeWindowOpen 默认值为 true
- 已弃用：app.runningUnderRosettaTranslation
计划中的重大 API 更改 (14.0)
- 移除：remote 模块
- 移除：app.allowRendererProcessReuse
- 移除：浏览器窗口关联性
- 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.{destroy, fromId, fromWebContents, getAllViews} 和 BrowserView 的 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)
- 默认值更改：默认情况下，禁用在渲染器进程中加载非上下文感知的原生模块
- 已弃用：BrowserWindow 扩展 API
- 移除：<webview>.getWebContents()
- 移除：webFrame.setLayoutZoomLevelLimits()
- 行为更改：通过 IPC 发送非 JS 对象现在会抛出异常
- API 更改：shell.openItem 现在是 shell.openPath
计划中的重大 API 更改 (8.0)
- 行为更改：通过 IPC 发送的值现在使用结构化克隆算法进行序列化
- 已弃用：<webview>.getWebContents()
- 已弃用：webFrame.setLayoutZoomLevelLimits()
- systemPreferences 中的已弃用事件
- 已弃用：systemPreferences 中的方法
计划中的重大 API 更改 (7.0)
- 已弃用：Atom.io 节点头文件 URL
- API 更改：session.clearAuthCache() 不再接受选项
- API 更改：powerMonitor.querySystemIdleState 现在是 powerMonitor.getSystemIdleState
- API 更改：powerMonitor.querySystemIdleTime 现在是 powerMonitor.getSystemIdleTime
- API 更改：webFrame.setIsolatedWorldInfo 替换了单独的方法
- 移除：getBlinkMemoryInfo 上的 marked 属性
- 行为更改：<input type="file"/> 的 webkitdirectory 属性现在列出目录内容
- API 更改：Promise 化 API 的基于回调的版本
计划中的重大 API 更改 (6.0)
- API 更改：win.setMenu(null) 现在是 win.removeMenu()
- API 更改：渲染器进程中的 electron.screen 应该通过 remote 访问
- API 更改：在沙盒化的渲染器中 require() 节点内置模块不再隐式加载 remote 版本
- 已弃用：powerMonitor.querySystemIdleState 被 powerMonitor.getSystemIdleState 替换
- 已弃用：powerMonitor.querySystemIdleTime 被 powerMonitor.getSystemIdleTime 替换
- 已弃用：不再需要 app.enableMixedSandbox()
- 已弃用：Tray.setHighlightMode
计划中的重大 API 更改 (5.0)
- 默认值更改：nodeIntegration 和 webviewTag 默认值为 false，contextIsolation 默认值为 true
- 行为更改：通过 nativeWindowOpen 打开的子窗口中的 nodeIntegration
- API 更改：注册特权方案现在必须在应用程序就绪之前完成
- 已弃用：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>
- 节点头文件 URL
重大 API 更改 (2.0)
- BrowserWindow
- menu
- nativeImage
- process
- webContents
- webFrame
- <webview>
- 重复的 ARM 资产

重大变更类型​

计划中的重大 API 变更 (33.0)​

行为更改：app 上的 login 事件中的 webContents 属性​

已弃用：systemPreferences.accessibilityDisplayShouldReduceTransparency​

计划中的重大 API 变更 (32.0)​

已移除：File.path​

已弃用：WebContents 上的 clearHistory、canGoBack、goBack、canGoForward、goForward、goToIndex、canGoToOffset、goToOffset​

计划中的重大 API 变更 (31.0)​

已移除：WebSQL 支持​

行为更改：nativeImage.toDataURL 将保留 PNG 色彩空间​

行为更改：window.flashFrame(bool) 将在 macOS 上连续闪烁 Dock 图标​

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

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

已移除：--disable-color-correct-rendering 开关​

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

已弃用：BrowserView​

已移除：WebContents 上的 context-menu 事件中的 params.inputFormType 属性​

已移除：process.getIOCounters()​

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

行为更改：ipcRenderer 不能再通过 contextBridge 发送​

已移除：app 上的 renderer-process-crashed 事件​

已移除：WebContents 和 <webview> 上的 crashed 事件​

已移除：app 上的 gpu-process-crashed 事件​

计划中的破坏性 API 更改 (28.0)​

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

已移除：BrowserWindow.setTrafficLightPosition(position)​

已移除：BrowserWindow.getTrafficLightPosition()​

已移除：ipcRenderer.sendTo()​

已移除：app.runningUnderRosettaTranslation​

已弃用：app 上的 renderer-process-crashed 事件​

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

已弃用：WebContents 和 <webview> 上的 crashed 事件​

已弃用：app 上的 gpu-process-crashed 事件​

计划中的破坏性 API 更改 (27.0)​

已移除：macOS 10.13 / 10.14 支持​

已弃用：ipcRenderer.sendTo()​

已移除：systemPreferences 中的颜色方案事件​

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

已移除：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)​

已弃用：protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol 和 protocol.isProtocol{Registered,Intercepted}​

已弃用：BrowserWindow.setTrafficLightPosition(position)​

已弃用：BrowserWindow.getTrafficLightPosition()​

计划中的破坏性 API 更改 (24.0)​

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

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

已移除：macOS 10.11 / 10.12 支持​

默认值更改：默认情况下，没有nodeIntegration: true 的渲染器处于沙箱状态​

已移除：Linux 上的skipTaskbar​

API 更改：session.setDevicePermissionHandler(handler)​

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

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

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

已移除：nativeWindowOpen​

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

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

已弃用：nativeWindowOpen​

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

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

重大变更类型

计划中的重大 API 变更 (33.0)

行为更改：`app` 上的 `login` 事件中的 `webContents` 属性

已弃用：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

计划中的重大 API 变更 (32.0)

已移除：`File.path`

已弃用：`WebContents` 上的 `clearHistory`、`canGoBack`、`goBack`、`canGoForward`、`goForward`、`goToIndex`、`canGoToOffset`、`goToOffset`

计划中的重大 API 变更 (31.0)

已移除：`WebSQL` 支持

行为更改：`nativeImage.toDataURL` 将保留 PNG 色彩空间

行为更改：`window.flashFrame(bool)` 将在 macOS 上连续闪烁 Dock 图标

计划中的重大 API 变更 (30.0)

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

已移除：`--disable-color-correct-rendering` 开关

行为更改：macOS 上 `BrowserView.setAutoResize` 的行为

已弃用：`BrowserView`

已移除：`WebContents` 上的 `context-menu` 事件中的 `params.inputFormType` 属性

已移除：`process.getIOCounters()`

计划中的重大 API 变更 (29.0)

行为更改：`ipcRenderer` 不能再通过 `contextBridge` 发送

已移除：`app` 上的 `renderer-process-crashed` 事件

已移除：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已移除：`app` 上的 `gpu-process-crashed` 事件

计划中的破坏性 API 更改 (28.0)

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

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

已移除：`BrowserWindow.getTrafficLightPosition()`

已移除：`ipcRenderer.sendTo()`

已移除：`app.runningUnderRosettaTranslation`

已弃用：`app` 上的 `renderer-process-crashed` 事件

已弃用：`WebContents` 上 `context-menu` 的 `params.inputFormType` 属性

已弃用：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已弃用：`app` 上的 `gpu-process-crashed` 事件

计划中的破坏性 API 更改 (27.0)

已移除：macOS 10.13 / 10.14 支持

已弃用：`ipcRenderer.sendTo()`

已移除：`systemPreferences` 中的颜色方案事件

已移除：macOS 上的一些 `window.setVibrancy` 选项

已移除：`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)

已弃用：`protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` 和 `protocol.isProtocol{Registered,Intercepted}`

已弃用：`BrowserWindow.setTrafficLightPosition(position)`

已弃用：`BrowserWindow.getTrafficLightPosition()`

计划中的破坏性 API 更改 (24.0)

API 变更：`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 更改：`webContents.printToPDF()`

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

已移除：macOS 10.11 / 10.12 支持

默认值更改：默认情况下，没有`nodeIntegration: true` 的渲染器处于沙箱状态

已移除：Linux 上的`skipTaskbar`

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

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

已移除：IA32 Linux 二进制文件

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

已移除：`nativeWindowOpen`

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

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

已弃用：`nativeWindowOpen`

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

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