Критические изменения

Здесь будут описаны критические изменения, а также будут добавлены предупреждения об устаревших функциях в JS коде, где это возможно, по крайней мере перед тем, как изменения будут сделаны в одной мажорной версии.

Типы критических изменений

В этом документе используется следующее соглашение для классификации критических изменений:

Изменение API: API был изменен таким образом, что код, который не был обновлен, гарантировано бросит исключение.
Изменение поведения: Поведение Electron было изменено, но не обязательно появление исключений.
Изменено значение по-умолчанию: Код, работа которого зависит от старого значения по-умолчанию, может сломаться, не обязательно кидая исключение. Старое поведение можно восстановить, если явно указать значение.
Устарело: API был помечен как устаревший. API продолжит функционировать, но будет появляться предупреждающее сообщение о том, что API будет удален в будущем релизе.
Удалено: API или функция была удалена и больше не поддерживается Electron.

Запланированные критические изменения API (17.0)

Removed: `desktopCapturer.getSources` in the renderer

The desktopCapturer.getSources API is now only available in the main process. This has been changed in order to improve the default security of Electron apps.

If you need this functionality, it can be replaced as follows:

// Main process
const { ipcMain, desktopCapturer } = require('electron')

ipcMain.handle(
  'DESKTOP_CAPTURER_GET_SOURCES',
  (event, opts) => desktopCapturer.getSources(opts)
)

// Renderer process
const { ipcRenderer } = require('electron')

const desktopCapturer = {
  getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
}

However, you should consider further restricting the information returned to the renderer; for instance, displaying a source selector to the user and only returning the selected source.

Запланированные критические изменения API (16.0)

Behavior Changed: `crashReporter` implementation switched to Crashpad on Linux

The underlying implementation of the crashReporter API on Linux has changed from Breakpad to Crashpad, bringing it in line with Windows and Mac. As a result of this, child processes are now automatically monitored, and calling process.crashReporter.start in Node child processes is no longer needed (and is not advisable, as it will start a second instance of the Crashpad reporter).

There are also some subtle changes to how annotations will be reported on Linux, including that long values will no longer be split between annotations appended with __1, __2 and so on, and instead will be truncated at the (new, longer) annotation value limit.

Deprecated: `desktopCapturer.getSources` in the renderer

Usage of the desktopCapturer.getSources API in the renderer has been deprecated and will be removed. This change improves the default security of Electron apps.

See here for details on how to replace this API in your app.

Запланированные критические изменения API (15.0)

Default Changed: `nativeWindowOpen` defaults to `true`

Prior to Electron 15, window.open was by default shimmed to use BrowserWindowProxy. This meant that window.open('about:blank') did not work to open synchronously scriptable child windows, among other incompatibilities. nativeWindowOpen is no longer experimental, and is now the default.

See the documentation for window.open in Electron for more details.

Запланированные критические изменения API (14.0)

Removed: `remote` module

The remote module was deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

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

Удален: `app.allowRendererProcessReuse`

The app.allowRendererProcessReuse property will be removed as part of our plan to more closely align with Chromium's process model for security, performance and maintainability.

Для подробностей см. #18397.

Removed: Browser Window Affinity

Параметр affinity при создании нового BrowserWindow будет удален в рамках нашего плана для более тесной связи с моделью процесса Chrome в целях безопасности, производительность и лучшей поддержки.

Для подробностей см. #18397.

Изменения в API: `window.open()`

Необязательный параметр frameName больше не устанавливает название окна. Теперь это следует спецификации, описанной в документации в соответствии с параметром windowName.

Если вы использовали этот параметр, чтобы задать заголовок окна, вы можете использовать win.setTitle(title).

Удален: `worldSafeExecuteJavaScript`

В Electron 14 worldSafeExecuteJavaScript будет удален. Альтернатива отсутствует, пожалуйста, убедитесь, что в вашем коде данный параметр включен. Он был включен в Electron по умолчанию 12.

На вас повлияет это изменение, если вы используете либо webFrame.executeJavaScript или webFrame.executeJavaScriptInIsolatedWorld. Вам нужно будет убедиться, что значения, возвращаемые одним из этих методов, поддерживаются Context Bridge API, поскольку эти методы используют одинаковую семантику значения.

Removed: BrowserWindowConstructorOptions inheriting from parent windows

Prior to Electron 14, windows opened with window.open would inherit BrowserWindow constructor options such as transparent and resizable from their parent window. Beginning with Electron 14, this behavior is removed, and windows will not inherit any BrowserWindow constructor options from their parents.

Instead, explicitly set options for the new window with setWindowOpenHandler:

webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    overrideBrowserWindowOptions: {
      // ...
    }
  }
})

Удален: `additionalFeatures`

The deprecated additionalFeatures property in the new-window and did-create-window events of WebContents has been removed. Since new-window uses positional arguments, the argument is still present, but will always be the empty array []. (Though note, the new-window event itself is deprecated, and is replaced by setWindowOpenHandler.) Bare keys in window features will now present as keys with the value true in the options object.

// Removed in Electron 14
// Triggered by window.open('...', '', 'my-key')
webContents.on('did-create-window', (window, details) => {
  if (details.additionalFeatures.includes('my-key')) {
    // ...
  }
})

// Replace with
webContents.on('did-create-window', (window, details) => {
  if (details.options['my-key']) {
    // ...
  }
})

Запланированные критические изменения API (13.0)

Изменения в API: `session.setPermissionCheckHandler(handler)`

Первым параметром handler был ранее всегда webContents, теперь он иногда может быть null. Вы должны использовать requestingOrigin, embeddingOrigin и securityOrigin свойства для правильного ответа на проверку. Так как webContents может быть null больше, на него нельзя полагаться.

// Старый код
session.setPermissionCheckHandler((webContents, permission) => {
  if (webContents.getURL().startsWith('https://google. om/') && permission === 'notification') {
    return true
  }
  возвращает false
})

// Заменить на
сессию. etPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin). ostname === 'google.com' && permission === 'notification') {
    return true
  }
  возвращает false
})

Удален: `shell.moveItemToTrash()`

Удален устаревший синхронный shell.moveItemToTrash() API. Вместо этого используйте асинхронный shell.trashItem().

// Удалён в Electron 13
shell.moveItemToTrash(path)
// Замена на
shell.trashItem(path).then(/* ... */)

Удалено: `BrowserWindow` API расширений

Удалено устаревшее API расширений:

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

Использовать API сессии:

ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()

// Удален в Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Заменить
session.defaultSession.loadExtension(path)

// Удален в Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Заменить
session.defaultSession.loadExtension(path)

// Удален в Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Заменить
session.defaultSession.getAllExtensions()

Удалено: методы в `systemPreferences`

Следующие systemPreferences были устаревшими:

systemPreferences.isDarkMode()
systemPreferences.isvertedColorScheme()
systemPreferences.isHighContrastColorScheme()

Используйте следующие свойства nativeTheme вместо этого:

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

// Удалён в Electron 13
systemPreferences.isDarkMode()
// Заменить на
nativeTheme.shouldUseDarkColors

// Удалён в Electron 13
systemPreferences. sInvertedColorScheme()
// Заменить на
nativeTheme.shouldUseInvertedColorScheme

// Удалено в Electron 13
systemPreferences.isHighContrastColorScheme()
// Заменить на
nativeTheme.shouldUseHighContrastColors

Устарело: WebContents `new-window` событие

Событие new-window сетевого контента является устаревшим. Заменяется на webContents.setWindowOpenHandler().

// Устарел в Electron 13
webContents.on('new-window', (event) => {
  событие. reventDefault()
})

// Заменить на
webContents.setWindowOpenHandler((details) => {
  return { action: 'deny' }
})

Запланированные критические изменения API (12.0)

Удалено: Поддержка Pepper Flash

Chromium удалил поддержку Flash, и поэтому мы должны следовать этому примеру. Смотрите Chromium Flash Roadmap для получения более подробной информации.

Default Changed: `worldSafeExecuteJavaScript` defaults to `true`

В Electron 12, worldSafeExecuteJavaScript будет включен по умолчанию. Чтобы восстановить предыдущее поведение, в WebPreferences должен быть определен worldSafeExecuteJavaScript: false. Обратите внимание, что установливать этого параметр в false небезопасно.

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

Default Changed: `contextIsolation` defaults to `true`

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

Another implication is that require() cannot be used in the renderer process unless nodeIntegration is true and contextIsolation is false.

Подробнее см.: https://github.com/electron/electron/issues/23506

Удален: `crashReporter.getCrashesDirectory()`

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

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

Removed: `crashReporter` methods in the renderer process

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

crashReporter.start
crashReporter.getLastCrashReport
crashReporter.getUploadedReports
crashReporter.getUploadToServer
вылетать Reporter.setUploadToServer
crashReporter.getCrashesDirectory

They should be called only from the main process.

See #23265 for more details.

Default Changed: `crashReporter.start({ compress: true })`

The default value of the compress option to crashReporter.start has changed from false to true. This means that crash dumps will be uploaded to the crash ingestion server with the Content-Encoding: gzip header, and the body will be compressed.

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

Deprecated: `remote` module

The remote module is deprecated in Electron 12, and will be removed in Electron 14. It is replaced by the @electron/remote module.

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

Obsoleto: `shell.moveItemToTrash()`

The synchronous shell.moveItemToTrash() has been replaced by the new, asynchronous shell.trashItem().

// Deprecated in Electron 12
shell.moveItemToTrash(path)
// Replace with
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.

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

Obsoleto: `crashReporter.getCrashesDirectory()`

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

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

Deprecated: `crashReporter` methods in the renderer process

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

crashReporter.start
crashReporter.getLastCrashReport
crashReporter.getUploadedReports
crashReporter.getUploadToServer
вылетать Reporter.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.

Obsoleto: `crashReporter.start({ compress: false })`

Setting { compress: false } in crashReporter.start is deprecated. Nearly all crash ingestion servers support gzip compression. This option will be removed in a future version of Electron.

Изменение значения по-умолчанию: `enableRemoteModule` изменено на `false`

In Electron 9, using the remote module without explicitly enabling it via the enableRemoteModule WebPreferences option began emitting a warning. In Electron 10, the remote module is now disabled by default. To use the remote module, enableRemoteModule: true must be specified in WebPreferences:

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

We recommend moving away from the remote module.

`protocol.unregisterProtocol`

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

Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default

As of Electron 9 we do not allow loading of non-context-aware native modules in the renderer process. This is to improve security, performance and maintainability of Electron as a project.

If this impacts you, you can temporarily set app.allowRendererProcessReuse to false to revert to the old behavior. This flag will only be an option until Electron 11 so you should plan to update your native modules to be context aware.

Для подробностей см. #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()

Использовать API сессии:

ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()

// Deprecated in Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)

// Deprecated in Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)

// Deprecated in Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

Removed: `<webview>.getWebContents()`

Удален этот API, устаревший в Electron 8.0.

// Удален в Electron 9.0
webview.getWebContents()
// Замена на
const { remote } = require('electron')
remote.webContents.fromId(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 was deprecated in Electron 8.x, and has been removed 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.

Behavior Changed: Sending non-JS objects over IPC now throws an exception

In Electron 8.0, IPC was changed to use the Structured Clone Algorithm, bringing significant performance improvements. To help ease the transition, the old IPC serialization algorithm was kept and used for some objects that aren't serializable with Structured Clone. In particular, DOM objects (e.g. Element, Location and DOMMatrix), Node.js objects backed by C++ classes (e.g. process.env, some members of Stream), and Electron objects backed by C++ classes (e.g. WebContents, BrowserWindow and WebFrame) are not serializable with Structured Clone. Whenever the old algorithm was invoked, a deprecation warning was printed.

In Electron 9.0, the old serialization algorithm has been removed, and sending such non-serializable objects will now throw an "object could not be cloned" error.

API Changed: `shell.openItem` is now `shell.openPath`

The shell.openItem API has been replaced with an asynchronous shell.openPath API. You can see the original API proposal and reasoning here.

Запланированные критические изменения API (8.0)

Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm

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.

// 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 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:

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.

Obsoleto: `<webview>.getWebContents()`

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

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

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

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

Deprecated: `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.

// Deprecated
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

Deprecated: methods in `systemPreferences`

Следующие systemPreferences были устаревшими:

systemPreferences.isDarkMode()
systemPreferences.isvertedColorScheme()
systemPreferences.isHighContrastColorScheme()

Используйте следующие свойства nativeTheme вместо этого:

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

// Deprecated
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme

// Deprecated
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors

Запланированные критические изменения API (7.0)

Deprecated: Atom.io Node Headers URL

Это URL, указанный как disturl в файле .npmrc или как --dist-url флаг командной строки, при сборке нативных модулей Node. Оба будут поддерживаться в обозримом будущем, но рекомендуется переключиться.

Deprecated: https://atom.io/download/electron

Replace with: https://electronjs.org/headers

API Changed: `session.clearAuthCache()` no longer accepts options

session.clearAuthCache API больше не принимает параметры для очистки, а вместо этого безоговорочно очищает весь кэш.

// Устарело
session.clearAuthCache({ type: 'password' })
// Заменить на
session.clearAuthCache()

API Changed: `powerMonitor.querySystemIdleState` is now `powerMonitor.getSystemIdleState`

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

API Changed: `powerMonitor.querySystemIdleTime` is now `powerMonitor.getSystemIdleTime`

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

API Changed: `webFrame.setIsolatedWorldInfo` replaces separate methods

// Удалено в Electron 7.0
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'
  })

Removed: `marked` property on `getBlinkMemoryInfo`

Это свойство было удалено в Chromium 77, и как таковое больше не доступно.

Behavior Changed: `webkitdirectory` attribute for `<input type="file"/>` now lists directory contents

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:

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

In Electron <=6, this would return a FileList with a File object for:

path/to/folder

In Electron 7, this now returns a FileList with a File object for:

/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 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
contentTracing.getCategories() #16583
contentTracing.getTraceBufferUsage() #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
inAppPurchase.getProducts() #17355
inAppPurchase.purchaseProduct()#17355
netLog.stopLogging() #16862
session.clearAuthCache() #17259
session.clearCache() #17185
session.clearHostResolverCache() #17229
session.clearStorageData() #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

These functions now have two forms, synchronous and Promise-based asynchronous:

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

Запланированные критические изменения API (6.0)

API Changed: `win.setMenu(null)` is now `win.removeMenu()`

// Устаревшее
win.setMenu(null)
// Заменено на
win.removeMenu()

API Changed: `electron.screen` in the renderer process should be accessed via `remote`

// Устаревшее
require('electron').screen
// Заменено на
require('electron').remote.screen

API Changed: `require()`ing node builtins in sandboxed renderers no longer implicitly loads the `remote` version

// Устаревшее
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')

Deprecated: `powerMonitor.querySystemIdleState` replaced with `powerMonitor.getSystemIdleState`

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

Deprecated: `powerMonitor.querySystemIdleTime` replaced with `powerMonitor.getSystemIdleTime`

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

Deprecated: `app.enableMixedSandbox()` is no longer needed

// Устарело
app.enableMixedSandbox()

Режим смешанной песочницы теперь включен по умолчанию.

Deprecated: `Tray.setHighlightMode`

Под macOS Catalina наша прежняя реализация Tray нарушена. Нативная замена Apple не поддерживает изменение поведения подсветки.

// Устарело
tray.setHighlightMode(mode)
// Метод будет удален в v7.0 без альтернатив.

Запланированные критические изменения API (5.0)

Default Changed: `nodeIntegration` and `webviewTag` default to false, `contextIsolation` defaults to true

Следующие значения по умолчанию для параметра webPreferences устарели в пользу новых значений по умолчанию, перечисленных ниже.

Свойство	Устаревшее	Новое
`contextIsolation`	`false`	`true`
`nodeIntegration`	`true`	`false`
`webviewTag`	`nodeIntegration`, если установлено, иначе `true`	`false`

Например, Re-enabling the webviewTag

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

Behavior Changed: `nodeIntegration` in child windows opened via `nativeWindowOpen`

Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is true.

API Changed: Registering privileged schemes must now be done before app ready

Renderer process APIs webFrame.registerURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. Новый API protocol.registerSchemesAsPrivileged был добавлен и должен использоваться для регистрации пользовательских схем с необходимыми привилегиями. Пользовательские схемы должны быть зарегистрированы до готовности приложения.

Deprecated: `webFrame.setIsolatedWorld*` replaced with `webFrame.setIsolatedWorldInfo`

// Устарело
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'
  })

API Changed: `webFrame.setSpellCheckProvider` now takes an asynchronous callback

Параметр spellCheck теперь асинхронный, а параметр autoCorrectWord был удален.

// Устаревшее
webFrame.setSpellCheckProvider('en-US', true, {
  spellCheck: (text) => {
    return !spellchecker. sMisspelled(text)
  }
})
// Заменить на
webFrame. etSpellCheckProvider('en-US', {
  spellCheck: (words, callback) => {
    callback(слова. ilter(text => spellchecker.isMisspelled(text)))
  }
})

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.

// Deprecated
webContents.getZoomLevel((level) => {
  console.log(level)
})
// Replace with
const level = webContents.getZoomLevel()
console.log(level)

// Deprecated
webContents.getZoomFactor((factor) => {
  console.log(factor)
})
// Replace with
const factor = webContents.getZoomFactor()
console.log(factor)

Запланированные критические изменения API (4.0)

Следующий список включает в себя критические изменения API, сделанные в Electron 4.0.

`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.getGPUInfo`

app.getGPUInfo('complete')
// Теперь ведет себя так же с `basic` в macOS
app.getGPUInfo('basic')

`win_delay_load_hook`

При создании нативных модулей для Windows переменная win_delay_load_hook в binding.gyp модуля должна быть true (это значение по умолчанию). Если этот хук отсутствует, то нативный модуль на Windows неудачно загрузится, с сообщением об ошибке, например Cannot find module. See the native module guide for more.

Критические изменения API (3.0)

Данный список включает в себя критические изменения в API для Electron 3.0.

`app`

// Устарело
app.getAppMemoryInfo()
// Заменить на
app.getAppMetrics()

// Устарело
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // свойство устарело

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

// Устарело
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&nbsp;= () => { /* обработчик */ }
webview.onkeyup&nbsp;= () => { /* обработчик */ }

Node Headers URL

Это URL, указанный как disturl в файле .npmrc или как --dist-url флаг командной строки, при сборке нативных модулей Node.

Устарело: https://atom.io/download/atom-shell

Заменено на: https://atom.io/download/electron

Критические изменения API (2.0)

Следующий список включает в себя критические изменения API, сделанные в Electron 2.0.

`BrowserWindow`

// Deprecated
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { titleBarStyle: 'hiddenInset' }
const 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, которые могут быть произведены.

The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Начиная с версии 2.0, файл без префикса более не будет публиковаться.

Для подробностей см. 6986 и 7189.

Типы критических изменений
Запланированные критические изменения API (17.0)
- Removed: desktopCapturer.getSources in the renderer
Запланированные критические изменения API (16.0)
- Behavior Changed: crashReporter implementation switched to Crashpad on Linux
- Deprecated: desktopCapturer.getSources in the renderer
Запланированные критические изменения API (15.0)
- Default Changed: nativeWindowOpen defaults to true
Запланированные критические изменения API (14.0)
Запланированные критические изменения API (13.0)
Запланированные критические изменения API (12.0)
Запланированные критические изменения API (11.0)
- Removed: BrowserView.{destroy, fromId, fromWebContents, getAllViews} and id property of BrowserView
Запланированные критические изменения API (10.0)
Запланированные критические изменения API (9.0)
Запланированные критические изменения API (8.0)
Запланированные критические изменения API (7.0)
Запланированные критические изменения API (6.0)
Запланированные критические изменения API (5.0)
Запланированные критические изменения API (4.0)
Критические изменения API (3.0)
Критические изменения API (2.0)

Типы критических изменений​

Запланированные критические изменения API (17.0)​

Removed: desktopCapturer.getSources in the renderer​

Запланированные критические изменения API (16.0)​

Behavior Changed: crashReporter implementation switched to Crashpad on Linux​

Deprecated: desktopCapturer.getSources in the renderer​

Запланированные критические изменения API (15.0)​

Default Changed: nativeWindowOpen defaults to true​

Запланированные критические изменения API (14.0)​

Removed: remote module​

Удален: app.allowRendererProcessReuse​

Removed: Browser Window Affinity​

Изменения в API: window.open()​

Удален: worldSafeExecuteJavaScript​

Removed: BrowserWindowConstructorOptions inheriting from parent windows​

Удален: additionalFeatures​

Запланированные критические изменения API (13.0)​

Изменения в API: session.setPermissionCheckHandler(handler)​

Удален: shell.moveItemToTrash()​

Удалено: BrowserWindow API расширений​

Удалено: методы в systemPreferences​

Устарело: WebContents new-window событие​

Запланированные критические изменения API (12.0)​

Удалено: Поддержка Pepper Flash​

Default Changed: worldSafeExecuteJavaScript defaults to true​

Default Changed: contextIsolation defaults to true​

Удален: crashReporter.getCrashesDirectory()​

Removed: crashReporter methods in the renderer process​

Default Changed: crashReporter.start({ compress: true })​

Deprecated: remote module​

Obsoleto: shell.moveItemToTrash()​

Запланированные критические изменения API (11.0)​

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

Запланированные критические изменения API (10.0)​

Deprecated: companyName argument to crashReporter.start()​

Obsoleto: crashReporter.getCrashesDirectory()​

Deprecated: crashReporter methods in the renderer process​

Obsoleto: crashReporter.start({ compress: false })​

Изменение значения по-умолчанию: enableRemoteModule изменено на false​

protocol.unregisterProtocol​

protocol.uninterceptProtocol​

protocol.registerFileProtocol​

protocol.registerBufferProtocol​

protocol.registerStringProtocol​

protocol.registerHttpProtocol​

protocol.registerStreamProtocol​

protocol.interceptFileProtocol​

protocol.interceptStringProtocol​

protocol.interceptBufferProtocol​

protocol.interceptHttpProtocol​

protocol.interceptStreamProtocol​

protocol.isProtocolHandled​

Запланированные критические изменения API (9.0)​

Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default​

Deprecated: BrowserWindow extension APIs​

Removed: <webview>.getWebContents()​

Удален: webFrame.setLayoutZoomLevelLimits()​

Behavior Changed: Sending non-JS objects over IPC now throws an exception​

API Changed: shell.openItem is now shell.openPath​

Запланированные критические изменения API (8.0)​

Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm​

Obsoleto: <webview>.getWebContents()​

Deprecated: webFrame.setLayoutZoomLevelLimits()​

Deprecated events in systemPreferences​

Deprecated: methods in systemPreferences​

Запланированные критические изменения API (7.0)​

Deprecated: Atom.io Node Headers URL​

API Changed: session.clearAuthCache() no longer accepts options​

API Changed: powerMonitor.querySystemIdleState is now powerMonitor.getSystemIdleState​

API Changed: powerMonitor.querySystemIdleTime is now powerMonitor.getSystemIdleTime​

API Changed: webFrame.setIsolatedWorldInfo replaces separate methods​

Removed: marked property on getBlinkMemoryInfo​

Behavior Changed: webkitdirectory attribute for <input type="file"/> now lists directory contents​

API Changed: Callback-based versions of promisified APIs​

Запланированные критические изменения API (6.0)​

API Changed: win.setMenu(null) is now win.removeMenu()​

API Changed: electron.screen in the renderer process should be accessed via remote​

API Changed: require()ing node builtins in sandboxed renderers no longer implicitly loads the remote version​

Deprecated: powerMonitor.querySystemIdleState replaced with powerMonitor.getSystemIdleState​

Deprecated: powerMonitor.querySystemIdleTime replaced with powerMonitor.getSystemIdleTime​

Типы критических изменений

Запланированные критические изменения API (17.0)

Removed: `desktopCapturer.getSources` in the renderer

Запланированные критические изменения API (16.0)

Behavior Changed: `crashReporter` implementation switched to Crashpad on Linux

Deprecated: `desktopCapturer.getSources` in the renderer

Запланированные критические изменения API (15.0)

Default Changed: `nativeWindowOpen` defaults to `true`

Запланированные критические изменения API (14.0)

Removed: `remote` module

Удален: `app.allowRendererProcessReuse`

Removed: Browser Window Affinity

Изменения в API: `window.open()`

Удален: `worldSafeExecuteJavaScript`

Removed: BrowserWindowConstructorOptions inheriting from parent windows

Удален: `additionalFeatures`

Запланированные критические изменения API (13.0)

Изменения в API: `session.setPermissionCheckHandler(handler)`

Удален: `shell.moveItemToTrash()`

Удалено: `BrowserWindow` API расширений

Удалено: методы в `systemPreferences`

Устарело: WebContents `new-window` событие

Запланированные критические изменения API (12.0)

Удалено: Поддержка Pepper Flash

Default Changed: `worldSafeExecuteJavaScript` defaults to `true`

Default Changed: `contextIsolation` defaults to `true`

Удален: `crashReporter.getCrashesDirectory()`

Removed: `crashReporter` methods in the renderer process

Default Changed: `crashReporter.start({ compress: true })`

Deprecated: `remote` module

Obsoleto: `shell.moveItemToTrash()`

Запланированные критические изменения API (11.0)

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

Запланированные критические изменения API (10.0)

Deprecated: `companyName` argument to `crashReporter.start()`

Obsoleto: `crashReporter.getCrashesDirectory()`

Deprecated: `crashReporter` methods in the renderer process

Obsoleto: `crashReporter.start({ compress: false })`

Изменение значения по-умолчанию: `enableRemoteModule` изменено на `false`

`protocol.unregisterProtocol`

`protocol.uninterceptProtocol`

`protocol.registerFileProtocol`

`protocol.registerBufferProtocol`

`protocol.registerStringProtocol`

`protocol.registerHttpProtocol`

`protocol.registerStreamProtocol`

`protocol.interceptFileProtocol`

`protocol.interceptStringProtocol`

`protocol.interceptBufferProtocol`

`protocol.interceptHttpProtocol`

`protocol.interceptStreamProtocol`

`protocol.isProtocolHandled`

Запланированные критические изменения API (9.0)

Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default

Deprecated: `BrowserWindow` extension APIs

Removed: `<webview>.getWebContents()`

Удален: `webFrame.setLayoutZoomLevelLimits()`

Behavior Changed: Sending non-JS objects over IPC now throws an exception

API Changed: `shell.openItem` is now `shell.openPath`

Запланированные критические изменения API (8.0)

Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm

Obsoleto: `<webview>.getWebContents()`

Deprecated: `webFrame.setLayoutZoomLevelLimits()`

Deprecated events in `systemPreferences`

Deprecated: methods in `systemPreferences`

Запланированные критические изменения API (7.0)

Deprecated: Atom.io Node Headers URL

API Changed: `session.clearAuthCache()` no longer accepts options

API Changed: `powerMonitor.querySystemIdleState` is now `powerMonitor.getSystemIdleState`

API Changed: `powerMonitor.querySystemIdleTime` is now `powerMonitor.getSystemIdleTime`

API Changed: `webFrame.setIsolatedWorldInfo` replaces separate methods

Removed: `marked` property on `getBlinkMemoryInfo`

Behavior Changed: `webkitdirectory` attribute for `<input type="file"/>` now lists directory contents

API Changed: Callback-based versions of promisified APIs

Запланированные критические изменения API (6.0)

API Changed: `win.setMenu(null)` is now `win.removeMenu()`

API Changed: `electron.screen` in the renderer process should be accessed via `remote`

API Changed: `require()`ing node builtins in sandboxed renderers no longer implicitly loads the `remote` version

Deprecated: `powerMonitor.querySystemIdleState` replaced with `powerMonitor.getSystemIdleState`

Deprecated: `powerMonitor.querySystemIdleTime` replaced with `powerMonitor.getSystemIdleTime`