重大更改

这里将记录重大更改,并在可能的情况下向JS代码添加弃用警告,在这更改之前至少会有一个重要版本.

`FIXME` 注释

代码注释中添加的FIXME字符来表示以后的版本应该被修复的问题. 参考 https://github.com/electron/electron/search?q=fixme

计划重写的 API (7.0)

Node Headers URL

这是在构建原生 node 模块时在 .npmrc 文件中指定为 disturl 的 url 或是 --dist-url 命令行标志. Both will be supported for the foreseeable future but it is recommended that you switch.

过时的: https://atom.io/download/electron

替换为: https://electronjs.org/headers

`session.clearAuthCache(options)`

The session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.

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

`powerMonitor.querySystemIdleState`

// Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = getSystemIdleState(threshold)

`powerMonitor.querySystemIdleTime`

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

webFrame Isolated World APIs

// Removed in Elecron 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'
  })

Removal of deprecated `marked` property on getBlinkMemoryInfo

This property was removed in Chromium 77, and as such is no longer available.

`webkitdirectory` attribute for `<input type="file"/>`

The webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder. As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs). As an illustration, take a folder with this structure:

console
folder
├── file1
├── file2
└── file3
  In Electron <=6, this would return a

FileList with a File object for:

console
path/to/folder
  In Electron 7, this now returns a

FileList with a File object for:

console
/path/to/folder/file3
/path/to/folder/file2
/path/to/folder/file1
  Note that

webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

计划重写的 API (6.0)

`win.setMenu(null)`

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

`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.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')

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

`app.enableMixedSandbox`

// Deprecated
app.enableMixedSandbox()

Mixed-sandbox mode is now enabled by default.

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

`new BrowserWindow({ webPreferences })`

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

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

例如，重新启用 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.

带权限的 Scheme 注册

移除 Renderer process APIs webFrame.setLSSemeAsPrivieged 和 webFrame.registerURLLSQUIseAswersegCSP 以及浏览器 process API protocol.registerStardsSchemes. 新的 API protocol.registerSchemeasviliged 已被添加，并用于注册具有必要权限的自定义 scheme。自定义 scheme 需要在 app 触发 ready 事件之前注册。

webFrame Isolated World APIs

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

`webFrame.setSpellCheckProvider`

The spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.

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

以下包含了Electron 4.0中重大的API更新

`app.makeSingleInstance`

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

`app.releaseSingleInstance`

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

`app.getGPUInfo`

app.getGPUInfo('complete')
// 现在的行为将与macOS下的`basic`设置一样
app.getGPUInfo('basic')

`win_delay_load_hook`

在为 Windows 构建本机模块时，将使 win_delay_load_hook 变量值位于 binding.gyp 模块，必须为 true (这是默认值)。如果这个钩子不存在，那么本机模块将无法在 Windows 上加载，并出现错误消息如 无法找到模块。查看原生模块指南以获取更多信息.

重大的API更新 (3.0)

以下包含了Electron 3.0中重大的API更新

`app`

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

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

`BrowserWindow`

// 弃用
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
  }
})

`clipboard`

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

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

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

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

`crashReporter`

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

`nativeImage`

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

`process`

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

`screen`

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

`session`

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

`Tray`

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

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

`webContents`

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

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

`webFrame`

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

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

`<webview>`

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

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

// 键盘监听器在webview标签中不再起效
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node Headers URL

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

过时的: https://atom.io/download/atom-shell

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

重大的API更新 (2.0)

以下包含了Electron 2.0中重大的API更新

`BrowserWindow`

// 弃用
let optionsA = { titleBarStyle: 'hidden-inset' }
let windowA = new BrowserWindow(optionsA)
// 替换为
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 })

`nativeImage`

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

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

`process`

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

`webContents`

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

`webFrame`

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

`<webview>`

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

重复的 ARM 资源

每个 Electron 发布版本包含两个相同的ARM版本，文件名略有不同，如electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip 添加包含v7l前缀的资源向用户明确其支持的ARM版本，并消除由未来armv6l 和 arm64 资源可能产生的歧义。

为了防止可能导致安装器毁坏的中断，不带前缀的文件仍然将被发布。 Starting at 2.0, the unprefixed file will no longer be published.

更多详细情况，查看 6986 和 7189。

Files

breaking-changes.md

Latest commit

History

breaking-changes.md

File metadata and controls

重大更改

FIXME 注释

计划重写的 API (7.0)

Node Headers URL

session.clearAuthCache(options)

powerMonitor.querySystemIdleState

powerMonitor.querySystemIdleTime

webFrame Isolated World APIs

Removal of deprecated marked property on getBlinkMemoryInfo

webkitdirectory attribute for <input type="file"/>

计划重写的 API (6.0)

win.setMenu(null)

contentTracing.getTraceBufferUsage()

渲染进程中的 electron.screen

沙盒渲染器中的require

powerMonitor.querySystemIdleState

powerMonitor.querySystemIdleTime

app.enableMixedSandbox

Tray

计划重写的 API (5.0)

new BrowserWindow({ webPreferences })

nativeWindowOpen

带权限的 Scheme 注册

webFrame Isolated World APIs

webFrame.setSpellCheckProvider

计划重写的 API (4.0)

app.makeSingleInstance

app.releaseSingleInstance

app.getGPUInfo

win_delay_load_hook

重大的API更新 (3.0)

app

BrowserWindow

clipboard

crashReporter

nativeImage

process

screen

session

Tray

webContents

webFrame

<webview>

Node Headers URL

重大的API更新 (2.0)

BrowserWindow

menu

nativeImage

process

webContents

webFrame

<webview>

重复的 ARM 资源

`FIXME` 注释

`session.clearAuthCache(options)`

`powerMonitor.querySystemIdleState`

`powerMonitor.querySystemIdleTime`

Removal of deprecated `marked` property on getBlinkMemoryInfo

`webkitdirectory` attribute for `<input type="file"/>`

`win.setMenu(null)`

`contentTracing.getTraceBufferUsage()`

渲染进程中的 `electron.screen`

沙盒渲染器中的`require`

`powerMonitor.querySystemIdleState`

`powerMonitor.querySystemIdleTime`

`app.enableMixedSandbox`

`Tray`

`new BrowserWindow({ webPreferences })`

`nativeWindowOpen`

`webFrame.setSpellCheckProvider`

`app.makeSingleInstance`

`app.releaseSingleInstance`

`app.getGPUInfo`

`win_delay_load_hook`

`app`

`BrowserWindow`

`clipboard`

`crashReporter`

`nativeImage`

`process`

`screen`

`session`

`Tray`

`webContents`

`webFrame`

`<webview>`

`BrowserWindow`

`menu`

`nativeImage`

`process`

`webContents`

`webFrame`

`<webview>`