重大更改

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

重大更改的类型

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

  • API 更改： 一个 API 更改的方式使得尚未更新的代码保证会丢弃异常。
  • 行为有所改变： Electron的行为已经改变，但并不是一定会抛出例外情况。
  • 默认更改： 代码取决于旧的默认情况可能会中断，不一定会抛出例外。 可以通过明确指定值来恢复旧行为。
  • 已废弃： 一个 API 被标记为过时状态。 API将继续运行，但将发出一个废弃警告，并将在未来的发布中删除。
  • 已移除： 一个 API 或功能已被删除，不再被 Electron 支持。

计划重写的 API (14.0)

API Changed: window.(open)

The optional parameter frameName will no longer set the title of the window. This now follows the specification described by the native documentation under the corresponding parameter windowName.

If you were using this parameter to set the title of a window, you can instead use win.setTitle(title).

已移除： worldSafeExecuteJavaScript

在 Electron 14, worldSafeExecuteJavaScript 将被移除。 There is no alternative, please ensure your code works with this property enabled. It has been enabled by default since Electron 12.

You will be affected by this change if you use either webFrame.executeJavaScript or webFrame.executeJavaScriptInIsolatedWorld. You will need to ensure that values returned by either of those methods are supported by the Context Bridge API as these methods use the same value passing semantics.

计划重写的 API (13.0)

API 更改： session.setPermissionCheckHandler(handler)

The handler methods first parameter was previously always a webContents, it can now sometimes be null. You should use the requestingOrigin, embeddingOrigin and securityOrigin properties to respond to the permission check correctly. As the webContents can be null it can no longer be relied on.

  1. // Old code
  2. session.setPermissionCheckHandler((webContents, permission) => {
  3.   if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
  4.     return true
  5.   }
  6.   return false
  7. })
  9. // Replace with
  10. session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  11.   if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
  12.     return true
  13.   }
  14.   return false
  15. })

已移除： shell.moveItemToTrash()

废弃的同步 shell.moveItemToTrash() API 已被删除。 使用 异步 shell.trashItem() 代替。

  1. // Removed in Electron 13
  2. shell.moveItemToTrash(path)
  3. // Replace with
  4. shell.trashItem(path).then(/* ... */)

已移除： BrowserWindow 扩展 API

移除已弃用的扩展 API：

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

Use the session APIs instead:

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
  1. // Removed in Electron 13
  2. BrowserWindow.addExtension(path)
  3. BrowserWindow.addDevToolsExtension(path)
  4. // Replace with
  5. session.defaultSession.loadExtension(path)
  1. // Removed in Electron 13
  2. BrowserWindow.removeExtension(name)
  3. BrowserWindow.removeDevToolsExtension(name)
  4. // Replace with
  5. session.defaultSession.removeExtension(extension_id)
  1. // Removed in Electron 13
  2. BrowserWindow.getExtensions()
  3. BrowserWindow.getDevToolsExtensions()
  4. // Replace with
  5. session.defaultSession.getAllExtensions()

已移除： systemPreferences 中的方法

The following systemPreferences methods have been deprecated:

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

Use the following nativeTheme properties instead:

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
  1. // Removed in Electron 13
  2. systemPreferences.isDarkMode()
  3. // Replace with
  4. nativeTheme.shouldUseDarkColors
  6. // Removed in Electron 13
  7. systemPreferences.isInvertedColorScheme()
  8. // Replace with
  9. nativeTheme.shouldUseInvertedColorScheme
  11. // Removed in Electron 13
  12. systemPreferences.isHighContrastColorScheme()
  13. // Replace with
  14. nativeTheme.shouldUseHighContrastColors

计划重写的 API (12.0)

已删除：Pepper Flash 支持

Chromium已经取消了对Flash的支持，因此我们必须效仿。 更多 详情请参阅 Chromium的 Flash Roadmap

默认更改： worldSafeExecuteJavaScript 默认为 true

在 Electron 12, worldSafeExecuteJavaScript 将默认启用。 To restore the previous behavior, worldSafeExecuteJavaScript: false must be specified in WebPreferences. 请注意，设置此选项为 false 是不安全的。

This option will be removed in Electron 14 so please migrate your code to support the default value.

默认更改： 上下文隔离 默认为 true

在 Electron 12, 上下文隔离 默认情况下将被启用。 若要恢复 上一个行为， 上下文孤立：false 必须在 Web 首选项中指定。

We recommend having contextIsolation enabled for the security of your application.

详情见：https://github.com/electron/electron/issues/23506

Removed: crashReporter.getCrashesDirectory()

The crashReporter.getCrashesDirectory method has been removed. Usage should be replaced by app.getPath('crashDumps').

  1. // Removed in Electron 12
  2. crashReporter.getCrashesDirectory()
  3. // Replace with
  4. app.getPath('crashDumps')

Removed: crashReporter methods in the renderer process

The following crashReporter methods are no longer available in the renderer process:

  • 开始
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

They should be called only from the main process.

See #23265 for more details.

默认更改： crashReporter.start({ compress: true })

压缩 选项的默认值为 crashReporter.start 已将 从 false 更改为 true 这意味着崩溃转储将被上传到 崩溃摄取服务器与 Content-Encoding: gzip head, 和正文 将被压缩。

If your crash ingestion server does not support compressed payloads, you can turn off compression by specifying { compress: false } in the crash reporter options.

废弃： 远程 模块

远程 模块在 Electron 12 中被废弃，并将在 Electron 14 中被删除。 由 @electronic /远程 模块替代。

  1. // Electron 12废弃：
  2. const { BrowserWindow } = require('electron').远程
  1. // 替换为：
  2. const { BrowserWindow } = require('@electron/remote')
  4. // 在主进程中：
  5. require('@electron/remote/main').initialize()

已废弃： shell.moveItemToTrash()

同步 shell.moveItemToTrash() 已被新的 异步 shell.trashItem() 替换。

  1. // Deprecated in Electron 12
  2. shell.moveItemToTrash(path)
  3. // Replace with
  4. shell.trashItem(path).then(/* ... */)

计划重写的 API (11.0)

Removed: BrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserView

The experimental APIs BrowserView.{destroy, fromId, fromWebContents, getAllViews} have now been removed. Additionally, the id property of BrowserView has also been removed.

For more detailed information, see #23578.

计划破解API更改(10.0)

Deprecated: companyName argument to crashReporter.start()

The companyName argument to crashReporter.start(), which was previously required, is now optional, and further, is deprecated. To get the same behavior in a non-deprecated way, you can pass a companyName value in globalExtra.

  1. // Deprecated in Electron 10
  2. crashReporter.start({ companyName: 'Umbrella Corporation' })
  3. // Replace with
  4. crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

Deprecated: crashReporter.getCrashesDirectory()

The crashReporter.getCrashesDirectory method has been deprecated. Usage should be replaced by app.getPath('crashDumps').

  1. // Deprecated in Electron 10
  2. crashReporter.getCrashesDirectory()
  3. // Replace with
  4. app.getPath('crashDumps')

Deprecated: crashReporter methods in the renderer process

Calling the following crashReporter methods from the renderer process is deprecated:

  • 开始
  • crashReporter.getLastCrashReport
  • crashReporter.getUploadedReports
  • crashReporter.getUploadToServer
  • crashReporter.setUploadToServer
  • crashReporter.getCrashesDirectory

The only non-deprecated methods remaining in the crashReporter module in the renderer are addExtraParameter, removeExtraParameter and getParameters.

All above methods remain non-deprecated when called from the main process.

See #23265 for more details.

已废弃： crashReporter.start({ compress: false })

设置 { compress: false } 在 crashReporter.start 已废弃。 几乎 所有崩溃摄取服务器都支持 gzip 压缩。 此选项将在未来版本的 Electron 中删除 。

移除：浏览器窗口关联性

在构建新的 Browserwindow 时， 相关 选项将被删除 作为我们计划的一部分，以更密切地与 Chromium 的安全进程模型匹配。 性能和可维护性。

详情见 #18397。

默认更改： 启用远程模块 默认为 false

在 Electron 9，使用远程模块但不通过 启用远程模块 Web首选项开始发出警告。 在 Electron 10, 远程模块现在默认被禁用。 若要使用远程 模块， 启用远程模块：true 必须在 Web 首选项中指定：

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

我们 推荐离开远程 模块。

protocol.unregisterProtocol

protocol.uninterceptProtocol

The APIs are now synchronous and the optional callback is no longer needed.

  1. // Deprecated
  2. protocol.unregisterProtocol(scheme, () => { /* ... */ })
  3. // Replace with
  4. protocol.unregisterProtocol(scheme)

protocol.registerFileProtocol

protocol.registerBufferProtocol

protocol.registerStringProtocol

protocol.registerHttpProtocol

protocol.registerStreamProtocol

protocol.interceptFileProtocol

protocol.interceptStringProtocol

protocol.interceptBufferProtocol

protocol.interceptHttpProtocol

protocol.interceptStreamProtocol

The APIs are now synchronous and the optional callback is no longer needed.

  1. // Deprecated
  2. protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
  3. // Replace with
  4. protocol.registerFileProtocol(scheme, handler)

The registered or intercepted protocol does not have effect on current page until navigation happens.

protocol.isProtocolHandled

This API is deprecated and users should use protocol.isProtocolRegistered and protocol.isProtocolIntercepted instead.

  1. // Deprecated
  2. protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
  3. // Replace with
  4. const isRegistered = protocol.isProtocolRegistered(scheme)
  5. const isIntercepted = protocol.isProtocolIntercepted(scheme)

计划破解API更改(9.0)

默认更改：默认禁用在渲染器进程中加载不了解上下文的本地模块

在 Electron 9 中，我们不允许在渲染器进程 中加载不具上下文意义的本机模块。 这是为了提高Electron的安全性、性能和维护性 作为一个项目。

如果这影响到您，您可以临时将 app.allowRenderProcessReuse 设置为 false 设置为旧的行为。 在Electron 11之前，此标志将只是一个选项，因此 您应该计划更新您的原生模块以便了解上下文情况。

详情见 #18397。

Deprecated: BrowserWindow extension APIs

The following extension APIs have been deprecated:

  • BrowserWindow.addExtension(path)
  • BrowserWindow.addDevToolsExtension(path)
  • BrowserWindow.removeExtension(name)
  • BrowserWindow.removeDevToolsExtension(name)
  • BrowserWindow.getExtensions()
  • BrowserWindow.getDevToolsExtensions()

Use the session APIs instead:

  • ses.loadExtension(path)
  • ses.removeExtension(extension_id)
  • ses.getAllExtensions()
  1. // Deprecated in Electron 9
  2. BrowserWindow.addExtension(path)
  3. BrowserWindow.addDevToolsExtension(path)
  4. // Replace with
  5. session.defaultSession.loadExtension(path)
  1. // Deprecated in Electron 9
  2. BrowserWindow.removeExtension(name)
  3. BrowserWindow.removeDevToolsExtension(name)
  4. // Replace with
  5. session.defaultSession.removeExtension(extension_id)
  1. // Deprecated in Electron 9
  2. BrowserWindow.getExtensions()
  3. BrowserWindow.getDevToolsExtensions()
  4. // Replace with
  5. session.defaultSession.getAllExtensions()

已移除： <webview>.getWebContents()

此API在 Electron 8.0中被废弃，现已删除。

  1. // 在 Electron 9.0
  2. webview.getWebContents()
  3. // 替换为
  4. const { remote } = require('electron')
  5. remote.webContents.from(webview.getWebContentsId())

已删除： webFrame.setLayoutZoomLevelLimits()

Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron’s capacity to maintain it. 此函数在 Electron 8.x 中被废弃，并在 Electron 9.x 中被删除。 布局缩放级别限制 现在被固定为 0。 5 和最多5.0，定义为 这里

行为改变：现在在 IPC 上发送非JS 对象给异常。

在 Electron 8.0 中，IPC 被更改为使用结构性克隆算法， 显著提高性能。 To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren’t serializable with Structured Clone. 特别是DOM对象 (例如， 元素, 位置 和 DOMMatrix), 节点 s 由 C++ 类支持的对象(例如， 进程)。 nv, 一些成员 串流, 和 Electron 对象由 C++ 类支持 (例如) Webcontent, BrowserWindow and WebFrame() 不是 序列化的结构克隆。 每当调用旧算法时，都会打印 弃置警告。

在 Electron 9中。 , 旧的序列化算法已被删除, 发送 这种不可序列化的对象现在会抛出一个“对象无法被克隆” 错误。

API 更改： shell.openitem 现在是 shell.openPath

shell.openitem API 已被异步 shell.openPath API替换。 您可以在这里查看 API 的原始建议和理由 。

计划重写的 API (8.0)

行为改变：通过 IPC 发送的值现在被结构化的克隆算法序列化

The algorithm used to serialize objects sent over IPC (through ipcRenderer.send, ipcRenderer.sendSync, WebContents.send and related methods) has been switched from a custom algorithm to V8’s built-in Structured Clone Algorithm, the same algorithm used to serialize messages for postMessage. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior.

  • Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any such values, over IPC will now throw an exception, instead of silently converting the functions to undefined.
  1. // Previously:
  2. ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
  3. // => results in { value: 3 } arriving in the main process
  5. // From Electron 8:
  6. ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
  7. // => throws Error("() => {} could not be cloned.")
  • NaN, Infinity and -Infinity will now be correctly serialized, instead of being converted to null.
  • Objects containing cyclic references will now be correctly serialized, instead of being converted to null.
  • Set, Map, Error and RegExp values will be correctly serialized, instead of being converted to {}.
  • BigInt values will be correctly serialized, instead of being converted to null.
  • Sparse arrays will be serialized as such, instead of being converted to dense arrays with nulls.
  • Date objects will be transferred as Date objects, instead of being converted to their ISO string representation.
  • Typed Arrays (such as Uint8Array, Uint16Array, Uint32Array and so on) will be transferred as such, instead of being converted to Node.js Buffer.
  • Node.js Buffer objects will be transferred as Uint8Arrays. You can convert a Uint8Array back to a Node.js Buffer by wrapping the underlying ArrayBuffer:
  1. Buffer.from(value.buffer, value.byteOffset, value.byteLength)

Sending any objects that aren’t native JS types, such as DOM objects (e.g. Element, Location, DOMMatrix), Node.js objects (e.g. process.env, Stream), or Electron objects (e.g. WebContents, BrowserWindow, WebFrame) is deprecated. In Electron 8, these objects will be serialized as before with a DeprecationWarning message, but starting in Electron 9, sending these kinds of objects will throw a ‘could not be cloned’ error.

已废弃： <webview>.getWebContents()

This API is implemented using the remote module, which has both performance and security implications. Therefore its usage should be explicit.

  1. // Deprecated
  2. webview.getWebContents()
  3. // Replace with
  4. const { remote } = require('electron')
  5. remote.webContents.fromId(webview.getWebContentsId())

However, it is recommended to avoid using the remote module altogether.

  1. // main
  2. const { ipcMain, webContents } = require('electron')
  4. const getGuestForWebContents = (webContentsId, contents) => {
  5.   const guest = webContents.fromId(webContentsId)
  6.   if (!guest) {
  7.     throw new Error(`Invalid webContentsId: ${webContentsId}`)
  8.   }
  9.   if (guest.hostWebContents !== contents) {
  10.     throw new Error('Access denied to webContents')
  11.   }
  12.   return guest
  13. }
  15. ipcMain.handle('openDevTools', (event, webContentsId) => {
  16.   const guest = getGuestForWebContents(webContentsId, event.sender)
  17.   guest.openDevTools()
  18. })
  20. // renderer
  21. const { ipcRenderer } = require('electron')
  23. ipcRenderer.invoke('openDevTools', webview.getWebContentsId())

已废弃： webFrame.setLayoutZoomLevelLimits()

Chromium has removed support for changing the layout zoom level limits, and it is beyond Electron’s capacity to maintain it. The function will emit a warning in Electron 8.x, and cease to exist in Electron 9.x. The layout zoom level limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined here.

Deprecated events in systemPreferences

The following systemPreferences events have been deprecated:

  • inverted-color-scheme-changed
  • high-contrast-color-scheme-changed

Use the new updated event on the nativeTheme module instead.

  1. // Deprecated
  2. systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
  3. systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
  5. // Replace with
  6. nativeTheme.on('updated', () => { /* ... */ })

Deprecated: methods in systemPreferences

The following systemPreferences methods have been deprecated:

  • systemPreferences.isDarkMode()
  • systemPreferences.isInvertedColorScheme()
  • systemPreferences.isHighContrastColorScheme()

Use the following nativeTheme properties instead:

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
  1. // Deprecated
  2. systemPreferences.isDarkMode()
  3. // Replace with
  4. nativeTheme.shouldUseDarkColors
  6. // Deprecated
  7. systemPreferences.isInvertedColorScheme()
  8. // Replace with
  9. nativeTheme.shouldUseInvertedColorScheme
  11. // Deprecated
  12. systemPreferences.isHighContrastColorScheme()
  13. // Replace with
  14. nativeTheme.shouldUseHighContrastColors

计划重写的 API (7.0)

已弃用: Atom.io 节点头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

API 更改： session.clearAuthCache() 不再接受选项

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

  1. // Deprecated
  2. session.clearAuthCache({ type: 'password' })
  3. // Replace with
  4. session.clearAuthCache()

API 更改： powerMonitor.querySystemIdleState 现在是 powerMonitor.getSystemIdleState

  1. // 在 Electron 7.0
  2. powerMonitor.querySystemIdleState(阈值，回调)
  3. // 替换为同步 API
  4. contst idleState = powerMonitor.getSystemIdleState(阈值)

API 更改： powerMonitor.querySystemIdletime 现在是 powerMonitor.getSystemIdletime

  1. // 在 Electron 7.0
  2. powerMonitor.querySystemIdleTime(callback)
  3. // 替换为同步API
  4. const idleTime = powerMonitor.getSystemIdleTime()

API 更改： webFramework.setatedWorldInfo 替换单独的方法

  1. // Removed in Electron 7.0
  2. webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
  3. webFrame.setIsolatedWorldHumanReadableName(worldId, name)
  4. webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
  5. // Replace with
  6. webFrame.setIsolatedWorldInfo(
  7.   worldId,
  8.   {
  9.     securityOrigin: 'some_origin',
  10.     name: 'human_readable_name',
  11.     csp: 'content_security_policy'
  12.   })

已移除： 在 <code>getBlinkMemoryInfo 中标记 属性

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

行为改变： webkitdirectory 属性 <input type="file"/> 现在列出目录内容

HTML 文件输入上的 webkitdirectory 属性允许他们选择文件夹。 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.

在 Electron 7 中， FileList 现在是包含在 文件夹中的所有文件的列表， 类似于Chrome、Firefox和边缘 (链接到 MDN 文档)。

作为示例，在这个结构中占用一个文件夹：

  1. folder
  2. ├── file1
  3. ├── file2
  4. └── file3

在 Electron <=6, 这将返回一个 文件列表 带有一个 文件 对象：

  1. path/to/folder

在 Electron 7 中，现在返回一个 FileList 带有 文件 对象：

  1. /path/to/folder/file3
  2. /path/to/folder/file2
  3. /path/to/folder/file1

请注意， webkitdirectory 不再显示选中文件夹的路径。 If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

API Changed: Callback-based versions of promisified APIs

Electron 5 and Electron 6 introduced Promise-based versions of existing asynchronous APIs and deprecated their older, callback-based counterparts. In Electron 7, all deprecated callback-based APIs are now removed.

These functions now only return Promises:

  • app.getFileIcon() #15742
  • app.dock.show() #16904
  • contentTracking.getcategories() #16583
  • contentTracking.getTraceBufferUs() #16600
  • contentTracing.startRecording() #16584
  • contentTracing.stopRecording() #16584
  • contents.executeJavaScript() #17312
  • cookies.flushStore() #16464
  • cookies.get() #16464
  • cookies.remove() #16464
  • cookies.set() #16464
  • debugger.sendCommand() #16861
  • dialog.showCertificateTrustDialog() #17181
  • inAppAppase.getProducts() #17355
  • inAppAppase.handeProduct()#17355
  • netLog.stopLogging() #16862
  • session.clear. AuthCache() #17259
  • session.clearCache() #17185
  • session.clearhostResolverCache() #17229
  • session.clearclearStorageData #17249
  • session.getBlobData() #17303
  • session.getCacheSize() #17185
  • session.resolveProxy() #17222
  • session.setProxy() #17222
  • shell.openExternal() #16176
  • webContents.loadFile() #15855
  • webContents.loadURL() #15855
  • webContents.hasServiceWorker() #16535
  • webContents.printToPDF() #16795
  • webContents.savePage() #16742
  • webFrame.executeJavaScript() #17312
  • webFrame.executeJavaScriptInIsolatedWorld() #17312
  • webviewTag.executeJavaScript() #17312
  • win.capturePage() #15743

这些功能现在有两种形式，即同步和基于允诺的异步：

  • dialog.showMessageBox()/dialog.showMessageBoxSync() #17298
  • dialog.showOpenDialog()/dialog.showOpenDialogSync() #16973
  • dialog.showSaveDialog()/dialog.showSaveDialogSync() #17054

计划重写的 API (6.0)

API 更改： win.setMenu(null) 现在是 win.remenu()

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

API 更改： 电子.screen 渲染过程中应通过 远程 访问

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

API 更改： 需要在沙盒渲染器中生成节点。不再含蓄地加载 远程 版本

  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 已替换为 powerMonitor.getSystemIdleState

  1. // 已弃用
  2. powerMonitor.querySystemIdleState(阈值，回调)
  3. // 替换为同步 API
  4. const idleState = powerMonitor.getSystemIdleState(阈值)

已废弃： powerMonitor.querySystemIdleTime 被替换为 powerMonitor.getSystemIdleTime

  1. // 已弃用
  2. powerMonitor.querySystemIdleTime(callback)
  3. // 用同步API替换
  4. const idleTime = powerMonitor.getSystemIdleTime()

已废弃： app.enableMixedSandbox() 不再需要

  1. // Deprecated
  2. app.enableMixedSandbox()

Mixed-sandbox mode is now enabled by default.

已废弃： Tray.setHighlightmode

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)

默认更改： 节点集成 and webviewTag 默认为 false， 上下文隔离 默认为 true

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

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

例如，重新启用 webviewTag

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

行为改变： 节点集成 在子窗口通过 本地窗口打开

使用 原生窗口打开 选项打开的子窗口将总是禁用 Node.js 集成，除非 nodeIntegrationInSubFrames 是 true

API 更改：在应用程序准备就绪之前必须完成注册特权计划

渲染进程 API webFramework.registerURLSchemeAss特权 and webFrame.registerURLSchemeAsBypassingCSP 以及浏览器进程 API protocol.registerStandardSchemes 已被删除。 新的 API protocol.registerSchemeasviliged 已被添加，并用于注册具有必要权限的自定义 scheme。 自定义 scheme 需要在 app 触发 ready 事件之前注册。

已废弃： webFramework.setIsolatedWorld* 替换为 webFrame.setIsolatedWorldInfo

  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 更改： webFrame.setSpellCheckProvider 现在需要异步回调

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

  1. // Deprecated
  2. webFrame.setSpellCheckProvider('en-US', true, {
  3.   spellCheck: (text) => {
  4.     return !spellchecker.isMisspelled(text)
  5.   }
  6. })
  7. // Replace with
  8. webFrame.setSpellCheckProvider('en-US', {
  9.   spellCheck: (words, callback) => {
  10.     callback(words.filter(text => spellchecker.isMisspelled(text)))
  11.   }
  12. })

API Changed: webContents.getZoomLevel and webContents.getZoomFactor are now synchronous

webContents.getZoomLevel and webContents.getZoomFactor no longer take callback parameters, instead directly returning their number values.

  1. // Deprecated
  2. webContents.getZoomLevel((level) => {
  3.   console.log(level)
  4. })
  5. // Replace with
  6. const level = webContents.getZoomLevel()
  7. console.log(level)
  1. // Deprecated
  2. webContents.getZoomFactor((factor) => {
  3.   console.log(factor)
  4. })
  5. // Replace with
  6. const factor = webContents.getZoomFactor()
  7. console.log(factor)

计划重写的 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. // Deprecated
  2. const optionsA = { webPreferences: { blinkFeatures: '' } }
  3. const windowA = new BrowserWindow(optionsA)
  4. // Replace with
  5. const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
  6. const windowB = new BrowserWindow(optionsB)
  8. // Deprecated
  9. window.on('app-command', (e, cmd) => {
  10.   if (cmd === 'media-play_pause') {
  11.     // do something
  12.   }
  13. })
  14. // Replace with
  15. window.on('app-command', (e, cmd) => {
  16.   if (cmd === 'media-play-pause') {
  17.     // do something
  18.   }
  19. })

剪贴板

  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. })

进程

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

网络控制

  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. const optionsA = { titleBarStyle: 'hidden-inset' }
  3. const window A = new BrowserWindow(optionsA)
  4. // 替换为
  5. const optionsB = { titleBarStyle: 'hiddenInset' }
  6. const 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.versions.electron 和 process.version.chrome 将成为只读属性, 以便与其他 process.versions 属性由Node设置。

网络控制

  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 资源可能产生的歧义。

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

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