跳到主要内容

重大变更

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

重大变更类型

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

  • API 变更: API 以一种未更新的代码一定会抛出异常的方式进行了更改。
  • 行为变更: Electron 的行为已更改,但不会因此必然抛出异常。
  • 默认值变更: 依赖旧默认值的代码可能会中断,不一定会抛出异常。 旧行为可以通过明确指定值来恢复。
  • 已弃用: API 已标记为弃用。 该 API 将继续运行,但会发出弃用警告,并将在未来版本中移除。
  • 已移除: API 或功能已移除,Electron 不再支持。

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

Utility 进程未处理拒绝行为变更

现在,当 Utility 进程发生未处理的拒绝时,将发出错误消息警告,而不是崩溃进程。

要恢复以前的行为,您可以使用

process.on('unhandledRejection', () => {
process.exit(1)
})

行为变更:process.exit() 同步终止 Utility 进程

在 Utility 进程中调用 process.exit() 现在将同步终止 Utility 进程。 这使得 process.exit() 的行为与 Node.js 行为保持一致。

请参阅 Node.js 文档PR #45690 以了解其潜在影响,例如在调用 console.log() 之前调用 process.exit()

行为变更:WebUSB 和 WebSerial 阻止列表支持

WebUSBWeb Serial 现在支持 Chromium 使用并分别在其规范中概述的 WebUSB 阻止列表Web Serial 阻止列表

要禁用这些功能,用户可以传递 disable-usb-blocklistdisable-serial-blocklist 作为命令行标志。

已移除:ProtocolResponsesession 属性的 null

此已弃用功能已移除。

此前,将 ProtocolResponse.session 属性设置为 null 会创建一个随机的独立会话。 这不再受支持。

由于开销成本,不建议在此处使用单用途会话;但是,需要保留此行为的旧代码可以通过使用 session.fromPartition(some_random_string) 创建一个随机会话,然后在 ProtocolResponse.session 中使用它来模拟此行为。

行为变更:Linux 上 BrowserWindow.IsVisibleOnAllWorkspaces()

如果窗口当前不可见,BrowserWindow.IsVisibleOnAllWorkspaces() 现在将在 Linux 上返回 false。

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

行为变更:app.commandLine

app.commandLine 会将大写开关和参数转换为小写。

app.commandLine 仅用于处理 Chromium 开关 (不区分大小写),通过 app.commandLine 传递的开关不会传递给任何子进程。

如果您曾使用 app.commandLine 来控制主进程的行为,您应该通过 process.argv 来完成。

已弃用:NativeImage.getBitmap()

NativeImage.toBitmap() 返回位图的新分配副本。 NativeImage.getBitmap() 最初是一个替代函数,返回原始位图而不是副本。 自引入沙盒以来,此功能已更改,因此两者都返回副本并且功能等效。

客户端代码应改为调用 NativeImage.toBitmap()

// Deprecated
bitmap = image.getBitmap()
// Use this instead
bitmap = image.toBitmap()

已移除:PrinterInfo 上的 isDefaultstatus 属性

这些属性已从 PrinterInfo 对象中移除,因为它们已从上游 Chromium 中移除。

已移除:Session.clearStorageData(options)quota 类型 syncable

调用 Session.clearStorageData(options) 时,不再支持 options.quota 类型 syncable,因为它已从上游 Chromium 移除

已弃用:ProtocolResponsesession 属性的 null

此前,将 ProtocolResponse.session 属性设置为 null 会创建一个随机的独立会话。 这不再受支持。

由于开销成本,不建议在此处使用单用途会话;但是,需要保留此行为的旧代码可以通过使用 session.fromPartition(some_random_string) 创建一个随机会话,然后在 ProtocolResponse.session 中使用它来模拟此行为。

已弃用:Session.clearStorageData(options) 中的 quota 属性

调用 Session.clearStorageData(options) 时,options.quota 属性已弃用。 由于 syncable 类型已移除,只剩下 'temporary' 类型,因此指定它是不必要的。

已弃用:session 上的扩展方法和事件

session.loadExtensionsession.removeExtensionsession.getExtensionsession.getAllExtensions、'extension-loaded' 事件、'extension-unloaded' 事件和 'extension-ready' 事件都已移至新的 session.extensions 类。

已移除:systemPreferences.isAeroGlassEnabled()

systemPreferences.isAeroGlassEnabled() 函数已移除,没有替代。 自 Electron 23 以来,它始终返回 true,Electron 23 仅支持 Windows 10+,其中 DWM 组合不再可禁用。

https://learn.microsoft.com/zh-cn/windows/win32/dwm/composition-ovw#disabling-dwm-composition-windows7-and-earlier

已更改:在 GNOME 中运行时的 GTK 4 是默认设置

上游更改后,GTK 4 现在是运行 GNOME 时的默认设置。

在极少数情况下,这可能会导致某些应用程序或配置出现以下错误消息:

Gtk-ERROR **: 11:30:38.382: GTK 2/3 symbols detected. Using GTK 2/3 and GTK 4 in the same process is not supported

受影响的用户可以通过指定 gtk-version 命令行标志来解决此问题

$ electron --gtk-version=3   # or --gtk-version=2

同样的操作也可以通过 app.commandLine.appendSwitch 函数完成。

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

行为变更:Linux 上 Dialog API 的 defaultPath 选项

在 Linux 上,文件对话框所需的门户版本已从 4 还原为 3。 使用门户文件选择器对话框时,除非门户后端版本为 4 或更高,否则不支持使用 Dialog API 的 defaultPath 选项。 --xdg-portal-required-version 命令行开关可用于强制应用程序使用所需的版本。 有关详细信息,请参阅 #44426

已弃用:session.serviceWorkers 上的 getFromVersionID

session.serviceWorkers.fromVersionID(versionId) API 已弃用,取而代之的是 session.serviceWorkers.getInfoFromVersionID(versionId)。 引入 session.serviceWorkers.getWorkerFromVersionID(versionId) API 后,此更改旨在更清楚地说明返回的是哪个对象。

// Deprecated
session.serviceWorkers.fromVersionID(versionId)

// Replace with
session.serviceWorkers.getInfoFromVersionID(versionId)

已弃用:Session 上的 setPreloadsgetPreloads

registerPreloadScriptunregisterPreloadScriptgetPreloadScripts 作为已弃用方法的替代品引入。 这些新的 API 允许第三方库注册预加载脚本,而无需替换现有脚本。 此外,新的 type 选项允许除了 frame 之外的额外预加载目标。

// Deprecated
session.setPreloads([path.join(__dirname, 'preload.js')])

// Replace with:
session.registerPreloadScript({
type: 'frame',
id: 'app-preload',
filePath: path.join(__dirname, 'preload.js')
})

已弃用:WebContentsconsole-message 事件中的 levelmessagelinesourceId 参数

WebContents 上的 console-message 事件已更新,以提供 Event 参数的详细信息。

// Deprecated
webContents.on('console-message', (event, level, message, line, sourceId) => {})

// Replace with:
webContents.on('console-message', ({ level, message, lineNumber, sourceId, frame }) => {})

此外,level 现在是一个字符串,可能的值为 infowarningerrordebug

行为变更:WebRequestFilterurls 属性。

此前,空的 urls 数组被解释为包含所有 URL。 要明确包含所有 URL,开发人员现在应使用 <all_urls> 模式,这是一个指定的 URL 模式,它匹配所有可能的 URL。 此更改阐明了意图并确保了更可预测的行为。

// Deprecated
const deprecatedFilter = {
urls: []
}

// Replace with
const newFilter = {
urls: ['<all_urls>']
}

已弃用:systemPreferences.isAeroGlassEnabled()

systemPreferences.isAeroGlassEnabled() 函数已弃用,没有替代。 自 Electron 23 以来,它始终返回 true,Electron 23 仅支持 Windows 10+,其中 DWM 组合不再可禁用。

https://learn.microsoft.com/zh-cn/windows/win32/dwm/composition-ovw#disabling-dwm-composition-windows7-and-earlier

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

行为变更:在 Windows 上全屏期间将隐藏菜单栏

这使得行为与 Linux 保持一致。 以前的行为:在 Windows 上全屏期间菜单栏仍然可见。 新行为:在 Windows 上全屏期间菜单栏隐藏。

更正:此前此项被列为 Electron 33 中的重大变更,但首次发布于 Electron 34。

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

已弃用:document.execCommand("paste")

同步剪贴板读取 API document.execCommand("paste") 已弃用,取而代之的是 异步剪贴板 API。 这是为了与浏览器默认设置保持一致。

WebPreferences 中触发此 API 权限检查的 enableDeprecatedPaste 选项以及相关的权限类型 deprecated-sync-clipboard-read 也已弃用。

行为变更:帧属性可能会检索分离的 WebFrameMain 实例或根本不检索

提供对 WebFrameMain 实例访问的 API 可能会返回一个 frame.detached 设置为 true 的实例,或者可能返回 null

当帧执行跨域导航时,它会进入分离状态,在此状态下它不再附加到页面。 在此状态下,它可能会在删除之前运行卸载处理程序。 如果在此状态期间发送 IPC,frame.detached 将设置为 true,帧随后很快被销毁。

接收事件时,务必在收到后立即访问 WebFrameMain 属性。 否则,不能保证它指向与收到时相同的网页。 为了避免不一致的预期,在网页发生更改的后期访问情况下,Electron 将返回 null

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 处理

由于 Chromium 中为支持 非特殊方案 URL 所做的更改,使用 Windows 文件路径的自定义协议 URL 将不再与已弃用的 protocol.registerFileProtocol 以及 BrowserWindow.loadURLWebContents.loadURL<webview>.loadURL 上的 baseURLForDataURL 属性正确配合使用。 protocol.handle 也将不适用于这些类型的 URL,但这并非更改,因为它一直都是如此。

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

行为变更:apploginwebContents 属性

login 事件因来自带有 respondToAuthRequestsFromMainProcess 选项创建的实用进程的请求而触发时,applogin 事件中的 webContents 属性将为 null

已弃用:BrowserWindowConstructorOption.type 中的 textured 选项

BrowserWindowConstructorOptionstypetextured 选项已弃用,没有替代。 此选项依赖于 macOS 上的 NSWindowStyleMaskTexturedBackground 样式掩码,该掩码已弃用,没有替代方案。

已移除:macOS 10.15 支持

macOS 10.15 (Catalina) 不再受 Chromium 支持。

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

行为变更:原生模块现在需要 C++20

由于上游的变化,V8Node.js 现在都要求 C++20 作为最低版本。 使用原生 Node 模块的开发者应该使用 --std=c++20 而不是 --std=c++17 来构建他们的模块。 使用 gcc9 或更低版本的镜像可能需要更新到 gcc10 才能编译。 更多详细信息请参阅 #43555

已弃用: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]').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}`)
}
})

已弃用:WebContents 上的 clearHistory, canGoBack, goBack, canGoForward, goForward, goToIndex, canGoToOffset, goToOffset

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

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

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

行为变更:userDatadatabases 目录将被删除

如果您的 app.getPath('userData') 返回的目录中有一个名为 databases 的目录,它将在 Electron 32 首次运行时被删除。 databases 目录曾被 WebSQL 使用,该功能在 Electron 31 中已移除。 Chromium 现在执行清理操作以删除此目录。 参阅 问题 #45396

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

已移除:WebSQL 支持

Chromium 已移除上游对 WebSQL 的支持,将其转换为仅限 Android。 更多信息请参阅 Chromium 移除意图讨论

行为变更:nativeImage.toDataURL 将保留 PNG 颜色空间

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

更多信息请参阅 crbug.com/332584706

行为变更:macOS 上 window.flashFrame(bool) 将持续闪烁 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()

已移除:WebContentscontext-menu 事件中的 params.inputFormType 属性

WebContentscontext-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 来替代它。

IpcRendererEventsenderIdsenderIsMainFrame 属性也已移除。

已移除:app.runningUnderRosettaTranslation

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

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

已弃用:apprenderer-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) => { /* ... */ })

已弃用:WebContentscontext-menu 事件中的 params.inputFormType 属性

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

已弃用:appgpu-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 支持

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

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

已弃用:ipcRenderer.sendTo()

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

IpcRendererEventsenderIdsenderIsMainFrame 属性也已弃用。

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

这些选项此前已弃用,并已在 Apple 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}AppLevelAppearancesystemPreferences.appLevelAppearance

systemPreferences.getAppLevelAppearancesystemPreferences.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.getColoralternate-selected-control-text

systemPreferences.getColoralternate-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}AppLevelAppearancesystemPreferences.appLevelAppearance

systemPreferences.getAppLevelAppearancesystemPreferences.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.getColoralternate-selected-control-text

systemPreferences.getColoralternate-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}Protocolprotocol.isProtocol{Registered,Intercepted}

protocol.register*Protocolprotocol.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://electron.js.cn' })
})

// Replace with
protocol.handle('some-protocol', () => {
return net.fetch('https://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,以反映传入的大小将是创建的缩略图的大小。 此前,如果图像小于 maxSize,Windows 不会将其放大,而 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 的区域重叠时,无论 CSS 层叠如何,macOS 上的 no-drag 区域始终优先。 也就是说,如果 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-beginscroll-touch-endscroll-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-beginscroll-touch-endscroll-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 内存笼已启用,这对于将非 V8 内存包装到 ArrayBufferBuffer 中的原生模块有影响。 有关详细信息,请参阅关于 V8 内存笼的博客文章

API 变更:webContents.printToPDF()

webContents.printToPDF() 已修改以符合 Chrome DevTools 协议中的 Page.printToPDF。 此更改是为了解决上游导致我们之前的实现不可行且充满 bug 的更改。

参数已更改

  • 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: truesandbox: 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 15 之前,window.open 默认情况下会被填充以使用 BrowserWindowProxy。 这意味着 window.open('about:blank') 无法打开同步可脚本化的子窗口,以及其他不兼容性。 自 Electron 15 以来,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

已移除:Browser Window Affinity

构造新 BrowserWindow 时的 affinity 选项将作为我们更紧密地与 Chromium 进程模型对齐的计划的一部分而被移除,以提高安全性、性能和可维护性。

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

API 变更:window.open()

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

如果您使用此参数设置窗口标题,则可以改为使用 win.setTitle(title)

已移除:worldSafeExecuteJavaScript

在 Electron 14 中,worldSafeExecuteJavaScript 将被移除。 没有替代方案,请确保您的代码在此属性启用时正常工作。 自 Electron 12 以来,它已默认启用。

如果您使用 webFrame.executeJavaScriptwebFrame.executeJavaScriptInIsolatedWorld,您将受到此更改的影响。 您需要确保这些方法返回的值受 Context Bridge API 支持,因为这些方法使用相同的值传递语义。

已移除:BrowserWindowConstructorOptions 从父窗口继承

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

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

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

已移除:additionalFeatures

WebContents 的 new-windowdid-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。 您应该使用 requestingOriginembeddingOriginsecurityOrigin 属性来正确响应权限检查。 由于 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()

请改用会话 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

另一个影响是,除非 nodeIntegrationtruecontextIsolationfalse,否则不能在渲染器进程中使用 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.startcompress 选项的默认值已从 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}BrowserViewid 属性

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

有关详细信息,请参见 #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 模块中唯一未弃用的方法是 addExtraParameterremoveExtraParametergetParameters

所有上述方法从主进程调用时仍未弃用。

更多详细信息请参阅 #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.isProtocolRegisteredprotocol.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()

请改用会话 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 对象(例如 ElementLocationDOMMatrix)、由 C++ 类支持的 Node.js 对象(例如 process.envStream 的某些成员)以及由 C++ 类支持的 Electron 对象(例如 WebContentsBrowserWindowWebFrame)无法通过结构化克隆序列化。每当调用旧算法时,都会打印弃用警告。

在 Electron 9.0 中,旧的序列化算法已被移除,发送此类不可序列化对象现在会抛出“object could not be cloned”错误。

API 已更改:shell.openItem 现在是 shell.openPath

shell.openItem API 已被异步的 shell.openPath API 取代。您可以在此处查看原始 API 提案和原因。

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

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

用于序列化通过 IPC 发送的对象(通过 ipcRenderer.sendipcRenderer.sendSyncWebContents.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.")
  • NaNInfinity-Infinity 现在将正确序列化,而不是转换为 null
  • 包含循环引用的对象现在将正确序列化,而不是转换为 null
  • SetMapErrorRegExp 值将正确序列化,而不是转换为 {}
  • BigInt 值将正确序列化,而不是转换为 null
  • 稀疏数组将按原样序列化,而不是转换为包含 null 的密集数组。
  • Date 对象将作为 Date 对象传输,而不是转换为其 ISO 字符串表示形式。
  • Typed Arrays (如 Uint8Array, Uint16Array, Uint32Array 等) 将按原样传输,而不是转换为 Node.js Buffer
  • Node.js Buffer 对象将作为 Uint8Arrays 传输。您可以通过包装底层 ArrayBufferUint8Array 转换回 Node.js Buffer
Buffer.from(value.buffer, value.byteOffset, value.byteLength)

发送任何非原生 JS 类型的对象,例如 DOM 对象(例如 ElementLocationDOMMatrix)、Node.js 对象(例如 process.envStream)或 Electron 对象(例如 WebContentsBrowserWindowWebFrame)已被弃用。在 Electron 8 中,这些对象将像以前一样序列化并带有一个 DeprecationWarning 消息,但从 Electron 9 开始,发送这些类型的对象将抛出“could not be cloned”错误。

已弃用:<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 Headers URL

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

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

替换为:https://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,该 FileList 返回一个对应于所选文件夹的 File

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

举例说明,假设一个文件夹具有以下结构:

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

在 Electron <=6 中,这将返回一个包含以下 File 对象的 FileList

path/to/folder

在 Electron 7 中,这将返回一个包含以下 File 对象的 FileList

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

请注意,webkitdirectory 不再暴露所选文件夹的路径。如果您需要所选文件夹的路径而不是文件夹内容,请参阅 dialog.showOpenDialog API(链接)。

API 已更改:Promise 化的 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() Node 内置模块不再隐式加载 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 下,我们之前的 Tray 实现会中断。Apple 的原生替代方案不支持更改高亮行为。

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

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

默认值已更改:nodeIntegrationwebviewTag 默认为 false,contextIsolation 默认为 true

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

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

例如:重新启用 webviewTag

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

行为已更改:通过 nativeWindowOpen 打开的子窗口中的 nodeIntegration

使用 nativeWindowOpen 选项打开的子窗口将始终禁用 Node.js 集成,除非 nodeIntegrationInSubFramestrue

API 已更改:特权方案的注册现在必须在应用程序就绪之前完成

渲染器进程 API webFrame.registerURLSchemeAsPrivilegedwebFrame.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.getZoomLevelwebContents.getZoomFactor 现在是同步的

webContents.getZoomLevelwebContents.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 Headers URL

这是在 .npmrc 文件中指定为 disturl 或在构建原生 Node 模块时作为 --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)
// 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.electronprocess.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.zipelectron-v1.7.3-linux-armv7l.zip。带有 v7l 前缀的资产是为了向用户明确它支持的 ARM 版本,并将其与将来可能生成的 armv6l 和 arm64 资产区分开来。

未带前缀的文件仍在发布,以避免破坏任何可能正在使用它的设置。从 2.0 版本开始,将不再发布未带前缀的文件。

有关详情,请参阅 69867189