重大更改

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

FIXME 注释

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

计划重写的 API (7.0)

shell.openExternalSync(url[, options])

  1. // Deprecated
  2. shell.openExternalSync(url)
  3. // Replace with
  4. async function openThing (url) {
  5.   await shell.openExternal(url)
  6. }

计划重写的 API (6.0)

win.setMenu(null)

  1. // 不推荐
  2. win.setMenu(null)
  3. // 替换为
  4. win.removeMenu()

contentTracing.getTraceBufferUsage()

  1. // Deprecated
  2. contentTracing.getTraceBufferUsage((percentage, value) => {
  3.   // do something
  4. })
  5. // Replace with
  6. contentTracing.getTraceBufferUsage().then(infoObject => {
  7.   // infoObject has percentage and value fields
  8. })

渲染进程中的 electron.screen

  1. // 不推荐
  2. require('electron').screen
  3. // 替换为
  4. require('electron').remote.screen

沙盒渲染器中的require

  1. // 不推荐
  2. require('child_process')
  3. // 替换为
  4. require('electron').remote.require('child_process')
  6. // 不推荐
  7. require('fs')
  8. // 替换为
  9. require('electron').remote.require('fs')
  11. // 不推荐
  12. require('os')
  13. // 替换为
  14. require('electron').remote.require('os')
  16. // 不推荐
  17. require('path')
  18. // 替换为
  19. require('electron').remote.require('path')

powerMonitor.querySystemIdleState

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

powerMonitor.querySystemIdleTime

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

Tray

Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.

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

计划重写的 API (5.0)

new BrowserWindow({ webPreferences })

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

属性不推荐使用的默认值新的默认值
contextIsolationfalsetrue
nodeIntegrationtruefalse
webviewTagnodeIntegration 未设置过则是 truefalse

例如，重新启用 webviewTag

  1. const w = new BrowserWindow({
  2.   webPreferences: {
  3.     webviewTag: true
  4.   }
  5. })

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

  1. // 弃用
  2. webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
  3. webFrame.setIsolatedWorldHumanReadableName(worldId, name)
  4. webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
  5. // 替换为
  6. webFrame.setIsolatedWorldInfo(
  7.   worldId,
  8.   {
  9.     securityOrigin: 'some_origin',
  10.     name: 'human_readable_name',
  11.     csp: 'content_security_policy'
  12.   })

计划重写的 API (4.0)

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

app.makeSingleInstance

  1. // 弃用
  2. app.makeSingleInstance((argv, cwd) => {
  3.   /* ... */
  4. })
  5. // 替换为
  6. app.requestSingleInstanceLock()
  7. app.on('second-instance', (event, argv, cwd) => {
  8.   /* ... */
  9. })

app.releaseSingleInstance

  1. // 废弃
  2. app.releaseSingleInstance()
  3. // 替换为
  4. app.releaseSingleInstanceLock()

app.getGPUInfo

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

win_delay_load_hook

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

重大的API更新 (3.0)

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

app

  1. // 弃用
  2. app.getAppMemoryInfo()
  3. // 替换为
  4. app.getAppMetrics()
  6. // 弃用
  7. const metrics = app.getAppMetrics()
  8. const { memory } = metrics[0] // 弃用的属性

BrowserWindow

  1. // 弃用
  2. let optionsA = { webPreferences: { blinkFeatures: '' } }
  3. let windowA = new BrowserWindow(optionsA)
  4. // 替换为
  5. let optionsB = { webPreferences: { enableBlinkFeatures: '' } }
  6. let windowB = new BrowserWindow(optionsB)
  8. // 弃用
  9. window.on('app-command', (e, cmd) => {
  10.   if (cmd === 'media-play_pause') {
  11.     // do something
  12.   }
  13. })
  14. // 替换为
  15. window.on('app-command', (e, cmd) => {
  16.   if (cmd === 'media-play-pause') {
  17.     // do something
  18.   }
  19. })

clipboard

  1. // 过时的
  2. clipboard.readRtf()
  3. // 替换为
  4. clipboard.readRTF()
  6. // 过时的
  7. clipboard.writeRtf()
  8. // 替换为
  9. clipboard.writeRTF()
  11. // 过时的
  12. clipboard.readHtml()
  13. // 替换为
  14. clipboard.readHTML()
  16. // 过时的
  17. clipboard.writeHtml()
  18. //替换为
  19. clipboard.writeHTML()

crashReporter

  1. // 过时的
  2. crashReporter.start({
  3.   companyName: 'Crashly',
  4.   submitURL: 'https://crash.server.com',
  5.   autoSubmit: true
  6. })
  7. // 替换为
  8. crashReporter.start({
  9.   companyName: 'Crashly',
  10.   submitURL: 'https://crash.server.com',
  11.   uploadToServer: true
  12. })

nativeImage

  1. // 弃用
  2. nativeImage.createFromBuffer(buffer, 1.0)
  3. // 替换为
  4. nativeImage.createFromBuffer(buffer, {
  5.   scaleFactor: 1.0
  6. })

process

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

screen

  1. // 弃用
  2. screen.getMenuBarHeight()
  3. // 替换为
  4. screen.getPrimaryDisplay().workArea

session

  1. // 弃用
  2. ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  3.   callback(true)
  4. })
  5. // 替换为
  6. ses.setCertificateVerifyProc((request, callback) => {
  7.   callback(0)
  8. })

Tray

  1. // 过时的
  2. tray.setHighlightMode(true)
  3. // 替换为
  4. tray.setHighlightMode('on')
  6. // 过时的
  7. tray.setHighlightMode(false)
  8. // 替换为
  9. tray.setHighlightMode('off')

webContents

  1. // 弃用
  2. webContents.openDevTools({ detach: true })
  3. // 替换为
  4. webContents.openDevTools({ mode: 'detach' })
  6. // 移除
  7. webContents.setSize(options)
  8. // 没有该API的替代

webFrame

  1. // 弃用
  2. webFrame.registerURLSchemeAsSecure('app')
  3. // 替换为
  4. protocol.registerStandardSchemes(['app'], { secure: true })
  6. // 弃用
  7. webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
  8. // 替换为
  9. protocol.registerStandardSchemes(['app'], { secure: true })

<webview>

  1. // 移除
  2. webview.setAttribute('disableguestresize', '')
  3. // 没有该API的替代
  5. // 移除
  6. webview.setAttribute('guestinstance', instanceId)
  7. // 没有该API的替代
  9. // 键盘监听器在webview标签中不再起效
  10. webview.onkeydown = () => { /* handler */ }
  11. 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

  1. // 弃用
  2. let optionsA = { titleBarStyle: 'hidden-inset' }
  3. let windowA = new BrowserWindow(optionsA)
  4. // 替换为
  5. let optionsB = { titleBarStyle: 'hiddenInset' }
  6. let windowB = new BrowserWindow(optionsB)

menu

  1. // 移除
  2. menu.popup(browserWindow, 100, 200, 2)
  3. // 替换为
  4. menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage

  1. // 移除
  2. nativeImage.toPng()
  3. // 替换为
  4. nativeImage.toPNG()
  6. // 移除
  7. nativeImage.toJpeg()
  8. // 替换为
  9. nativeImage.toJPEG()

process

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

webContents

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

webFrame

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

<webview>

  1. // 移除
  2. webview.setZoomLevelLimits(1, 2)
  3. // 替换为
  4. 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。