重大变更
重大变更将在此处记录,并在可能的情况下,至少在变更发生一个主要版本之前,将弃用警告添加到 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 阻止列表支持
WebUSB 和 Web Serial 现在支持 Chromium 使用并分别在其规范中概述的 WebUSB 阻止列表和 Web Serial 阻止列表。
要禁用这些功能,用户可以传递 disable-usb-blocklist
和 disable-serial-blocklist
作为命令行标志。
已移除:ProtocolResponse
中 session
属性的 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
上的 isDefault
和 status
属性
这些属性已从 PrinterInfo 对象中移除,因为它们已从上游 Chromium 中移除。
已移除:Session.clearStorageData(options)
中 quota
类型 syncable
调用 Session.clearStorageData(options)
时,不再支持 options.quota
类型 syncable
,因为它已从上游 Chromium 移除。
已弃用:ProtocolResponse
中 session
属性的 null
值
此前,将 ProtocolResponse.session 属性设置为 null
会创建一个随机的独立会话。 这不再受支持。
由于开销成本,不建议在此处使用单用途会话;但是,需要保留此行为的旧代码可以通过使用 session.fromPartition(some_random_string)
创建一个随机会话,然后在 ProtocolResponse.session
中使用它来模拟此行为。
已弃用:Session.clearStorageData(options)
中的 quota
属性
调用 Session.clearStorageData(options)
时,options.quota
属性已弃用。 由于 syncable
类型已移除,只剩下 'temporary'
类型,因此指定它是不必要的。
已弃用:session
上的扩展方法和事件
session.loadExtension
、session.removeExtension
、session.getExtension
、session.getAllExtensions
、'extension-loaded' 事件、'extension-unloaded' 事件和 'extension-ready' 事件都已移至新的 session.extensions
类。
已移除:systemPreferences.isAeroGlassEnabled()
systemPreferences.isAeroGlassEnabled()
函数已移除,没有替代。 自 Electron 23 以来,它始终返回 true
,Electron 23 仅支持 Windows 10+,其中 DWM 组合不再可禁用。
已更改:在 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
上的 setPreloads
、getPreloads
registerPreloadScript
、unregisterPreloadScript
和 getPreloadScripts
作为已弃用方法的替代品引入。 这些新的 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')
})
已弃用:WebContents
上 console-message
事件中的 level
、message
、line
和 sourceId
参数
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
现在是一个字符串,可能的值为 info
、warning
、error
和 debug
。
行为变更:WebRequestFilter
的 urls
属性。
此前,空的 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 组合不再可禁用。
计划中的重大 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.loadURL
、WebContents.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')
行为变更:app
上 login
的 webContents
属性
当 login
事件因来自带有 respondToAuthRequestsFromMainProcess
选项创建的实用进程的请求而触发时,app
的 login
事件中的 webContents
属性将为 null
。
已弃用:BrowserWindowConstructorOption.type
中的 textured
选项
BrowserWindowConstructorOptions
中 type
的 textured
选项已弃用,没有替代。 此选项依赖于 macOS 上的 NSWindowStyleMaskTexturedBackground
样式掩码,该掩码已弃用,没有替代方案。
已移除:macOS 10.15 支持
macOS 10.15 (Catalina) 不再受 Chromium 支持。
旧版本的 Electron 将继续在 Catalina 上运行,但运行 Electron v33.0.0 及更高版本将需要 macOS 11 (Big Sur) 或更高版本。
行为变更:原生模块现在需要 C++20
由于上游的变化,V8 和 Node.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 已移至 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)
行为变更:userData
中 databases
目录将被删除
如果您的 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()
已移除: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 支持
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
来替代它。
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'
这些选项此前已弃用,并已在 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}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://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-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 内存笼已启用,这对于将非 V8 内存包装到 ArrayBuffer
或 Buffer
中的原生模块有影响。 有关详细信息,请参阅关于 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: 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 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.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()
请改用会话 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()
请改用会话 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 中,旧的序列化算法已被移除,发送此类不可序列化对象现在会抛出“object could not be cloned”错误。
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 字符串表示形式。- Typed Arrays (如
Uint8Array
,Uint16Array
,Uint32Array
等) 将按原样传输,而不是转换为 Node.jsBuffer
。 - Node.js
Buffer
对象将作为Uint8Array
s 传输。您可以通过包装底层ArrayBuffer
将Uint8Array
转换回 Node.jsBuffer
。
Buffer.from(value.buffer, value.byteOffset, value.byteLength)
发送任何非原生 JS 类型的对象,例如 DOM 对象(例如 Element
、Location
、DOMMatrix
)、Node.js 对象(例如 process.env
、Stream
)或 Electron 对象(例如 WebContents
、BrowserWindow
、WebFrame
)已被弃用。在 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()
#15742app.dock.show()
#16904contentTracing.getCategories()
#16583contentTracing.getTraceBufferUsage()
#16600contentTracing.startRecording()
#16584contentTracing.stopRecording()
#16584contents.executeJavaScript()
#17312cookies.flushStore()
#16464cookies.get()
#16464cookies.remove()
#16464cookies.set()
#16464debugger.sendCommand()
#16861dialog.showCertificateTrustDialog()
#17181inAppPurchase.getProducts()
#17355inAppPurchase.purchaseProduct()
#17355netLog.stopLogging()
#16862session.clearAuthCache()
#17259session.clearCache()
#17185session.clearHostResolverCache()
#17229session.clearStorageData()
#17249session.getBlobData()
#17303session.getCacheSize()
#17185session.resolveProxy()
#17222session.setProxy()
#17222shell.openExternal()
#16176webContents.loadFile()
#15855webContents.loadURL()
#15855webContents.hasServiceWorker()
#16535webContents.printToPDF()
#16795webContents.savePage()
#16742webFrame.executeJavaScript()
#17312webFrame.executeJavaScriptInIsolatedWorld()
#17312webviewTag.executeJavaScript()
#17312win.capturePage()
#15743
这些函数现在有两种形式:同步和基于 Promise 的异步形式
dialog.showMessageBox()
/dialog.showMessageBoxSync()
#17298dialog.showOpenDialog()
/dialog.showOpenDialogSync()
#16973dialog.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)
默认值已更改: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 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)
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 版本开始,将不再发布未带前缀的文件。