重大更改
这里将记录重大更改,并在可能的情况下向JS代码添加弃用警告,在这更改之前至少会有一个重要版本.
Breaking Changes
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.
FIXME 注释
代码注释中添加的FIXME字符来表示以后的版本应该被修复的问题. 参考 https://github.com/electron/electron/search?q=fixme
FIXME comments
The FIXME string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme
计划重写的 API (7.0)
Planned Breaking API Changes (7.0)
shell.openExternalSync(url[, options])
// Deprecated
shell.openExternalSync(url)
// Replace with
async function openThing (url) {
await shell.openExternal(url)
}shell.openExternalSync(url[, options])
// Deprecated
shell.openExternalSync(url)
// Replace with
async function openThing (url) {
await shell.openExternal(url)
}计划重写的 API (6.0)
Planned Breaking API Changes (6.0)
win.setMenu(null)
// 不推荐
win.setMenu(null)
// 替换为
win.removeMenu()win.setMenu(null)
// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()contentTracing.getTraceBufferUsage()
// Deprecated
contentTracing.getTraceBufferUsage((percentage, value) => {
// do something
})
// Replace with
contentTracing.getTraceBufferUsage().then(infoObject => {
// infoObject has percentage and value fields
})contentTracing.getTraceBufferUsage()
// Deprecated
contentTracing.getTraceBufferUsage((percentage, value) => {
// do something
})
// Replace with
contentTracing.getTraceBufferUsage().then(infoObject => {
// infoObject has percentage and value fields
})渲染进程中的 electron.screen
// 不推荐
require('electron').screen
// 替换为
require('electron').remote.screenelectron.screen in renderer process
// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen沙盒渲染器中的require
// 不推荐
require('child_process')
// 替换为
require('electron').remote.require('child_process')
// 不推荐
require('fs')
// 替换为
require('electron').remote.require('fs')
// 不推荐
require('os')
// 替换为
require('electron').remote.require('os')
// 不推荐
require('path')
// 替换为
require('electron').remote.require('path')require in sandboxed renderers
// 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
// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = getSystemIdleState(threshold)powerMonitor.querySystemIdleState
// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = getSystemIdleState(threshold)powerMonitor.querySystemIdleTime
// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = getSystemIdleTime()powerMonitor.querySystemIdleTime
// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = getSystemIdleTime()Tray
Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.Tray
Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.
// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.计划重写的 API (5.0)
Planned Breaking API Changes (5.0)
new BrowserWindow({ webPreferences })
不推荐使用以下 webPreferences 选项默认值，以支持下面列出的新默认值。
| 属性 | 不推荐使用的默认值 | 新的默认值 |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration 未设置过则是 true | false |
例如，重新启用 webviewTag
const w = new BrowserWindow({
webPreferences: {
webviewTag: true
}
})new BrowserWindow({ webPreferences })
The following webPreferences option default values are deprecated in favor of the new defaults listed below.
| Property | Deprecated Default | New Default |
|---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration if set else true | false |
E.g. Re-enabling the webviewTag
const w = new BrowserWindow({
webPreferences: {
webviewTag: true
}
})nativeWindowOpen
Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is `true.
nativeWindowOpen
Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is `true.
带权限的 Scheme 注册
移除 Renderer process APIs webFrame.setLSSemeAsPrivieged 和 webFrame.registerURLLSQUIseAswersegCSP 以及浏览器 process API protocol.registerStardsSchemes. 新的 API protocol.registerSchemeasviliged 已被添加，并用于注册具有必要权限的自定义 scheme。 自定义 scheme 需要在 app 触发 ready 事件之前注册。
Privileged Schemes Registration
Renderer process APIs webFrame.setRegisterURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
webFrame Isolated World APIs
// 弃用
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// 替换为
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})webFrame Isolated World APIs
// 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 (4.0)
以下包含了Electron 4.0中重大的API更新
Planned Breaking API Changes (4.0)
The following list includes the breaking API changes made in Electron 4.0.
app.makeSingleInstance
// 弃用
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// 替换为
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})app.makeSingleInstance
// Deprecated
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})app.releaseSingleInstance
// 废弃
app.releaseSingleInstance()
// 替换为
app.releaseSingleInstanceLock()app.releaseSingleInstance
// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()app.getGPUInfo
app.getGPUInfo('complete')
// 现在的行为将与macOS下的`basic`设置一样
app.getGPUInfo('basic')app.getGPUInfo
app.getGPUInfo('complete')
// Now behaves the same with `basic` on macOS
app.getGPUInfo('basic')win_delay_load_hook
在为 Windows 构建本机模块时，将使 win_delay_load_hook 变量值 位于 binding.gyp 模块，必须为 true (这是默认值)。 如果这个钩子 不存在，那么本机模块将无法在 Windows 上加载，并出现错误 消息如 无法找到模块。 查看 原生模块指南 以获取更多信息.
win_delay_load_hook
When building native modules for windows, the win_delay_load_hook variable in the module's binding.gyp must be true (which is the default). If this hook is not present, then the native module will fail to load on Windows, with an error message like Cannot find module. See the native module guide for more.
重大的API更新 (3.0)
以下包含了Electron 3.0中重大的API更新
Breaking API Changes (3.0)
The following list includes the breaking API changes in Electron 3.0.
app
// 弃用
app.getAppMemoryInfo()
// 替换为
app.getAppMetrics()
// 弃用
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // 弃用的属性app
// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()
// Deprecated
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated propertyBrowserWindow
// 弃用
let optionsA = { webPreferences: { blinkFeatures: '' } }
let windowA = new BrowserWindow(optionsA)
// 替换为
let optionsB = { webPreferences: { enableBlinkFeatures: '' } }
let windowB = new BrowserWindow(optionsB)
// 弃用
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// do something
}
})
// 替换为
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// do something
}
})BrowserWindow
// Deprecated
let optionsA = { webPreferences: { blinkFeatures: '' } }
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = { webPreferences: { enableBlinkFeatures: '' } }
let 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
// 过时的
clipboard.readRtf()
// 替换为
clipboard.readRTF()
// 过时的
clipboard.writeRtf()
// 替换为
clipboard.writeRTF()
// 过时的
clipboard.readHtml()
// 替换为
clipboard.readHTML()
// 过时的
clipboard.writeHtml()
//替换为
clipboard.writeHTML()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
// 过时的
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// 替换为
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})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
// 弃用
nativeImage.createFromBuffer(buffer, 1.0)
// 替换为
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})nativeImage
// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})process
// 弃用
const info = process.getProcessMemoryInfo()process
// Deprecated
const info = process.getProcessMemoryInfo()screen
// 弃用
screen.getMenuBarHeight()
// 替换为
screen.getPrimaryDisplay().workAreascreen
// Deprecated
screen.getMenuBarHeight()
// Replace with
screen.getPrimaryDisplay().workAreasession
// 弃用
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// 替换为
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})session
// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})Tray
// 过时的
tray.setHighlightMode(true)
// 替换为
tray.setHighlightMode('on')
// 过时的
tray.setHighlightMode(false)
// 替换为
tray.setHighlightMode('off')Tray
// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')
// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')webContents
// 弃用
webContents.openDevTools({ detach: true })
// 替换为
webContents.openDevTools({ mode: 'detach' })
// 移除
webContents.setSize(options)
// 没有该API的替代webContents
// Deprecated
webContents.openDevTools({ detach: true })
// Replace with
webContents.openDevTools({ mode: 'detach' })
// Removed
webContents.setSize(options)
// There is no replacement for this APIwebFrame
// 弃用
webFrame.registerURLSchemeAsSecure('app')
// 替换为
protocol.registerStandardSchemes(['app'], { secure: true })
// 弃用
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// 替换为
protocol.registerStandardSchemes(['app'], { secure: true })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>
// 移除
webview.setAttribute('disableguestresize', '')
// 没有该API的替代
// 移除
webview.setAttribute('guestinstance', instanceId)
// 没有该API的替代
// 键盘监听器在webview标签中不再起效
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }<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
这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志.
过时的: https://atom.io/download/atom-shell
替换为: https://atom.io/download/electron
Node Headers URL
This is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules.
Deprecated: https://atom.io/download/atom-shell
Replace with: https://atom.io/download/electron
重大的API更新 (2.0)
以下包含了Electron 2.0中重大的API更新
Breaking API Changes (2.0)
The following list includes the breaking API changes made in Electron 2.0.
BrowserWindow
// 弃用
let optionsA = { titleBarStyle: 'hidden-inset' }
let windowA = new BrowserWindow(optionsA)
// 替换为
let optionsB = { titleBarStyle: 'hiddenInset' }
let windowB = new BrowserWindow(optionsB)BrowserWindow
// Deprecated
let optionsA = { titleBarStyle: 'hidden-inset' }
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = { titleBarStyle: 'hiddenInset' }
let windowB = new BrowserWindow(optionsB)menu
// 移除
menu.popup(browserWindow, 100, 200, 2)
// 替换为
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })menu
// Removed
menu.popup(browserWindow, 100, 200, 2)
// Replaced with
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })nativeImage
// 移除
nativeImage.toPng()
// 替换为
nativeImage.toPNG()
// 移除
nativeImage.toJpeg()
// 替换为
nativeImage.toJPEG()nativeImage
// Removed
nativeImage.toPng()
// Replaced with
nativeImage.toPNG()
// Removed
nativeImage.toJpeg()
// Replaced with
nativeImage.toJPEG()process
process.versions.electron和process.version.chrome将成为只读属性, 以便与其他process.versions属性由Node设置。
process
process.versions.electronandprocess.version.chromewill be made read-only properties for consistency with the otherprocess.versionsproperties set by Node.
webContents
// 移除
webContents.setZoomLevelLimits(1, 2)
// 替换为
webContents.setVisualZoomLevelLimits(1, 2)webContents
// Removed
webContents.setZoomLevelLimits(1, 2)
// Replaced with
webContents.setVisualZoomLevelLimits(1, 2)webFrame
// 移除
webFrame.setZoomLevelLimits(1, 2)
// 替换为
webFrame.setVisualZoomLevelLimits(1, 2)webFrame
// Removed
webFrame.setZoomLevelLimits(1, 2)
// Replaced with
webFrame.setVisualZoomLevelLimits(1, 2)<webview>
// 移除
webview.setZoomLevelLimits(1, 2)
// 替换为
webview.setVisualZoomLevelLimits(1, 2)<webview>
// Removed
webview.setZoomLevelLimits(1, 2)
// Replaced with
webview.setVisualZoomLevelLimits(1, 2)重复的 ARM 资源
每个 Electron 发布版本包含两个相同的ARM版本，文件名略有不同，如electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip 添加包含v7l前缀的资源向用户明确其支持的ARM版本，并消除由未来armv6l 和 arm64 资源可能产生的歧义。
为了防止可能导致安装器毁坏的中断，不带前缀的文件仍然将被发布。 从2.0版本起，不带前缀的文件将不再发布。
更多详细情况，查看 6986 和 7189。
Duplicate ARM Assets
Each Electron release includes two identical ARM builds with slightly different filenames, like electron-v1.7.3-linux-arm.zip and electron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added to clarify to users which ARM version it supports, and to disambiguate it from future armv6l and arm64 assets that may be produced.
The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the un-prefixed file will no longer be published.
For details, see 6986 and 7189.