Electron.js API参考——重大变化

吕骞尧

2023-12-01

重大变化

此处将记录重大更改，并在可能的情况下（至少在进行更改之前）至少在一个主要版本中向JS代码添加弃用警告。

重大变化的类型

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

更改了API ：对API进行了更改，以确保未更新的代码会引发异常。
行为已更改：Electron的行为已更改，但未必会引发异常。
默认值已更改：取决于旧默认值的代码可能会中断，不一定会引发异常。可以通过显式指定值来恢复旧的行为。
不推荐使用： API被标记为不推荐使用。该API将继续运行，但会发出弃用警告，并将在以后的版本中删除。
已删除： API或功能已删除，Electron不再支持。

计划中的重大API更改（13.0）

已移除： `shell.moveItemToTrash()`

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

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

计划中的重大API更改（12.0）

删除：Pepper Flash支持

Chromium已删除了对Flash的支持，因此我们必须紧随其后。有关更多详细信息，请参见Chromium的Flash路线图。

默认更改：`contextIsolation`默认为`true`

在Electron 12中，contextIsolation将默认启用。若要还原以前的行为，contextIsolation: false必须在WebPreferences中指定。

我们建议启用contextIsolation以确保应用程序的安全。

有关更多详细信息，请参见：github.com/electron/electron/issues/23506

删除：`crashReporter`渲染器过程中的方法

crashReporter渲染器过程中不再提供以下方法：

crashReporter.start
crashReporter.getLastCrashReport
crashReporter.getUploadedReports
crashReporter.getUploadToServer
crashReporter.setUploadToServer
crashReporter.getCrashesDirectory

仅应从主过程调用它们。

有关更多详细信息，请参见＃23265。

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

compress选项to的默认值crashReporter.start已从更改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更改（10.0）

不推荐使用：的`companyName`参数`crashReporter.start()`

以前需要的companyName参数tocrashReporter.start()现在是可选的，并且不建议使用。要以不推荐的方式获得相同的行为，可以在中传递companyName值 globalExtra。

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

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

删除：浏览器窗口关联性

作为我们计划的一部分，将删除affinity构建新产品时的选项，BrowserWindow以与Chromium的过程模型更紧密地保持安全性，性能和可维护性。

有关更多详细信息，请参见＃18397。

默认更改：`enableRemoteModule`默认为`false`

在Electron 9中，使用未通过enableRemoteModuleWebPreferences选项显式启用它的远程模块开始发出警告。在Electron 10中，现在默认情况下禁用远程模块。要使用远程模块，enableRemoteModule: true必须在WebPreferences中指定：

const w = new BrowserWindow({
  webPreferences: {
    enableRemoteModule: true
  }
})

我们建议远离远程模块。

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

已移除： `<webview>.getWebContents()`

现在已删除在Electron 8.0中弃用的该API。

// 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，所定义这里。

在Electron 8.0中，IPC更改为使用结构化克隆算法，从而显着提高了性能。为了帮助简化过渡，保留了旧的IPC序列化算法，并将其用于某些无法使用结构化克隆序列化的对象。特别地，DOM对象（例如Element， Location和DOMMatrix），Node.js的对象通过C ++类（例如备份 process.env，某些成员Stream），和电子通过对象的C ++类的支持（例如WebContents，BrowserWindow和WebFrame）是不可序列与结构化克隆。每当调用旧算法时，就会显示弃用警告。

在Electron 9.0中，旧的序列化算法已删除，发送此类不可序列化的对象现在将引发“无法克隆的对象”错误。

API已更改：`shell.openItem`现在`shell.openPath`

该shell.openItemAPI已被异步shell.openPathAPI取代。您可以在此处查看原始的API提案和推理。

计划中的重大API更改（8.0）

行为已更改：通过IPC发送的值现在已使用结构化克隆算法进行序列化

用于序列化对象的算法在IPC发送（通过 ipcRenderer.send，ipcRenderer.sendSync，WebContents.send和相关方法）已经从一个自定义算法切换到V8内置的结构化克隆算法，用于为消息序列相同的算法 postMessage。这使大型邮件的性能提高了2倍，但行为上也发生了一些重大变化。

现在，通过IPC发送函数，承诺，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。
稀疏数组将照此序列化，而不是使用nulls转换为密集数组。
Date对象将作为Date对象传输，而不是转换为它们的ISO字符串表示形式。
类型数组（例如Uint8Array，Uint16Array，Uint32Array等等）将被转移正因为如此，而不是被转换为Node.js的Buffer。
Node.jsBuffer对象将作为Uint8Arrays传输。您可以通过包装底层将其转换Uint8Array回Node.js ：BufferArrayBuffer

Buffer.from(value.buffer, value.byteOffset, value.byteLength)

发送不是天然JS类型，如DOM对象（例如任何对象 Element，Location，DOMMatrix），Node.js的对象（例如process.env， Stream），或电子的对象（例如WebContents，BrowserWindow， WebFrame）已废弃。在Electron 8中，这些对象将像以前一样通过DeprecationWarning消息进行序列化，但是从Electron 9开始，发送此类对象将引发“无法克隆”错误。

不推荐使用： `<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，所定义这里。

计划中的重大API更改（7.0）

弃用：Atom.io节点标题URL

这是在构建本机节点模块时指定为disturl在.npmrc文件中或作为--dist-url命令行标志指定的URL 。在可预见的将来，两者都将受支持，但建议您进行切换。

不推荐使用：atom.io/download/electron

替换为：electronjs.org/headers

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

该session.clearAuthCacheAPI不再接受什么明确的选择，而是无条件地清除所有缓存。

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

已删除：`marked`属性为`getBlinkMemoryInfo`

此属性已在Chromium 77中删除，因此不再可用。

行为已更改：现在的`webkitdirectory`属性`<input type="file"/>`列出了目录内容

webkitdirectoryHTML文件输入上的属性允许他们选择文件夹。早期版本的Electron的实现不正确，其中event.target.files 输入的返回一个FileList，返回一个File对应于所选文件夹的。

从Electron 7开始，该FileList文件夹现在包含该文件夹中所有文件的列表，类似于Chrome，Firefox和Edge（指向MDN docs的链接）。

例如，使用具有以下结构的文件夹：

folder
├── file1
├── file2
└── file3

在Electron <= 6中，这将返回FileList带有File对象的对象：

path/to/folder

在Electron 7中，现在返回FileList带有File对象的对象：

/path/to/folder/file3
/path/to/folder/file2
/path/to/folder/file1

请注意，webkitdirectory不再公开所选文件夹的路径。如果您需要选定文件夹的路径而不是文件夹内容，请参阅dialog.showOpenDialogAPI（链接）。

计划中的重大API更改（6.0）

API已更改：`win.setMenu(null)`现在`win.removeMenu()`

// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()

API已更改：`contentTracing.getTraceBufferUsage()`现在是一个承诺

// Deprecated
contentTracing.getTraceBufferUsage((percentage, value) => {
  // do something
})
// Replace with
contentTracing.getTraceBufferUsage().then(infoObject => {
  // infoObject has percentage and value fields
})

API已更改：`electron.screen`在渲染器过程中，应通过以下方式访问`remote`

// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen

API更改：`require()`沙盒渲染器中的ing节点内置函数不再隐式加载`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实施中断了。苹果的本机替代品不支持更改突出显示行为。

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

行为已更改：`nodeIntegration`在通过打开的子窗口中`nativeWindowOpen`

与打开的子窗口nativeWindowOpen选项，将永远有Node.js的整合禁用，除非nodeIntegrationInSubFrames是true。

API更改：现在必须在应用就绪之前完成特权计划的注册

渲染器流程APIwebFrame.registerURLSchemeAsPrivileged和webFrame.registerURLSchemeAsBypassingCSP浏览器流程APIprotocol.registerStandardSchemes已被删除。protocol.registerSchemesAsPrivileged添加了新的API，该API应用于注册具有所需特权的自定义方案。在应用就绪之前，必须先注册自定义方案。

不推荐使用：`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更改（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构建本机模块时，模块中的win_delay_load_hook变量binding.gyp必须为true（这是默认值）。如果不存在此挂钩，则本机模块将无法在Windows上加载，并显示错误消息，如Cannot find module。有关更多信息，请参见本机模块指南。

重大的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 */ }

节点头URL

这是在构建本机节点模块时指定为disturl在.npmrc文件中或作为--dist-url命令行标志指定的URL 。

不推荐使用：atom.io/download/atom-shell

替换为：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)

// 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将用于与其他一致性进行只读属性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开始，将不再发布未添加前缀的文件。

有关详细信息，请参见 6986 和 7189。

Electron.js API参考——重大变化

相关阅读

相关文章

相关问答

相关文档