Changements de rupture
Les changements cassants seront documentés ici, et des avertissements de dépréciations ajoutés au code JS quand possible, au moins une version majeur avant que le changement soit fait.
Types de modifications majeures
Ce document utilise la convention suivante pour catégoriser les modifications majeures :
- API modifiée : Une API a été modifiée avec la garantie que du code non modifié déclenchera une exception.
- Comportement modifié : Le comportement d'Electron a changé, mais pas de telle manière qu'une exception soit nécessairement déclenchée.
- Valeur par défaut modifiée : Le code dépendant de l'ancienne valeur par défaut peut ne plus fonctionner, sans nécessairement déclencher une exception. Le comportement d'origine peut être restauré en spécifiant explicitement la valeur.
- Déprécié : une API a été marquée comme étant dépréciée. L'API continuera à fonctionner, mais émettra une alerte de dépréciation, et sera supprimée dans une prochaine version.
- Supprimé: Une API ou une fonctionnalité a été supprimée et n'est plus prise en charge par Electron.
Changements majeurs prévus de l'API (20.0)
Default Changed: renderers without nodeIntegration: true
are sandboxed by default
Previously, renderers that specified a preload script defaulted to being unsandboxed. This meant that by default, preload scripts had access to Node.js. In Electron 20, this default has changed. Beginning in Electron 20, renderers will be sandboxed by default, unless nodeIntegration: true
or sandbox: false
is specified.
If your preload scripts do not depend on Node, no action is needed. If your preload scripts do depend on Node, either refactor them to remove Node usage from the renderer, or explicitly specify sandbox: false
for the relevant renderers.
Removed: skipTaskbar
on Linux
On X11, skipTaskbar
sends a _NET_WM_STATE_SKIP_TASKBAR
message to the X11 window manager. There is not a direct equivalent for Wayland, and the known workarounds have unacceptable tradeoffs (e.g. Window.is_skip_taskbar in GNOME requires unsafe mode), so Electron is unable to support this feature on Linux.
Planned Breaking API Changes (19.0)
None
Planned Breaking API Changes (18.0)
Supprimé : nativeWindowOpen
Avant Electron 15, window.open
utilisait par défaut BrowserWindowProxy
. This meant that window.open('about:blank')
did not work to open synchronously scriptable child windows, among other incompatibilities. Since Electron 15, nativeWindowOpen
has been enabled by default.
Consultez la documentation de window.open dans Electron pour plus de détails.
Changements majeurs prévus de l'API (17.0)
Supprimé: desktopCapturer.getSources
dans le moteur de rendu
Dorénavant l’API desktopCapturer.getSources
n’est plus disponible que dans le processus principal. Cela a été modifié afin d’améliorer la sécurité par défaut des applications Electron .
Si vous avez besoin de cette fonctionnalité, elle peut être remplacée comme suit :
// Main process
const { ipcMain, desktopCapturer } = require('electron')
ipcMain.handle(
'DESKTOP_CAPTURER_GET_SOURCES',
(event, opts) => desktopCapturer.getSources(opts)
)
// Processus de rendu
const { ipcRenderer } = require('electron')
const desktopCapturer = {
getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
}
Toutefois, vous devez envisager de restreindre davantage les informations renvoyées au moteur de rendu ; par exemple en affichant pour l'utilisateur un sélecteur de source et retourner ce qui provient de la source sélectionnée.
Déprécié : nativeWindowOpen
Avant Electron 15, window.open
utilisait par défaut BrowserWindowProxy
. This meant that window.open('about:blank')
did not work to open synchronously scriptable child windows, among other incompatibilities. Since Electron 15, nativeWindowOpen
has been enabled by default.
Consultez la documentation de window.open dans Electron pour plus de détails.
Changements majeurs prévus de l'API (16.0)
Changement de comportement : l'implémentation de crashReporter
utilise Crashpad sous Linux
L'implémentation sous-jacente de l'API crashReporter
sous Linux est passée de Breakpad à Crashpad, le rendant conforme à Windows et Mac. En conséquence, les processus enfants sont désormais automatiquement monitorés et l’appel de process.crashReporter.start
dans les processus enfants de Node n’est plus nécessaire (ni conseillé d'ailleurs, car il démarrerait une deuxième instance du rapporteur Crashpad).
Il y a aussi quelques changements subtils dans la façon dont les annotations seront signalées sous Linux, notamment les valeurs longues ne seront plus présentées dans plusieurs annotations suffixées par __1
, __2
etc., mais seront plutôt tronquées à la taille limite des annotations (nouvelle et plus longue).
Obsolète : desktopCapturer.getSources
dans le moteur de rendu
L’utilisation de l’API desktopCapturer.getSources
dans le moteur de rendu est Obsolète et sera supprimée. Ce changement améliore la sécurité par défaut des applications Electron.
Consultez ceci pour plus d’informations sur comment remplacer cette API dans votre application.
Changements majeurs prévus de l'API (15.0)
Valeur par défaut modifié : nativeWindowOpen
est par défaut à true
Avant Electron 15, window.open
utilisait par défaut 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.
Consultez la documentation de window.open dans Electron pour plus de détails.
Changements majeurs prévus de l'API (14.0)
Removed: remote
module
Le module remote
a été déprécié dans Electron 12, et sera supprimé dans Electron 14. Il est remplacé par le module @electron/remote
.
// Déprécié dans Electron 12 :
const { BrowserWindow } = require('electron').remote
Remplacer par :
const { BrowserWindow } = require('@electron/remote')
// Dans le processus principal:
require('@electron/remote/main').initialize()
Supprimé : app.allowRendererProcessReuse
La propriété app.allowRendererProcessReuse
sera supprimée dans le cadre de notre plan visant à être le plus étroitement aligné sur le modèle de processus de Chromium en matière de sécurité, de performance et de maintenabilité.
Pour des informations plus détaillées, voir #18397.
Suppression : Browser Window Affinity
L'option affinity
lors de l'instanciation d'une nouvelle BrowserWindow
sera supprimée dans le cadre de notre plan d'alignement sur le modèle de processus de Chromium à des fins de sécurité, performances et maintenabilité.
Pour des informations plus détaillées, voir #18397.
API modifiée : window.open()
Le paramètre optionnel frameName
ne définira plus le titre de la fenêtre. Ceci conformément à la spécification décrite par la documentation native sous le paramètre correspondant windowName
.
Si vous utilisiez ce paramètre pour définir le titre d'une fenêtre, vous devez utiliser à la place: win.setTitle(title).
Supprimé : worldSafeExecuteJavaScript
Dans Electron 14, worldSafeExecuteJavaScript
sera supprimé. Il n'y a pas d'alternative, s'il vous plaît assurez-vous que votre code fonctionne avec cette propriété activée. Il a été activé par défaut depuis Electron
12.
Vous serez affecté par ce changement si vous utilisez webFrame.executeJavaScript
ou webFrame.executeJavaScriptInIsolatedWorld
. Vous devrez vous assurer que les valeurs renvoyées par l’une ou l’autre de ces méthodes sont prises en charge par l’API Context Bridge car ces méthodes utilisent la même sémantique de transmission de valeur.
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. À partir d'Electron 14, ce comportement est supprimé et les fenêtres n'hériteront d'aucune option du constructeur BrowserWindow de leurs parents.
Instead, explicitly set options for the new window with setWindowOpenHandler
:
webContents.setWindowOpenHandler((details) => {
return {
action: 'allow',
overrideBrowserWindowOptions: {
// ...
}
}
})
Supprimé : 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 []
. (Notez toutefois que l’événement new-window
lui-même est déprécié et remplacé par 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']) {
// ...
}
})
Changements majeurs prévus de l'API (13.0)
API modifiée : session.setPermissionCheckHandler(handler)
Le premier paramètre handler
des méthodes était auparavant toujours un webContents
, il peut maintenant parfois être null
. Vous devez utiliser les propriétés requestingOrigin
, embeddingOrigin
et securityOrigin
pour répondre correctement à la vérification des permissions. Comme le webContents
peut être désormais null
, on ne peut plus s'y fier.
// Ancien code:
session.setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
return true
}
return false
})
// A remplacer par:
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
return true
}
return false
})
Supprimé: shell.moveItemToTrash()
L’API shell.moveItemToTrash()
synchrone qui était dépréciée a été supprimée. Utilisez shell.trashItem() asynchrone
à la place.
// Supprimé dans Electron 13
shell.moveItemToTrash(path)
// Remplacer par
shell.trashItem(path).then(/* ... */)
Removed: BrowserWindow
extension APIs
Les API d'extension obsolètes ont été supprimées :
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
Utilisez plutôt les API de session :
ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()
// Supprimé dans Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Remplacer par
session.defaultSession.loadExtension(path)
Supprimé dans Electron 13
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Remplacer par
session.defaultSession.removeExtension(extension_id)
Supprimé dans Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Remplacer par
session.defaultSession.getAllExtensions()
Méthodes supprimées dans systemPreferences
Les méthodes suivantes de systemPreferences
ont été dépréciées :
systemPreferences.isDarkMode()
systemPreferences.isInvertedColorScheme()
systemPreferences.isHighContrastColorScheme()
Veuillez utiliser à la place les propriétés de nativeTheme
suivantes :
nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors
// Supprimée dans Electron 13
systemPreferences.isDarkMode()
// Remplacée par
nativeTheme.shouldUseDarkColors
// Supprimée dans Electron 13
systemPreferences.isInvertedColorScheme()
// Remplacée par
nativeTheme.shouldUseInvertedColorScheme
// Supprimée dans Electron 13
systemPreferences.isHighContrastColorScheme()
// Remplacée par
nativeTheme.shouldUseHighContrastColors
Obsolète : événement WebContents new-window
L'événement new-window
de WebContents est déprécié. Il est remplacé par webContents.setWindowOpenHandler()
.
// Déprécié dans Electron 13
webContents.on('new-window', (event) => {
event.preventDefault()
})
// Remplacer par
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})
Changements majeurs prévus de l'API (12.0)
Supprimé: Support de Pepper Flash
Chromium a supprimé la prise en charge de Flash, nous devons donc emboîter le pas. Consultez la feuille de route Flash de Chromium pour plus de détails.
Changements de rupturetrue
Dans Electron 12, worldSafeExecuteJavaScript
sera activé par défaut. Restaurer le comportement précédent, worldSafeExecuteJavaScript: false
doit être spécifié dans WebPreferences. Veuillez noter que définir cette option sur false
est non sécurisé.
Cette option sera supprimée dans Electron 14, veuillez donc migrer votre code pour prendre en charge la valeur par défaut.
Valeur par défaut modifié : contextIsolation
est par défaut à true
Dans Electron 12, contextIsolation
sera activé par défaut. Restaurer le comportement précédent, contextIsolation: false
doit être spécifié dans WebPreferences.
Nous recommandons que contextIsolation soit activé pour la sécurité de votre application.
En conséquence require()
ne peut pas être utilisé dans le processus de rendu à sauf si nodeIntegration
est à true
et contextIsolation
à false
.
Pour plus de détails, voir : https://github.com/electron/electron/issues/23506
Supprimé : crashReporter.getCrashesDirectory()
La méthode crashReporter.getCrashesDirectory
a été supprimée. Usage Devrait être remplacé par app.getPath('crashDumps')
.
// Supprimé dans Electron 12
crashReporter.getCrashesDirectory()
// Remplacé par
app.getPath('crashDumps')
Supprimé : méthodes crashReporter
dans le processus de rendu
Les méthodes crashReporter
suivantes ne sont plus disponibles dans le processus de rendu :
crashReporter.start
crashReporter.getLastCrashReport
crashReporter.getUploadedReports
crashReporter.getUploadToServer
crashReporter.setUploadToServer
crashReporter.getCrashesDirectory
Ils ne doivent être appelés qu'à partir du processus principal.
Voir #23265 pour plus de détails.
Valeur par défaut modifiée : crashReporter.start({ compress: true })
La valeur par défaut de l'option compress
en crashReporter.start
a changé de false
à true
. Cela signifie que les rapports de plantage seront envoyés au serveur d'ingestion de plantage avec l'en-tête Content-Encoding: gzip
et le corps sera compressé.
Si votre serveur d'ingestion de plantage ne supporte pas les payloads compressées, vous pouvez désactiver la compression en spécifiant { compress: false }
dans les options du rapporteur de plantage.
Déprécié : moduleremote
Le module remote
est déprécié dans Electron 12, et sera supprimé dans Electron 14. Il est remplacé par le module @electron/remote
.
// Déprécié dans Electron 12 :
const { BrowserWindow } = require('electron').remote
Remplacer par :
const { BrowserWindow } = require('@electron/remote')
// Dans le processus principal:
require('@electron/remote/main').initialize()
Déprécié : shell.moveItemToTrash()
La méthode synchrone shell.moveItemToTrash()
a été remplacée par une asynchrone shell.trashItem()
.
Déprécié dans Electron 12
shell.moveItemToTrash(path)
// Remplacer par
shell.trashItem(path).then(/* ... */)
Changements majeurs prévus de l'API (11.0)
Supprimés: BrowserView.{destroy, fromId, fromWebContents, getAllViews}
et id
propriété de BrowserView
Les API expérimentales BrowserView.{destroy, fromId, fromWebContents, getAllViews}
ont maintenant été supprimées. De plus, la propriété id
de BrowserView
a également été supprimée.
Pour des informations plus détaillées, voir #23578.
Changements majeurs prévus de l'API (10.0)
Déprécié : l'argument companyName
de crashReporter.start()
L'argument companyName
de crashReporter.start()
, qui était auparavant requis, est maintenant optionnel et de plus déprécié. Pour obtenir le même comportement de manière non dépréciée, vous pouvez passer une valeur companyName
dans globalExtra
.
// Déprécié dans Electron 10
crashReporter.start({ companyName: 'Umbrella Corporation' })
// Remplacé par
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' }})
Déprécié : crashReporter.getCrashesDirectory()
La méthode crashReporter.getCrashesDirectory
a été dépréciée. Usage Devrait être remplacé par app.getPath('crashDumps')
.
// Déprécié dans Electron 10
crashReporter.getCrashesDirectory()
// Remplacé par
app.getPath('crashDumps')
Déprécié : méthodes crashReporter
dans le processus de rendu
L'appel des méthodes crashReporter
suivantes à partir du processus de rendu est déprécié :
crashReporter.start
crashReporter.getLastCrashReport
crashReporter.getUploadedReports
crashReporter.getUploadToServer
crashReporter.setUploadToServer
crashReporter.getCrashesDirectory
Les seules méthodes non obsolètes restantes dans le module crashReporter
du renderer sont addExtraParameter
, removeExtraParameter
et getParameters
.
Toutes les méthodes ci-dessus restent non dépréciées lorsqu'elles sont appelées à partir du processus principal.
Voir #23265 pour plus de détails.
Déprécié : crashReporter.start({ compress: false })
La configuration { compress: false }
dans crashReporter.start
est obsolète. Presque tous les serveurs d'ingestion de plantages supportent la compression gzip. Cette option sera supprimée dans une future version d’Electron.
Valeur par défaut modifié : enableRemoteModule
est par défaut à false
Dans Electron 9, l'utilisation du module remote sans l'activer explicitement via l'option enableRemoteModule
de WebPreferences émet dès maintenant un avertissement. Avec Electron 10, le module remote est dès maintenant désactivé par défaut. Pour utiliser le module remote, on doit spécifier enableRemoteModule : true
dans les WebPreferences:
const w = new BrowserWindow({
webPreferences: {
enableRemoteModule: true
}
})
Nous vous recommandons d'éviter d'utiliser le module distant.
protocol.unregisterProtocol
protocol.uninterceptProtocol
Les API sont désormais synchrones donc la callback qui était facultative n'est plus nécessaire.
// Déprécié
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// Remplacer par
protocol.unregisterProtocol(scheme)
protocol.registerFileProtocol
protocol.registerBufferProtocol
protocol.registerStringProtocol
protocol.registerHttpProtocol
protocol.registerStreamProtocol
protocol.interceptFileProtocol
protocol.interceptStringProtocol
protocol.interceptBufferProtocol
protocol.interceptHttpProtocol
protocol.interceptStreamProtocol
Les API sont désormais synchrones donc la callback qui était facultative n'est plus nécessaire.
// Déprécié
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Remplacer par
protocol.registerFileProtocol(scheme, handler)
Le protocole enregistré ou intercepté n'a pas d'effet sur la page actuelle tant que la navigation n'a pas eu lieu.
protocol.isProtocolHandled
Cette API est dépréciée et les utilisateurs doivent utiliser à la place protocol.isProtocolRegistered
et protocol.isProtocolIntercepted
.
// Déprécié
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Remplacer par
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)
Changements majeurs prévus de l'API (9.0)
Fonctionnement par défaut modifié : le chargement des modules natifs non contextuels dans le processus de rendu est désactivé par défaut
À partir d’Electron 9, nous n’autorisons plus le chargement de modules natifs insensibles au contexte dans le processus de rendu. Ceci est pour améliorer la sécurité, les performances et la maintenabilité d'Electron en tant que projet.
Si cela vous affecte, vous pouvez définir temporairement app.allowRendererProcessReuse
pour faux
pour revenir à l’ancien comportement. Ce drapeau ne sera une option que jusqu'à Electron 11 donc vous devriez planifier de mettre à jour vos modules natifs pour être sensible au contexte.
Pour des informations plus détaillées, voir #18397.
Déprécié : API d'extension BrowserWindow
Les API d'extension suivantes sont obsolètes :
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
Utilisez plutôt les API de session :
ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()
// Déprécié dans Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Remplacer par
session.defaultSession.loadExtension(path)
// Déprécié dans Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Remplacer par
session.defaultSession.removeExtension(extension_id)
// Déprécié dans Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Remplacé par
session.defaultSession.getAllExtensions()
Supprimé: <webview>.getWebContents()
Cette API, qui a été dépréciée dans Electron 8.0, est désormais supprimée.
// Supprimé dans Electron 9.0
webview.getWebContents()
// Remplacé par
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())
Supprimé : webFrame.setLayoutZoomLevelLimits()
Chrome a supprimé la prise en charge pour modifier les limites de niveau de zoom de mise en page et il n'est plus possible pour Electron de le maintenir. La fonction a été dépréciée dans Electron 8.x, et supprimée dans Electron 9.x. Les limites de niveau de zoom de mise en page sont maintenant fixées à un minimum de 0. 5 et un maximum de 5.0, tel que défini ici.
Comportement modifié : l’envoi d’objets non-JS au travers d' IPC déclenche maintenant une exception
Dans Electron 8.0, l'IPC a été modifié pour utiliser l'algorithme Structured Clone , apportant des améliorations significatives des performances. Pour aider à faciliter la transition, l'ancien algorithme de sérialisation IPC a été conservé et utilisé pour certains objets qui ne sont pas sérialisables avec 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. Chaque fois que l'ancien algorithme était invoqué, un un avertissement de dépréciation a été imprimé.
Dans la version 9.0 d'Electron, l'ancien algorithme de sérialisation a été supprimé, et l'envoi de tels objets non sérialisables lèvera dorénavant une erreur "object could not be cloned".
API modifiée : shell.openItem
est désormais shell.openPath
L'API shell.openItem
a été remplacée par une API shell.openPath
asynchrone. Vous pouvez voir la proposition initiale de l'API et le raisonnement ici.
Changements majeurs prévus de l'API (8.0)
Comportement modifié : les valeurs envoyées par IPC sont maintenant sérialisées avec l'algorithme de clonage structuré
L'algorithme utilisé pour sérialiser les objets envoyés par IPC (via ipcRenderer.send
, ipcRenderer.sendSync
, WebContents. les méthodes de fin
et associées) est passé d'un algorithme personnalisé à l'algorithme intégré de V8 Structured Clone Algorithm qui est déja utilisé pour sérialiser les messages dans postMessage
. Cela entraîne une amélioration dans un rapport 2 des performances en ce qui concerne les messages de grande taille, mais apporte également quelques changements de rupture dans le comportement.
- 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
et-Infinity
seront désormais correctement sérialisés à la place d'être converti ennull
.- Les objets contenant des références cycliques seront désormais correctement sérialisés, au lieu d'être converti en
null
. - Les valeurs
Set
,Map
,Error
etRegExp
seront correctement sérialisées, au lieu d'être converti en{}
. - Les valeurs
BigInt
seront correctement sérialisées, au lieu d'être converties ennull
. - Sparse arrays will be serialized as such, instead of being converted to dense arrays with
null
s. Date
objects will be transferred asDate
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.jsBuffer
. - Node.js
Buffer
objects will be transferred asUint8Array
s. You can convert aUint8Array
back to a Node.jsBuffer
by wrapping the underlyingArrayBuffer
:
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.
Déprécié : <webview>.getWebContents()
Cette API est implémentée à l'aide du module remote
, qui a à la fois des performances et les implications en matière de sécurité. Par conséquent, son utilisation doit être explicite.
// Déprécié
webview.getWebContents()
// Remplacé par
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())
Cependant, il est recommandé d'éviter d'utiliser le module remote
.
// main
const { ipcMain, webContents } = require('electron')
const getGuestForWebContents = (webContentsId, contents) => {
const guest = webContents. romId(webContentsId)
si (! uest) {
throw new Error(`Invalid webContentsId: ${webContentsId}`)
}
if (invité. ostWebContents ! = contents) {
throw new Error('Accès refusé à webContents')
}
return guest
}
ipcMain. handle('openDevTools', (event, webContentsId) => {
const guest = getGuestForWebContents(webContentsId, event.sender)
invité. penDevTools()
})
// moteur de rendu
const { ipcRenderer } = require('electron')
ipcRenderer.invoke('openDevTools', webview.getWebContentsId())
Déprécié : webFrame.setLayoutZoomLevelLimits()
Chrome a supprimé la prise en charge pour modifier les limites de niveau de zoom de mise en page et il n'est plus possible pour Electron de le maintenir. La fonction émettra un avertissement dans Electron 8.x, et cessent d'exister dans 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.
Événements obsolètes dans systemPreferences
Les événements systemPreferences
suivants ont été dépréciés :
inverted-color-scheme-changed
high-contrast-color-scheme-changed
Utilisez à la place le nouvel événement updated
sur le module nativeTheme
.
// Deprécié
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replacer avec
nativmeTheme.on('updated', () => { /* ... */ })
Méthodes obsolètes dans systemPreferences
Les méthodes suivantes de systemPreferences
ont été dépréciées :
systemPreferences.isDarkMode()
systemPreferences.isInvertedColorScheme()
systemPreferences.isHighContrastColorScheme()
Veuillez utiliser à la place les propriétés de nativeTheme
suivantes :
nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors
// Depreciée
systemPreferences.isDarkMode()
// Remplacer par
nativeTheme.shouldUseDarkColors
// Depreciée
systemPreferences.isInvertedColorScheme()
// Remplacer par
nativeTheme.shouldUseInvertedColorScheme
// Depreciée
systemPreferences.isHighContrastColorScheme()
// Remplacer par
nativeTheme.shouldUseHighContrastColors
Changements majeurs prévus de l'API (7.0)
Deprecated: Atom.io Node Headers URL
Il s’agit de l’URL spécifiée comme disturl
dans un fichier .npmrc
ou le flag --dist-url
en ligne de commande lors de la compilation des modules natifs de Node. Both will be supported for the foreseeable future but it is recommended that you switch.
Déprécié : https://atom.io/download/electron
Remplacer par : https://electronjs.org/headers
API modifiée : session.clearAuthCache()
n'accepte plus les options
The session.clearAuthCache
API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
// Déprécié
session.clearAuthCache({ type: 'password' })
// Remplacer par
session.clearAuthCache()
API modifiée : powerMonitor.querySystemIdleState
est désormais powerMonitor.getSystemIdleState
// Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)
API modifiée : powerMonitor.querySystemIdleTime
est désormais 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
// Supprimé dans Electron 7.0
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Remplacer par
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})
Removed: marked
property on getBlinkMemoryInfo
Cette propriété a été supprimée dans Chromium 77 et n'est donc plus disponible.
Behavior Changed: webkitdirectory
attribute for <input type="file"/>
now lists directory contents
The webkitdirectory
property on HTML file inputs allows them to select folders. Dans les versions précédentes d'Electron l'implémentation était incorrecte et la propriété event.target.files
de l'input retournait une FileList
qui retournait un objet File
correspondant au dossier sélectionné.
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).
En guise d'illustration, considérez un dossier avec cette structure :
dossier
├── fichier1
├── fichier2
└── fichier3
Dans Electron < 6, cela renverrait une FileList
avec un objetFile
pour :
chemin/vers/dossier
Dans Electron 7, cela renvoie maintenant une FileList
avec un objetFile
pour :
/chemin/vers/dossier/fichier3
/chemin/vers/dossier/fichier2
/chemin/vers/dossier/fichier1
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 et Electron 6 ont introduit des versions des API asynchrones existantes basées sur les promise et déprécié leurs homologues basées sur les callback. Dans Electron 7, toutes les APIs obsolètes basées sur les callback sont maintenant supprimées.
Les fonctions suivantes ne retournent plus que des promesses :
app.getFileIcon()
#15742app.dock.show()
#16904contentTracing.getCategories()
#16583contentTracing.getTraceBufferUsage()
#16600contentTracing.startRecording()
#16584contentTracing.stopRecording()
#16584contents.executeJavaScript()
#17312cookies.flushStore()
#16464cookies.get()
#16464cookies.remove()
#16464cookies.set()
#16464debugger.sendCommand()
#16861dialog.showCertificateTrustDialog()
#17181inAppPurchase.getProducts()
#17355inAppPurchase.purchaseProduct()
#17355netLog.stopLogging()
#16862session.clearAuthCache()
#17259session.clearCache()
#17185session.clearHostResolverCache()
#17229session.clearStorageData()
#17249session.getBlobData()
#17303session.getCacheSize()
#17185session.resolveProxy()
#17222session.setProxy()
#17222shell.openExternal()
#16176()
#15855()
#15855webContents.hasServiceWorker()
#16535webContents.printToPDF()
#16795webContents.savePage()
#16742webFrame.executeJavaScript()
#17312webFrame.executeJavaScriptInIsolatedWorld()
#17312webviewTag.executeJavaScript()
#17312win.capturePage()
#15743
Ces fonctions ont maintenant deux formes, synchrone et asynchrone basées sur Promise :
dialog.showMessageBox()
/dialog.showMessageBoxSync()
#17298dialog.showOpenDialog()
/dialog.showOpenDialogSync()
#16973dialog.showSaveDialog()
/dialog.showSaveDialogSync()
#17054
Changements API non rétro-compatible prévus (6.0)
API modifiée : win.setMenu(null)
est désormais win.removeMenu()
// Déprécié
win.setMenu(null)
// Remplacé par
win.removeMenu()
API modifiée : electron.screen
dans le processus de rendu doit être accédé via remote
// Déprécié
require('electron').screen
// Remplacé par
require('electron').remote.screen
API Changed: require()
ing node builtins in sandboxed renderers no longer implicitly loads the remote
version
// 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')
Déprécié : powerMonitor.querySystemIdleState
remplacé par powerMonitor.getSystemIdleState
// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)
Déprécié : powerMonitor.querySystemIdleTime
remplacé par powerMonitor.getSystemIdleTime
// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()
Déprécié : app.enableMixedSandbox()
n'est plus nécessaire
// Déprécié
app.enableMixedSandbox()
Le mode bac à sable mixte est désormais activé par défaut.
Déprécié : Tray.setHighlightMode
Sous macOS Catalina, notre ancienne implémentation de Tray est interrompue. Le substitut natif d'Apple ne prend pas en charge la modification du comportement de mise en évidence.
// Déprécié
tray.setHighlightMode(mode)
// L'API sera supprimée dans la v7.0 sans remplacement.
Changements majeurs prévus de l'API (5.0)
Default Changed: nodeIntegration
and webviewTag
default to false, contextIsolation
defaults to true
Les options suivantes de webPreferences
seront dépréciées en faveur de nouvelles valeurs par défaut listées ci-dessous.
Propriétés | Valeur par défaut dépréciée | Nouvelle valeur par défaut |
---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration si mis sinon true | false |
Exemple : Re-enabling the webviewTag
const w = new BrowserWindow({
webPreferences: {
webviewTag: true
}
})
Comportement modifié : nodeIntegration
dans les fenêtres enfants ouvertes via nativeWindowOpen
Les fenêtres enfants ouvertes avec l'option nativeWindowOpen
auront toujours Node.js integration désactivée, sauf si nodeIntegrationInSubFrames
est à true
.
API modifiée : l'enregistrement de schémas privilégiés doit maintenant être effectué avant que l'application ne soit prête
Renderer process APIs webFrame.registerURLSchemeAsPrivileged
and webFrame.registerURLSchemeAsBypassingCSP
as well as browser process API protocol.registerStandardSchemes
have been removed. A new API, protocol.registerSchemesAsPrivileged
has been added and should be used for registering custom schemes with the required privileges. Les schémas personnalisés doivent être enregistrés avant que l'application soit prête.
Déprécié : webFrame.setIsolatedWorld*
remplacé par 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 modifiée : webFrame.setSpellCheckProvider
prend désormais un rappel asynchrone
Le rappel spellCheck
est désormais asynchrone et le paramètre autoCorrectWord
a été supprimé.
// 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 modifiée : webContents.getZoomLevel
et webContents.getZoomFactor
sont désormais synchrones
webContents.getZoomLevel
et webContents.getZoomFactor
n'ont plus de callback en paramètre et retournent directement leurs valeur numérique.
// Déprécié:
webContents.getZoomLevel((level) => {
console.log(level)
})
// Remplacer par
const level = webContents.getZoomLevel()
console.log(level)
// Déprécié:
webContents.getZoomLevel((level) => {
console.log(factor)
})
// Remplacer par
const level = webContents.getZoomLevel()
console.log(factor)
Changements majeurs prévus de l'API (4.0)
La liste suivante inclut les modifications de rupture de l'API apportées dans Electron 4.0.
app.makeSingleInstance
// Deprecated
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})
app.releaseSingleInstance
// Déprécié
app.releaseSingleInstance()
// Remplacé par
app.releaseSingleInstanceLock()
app.getGPUInfo
app.getGPUInfo('complete')
// Now behaves the same with `basic` on macOS
app.getGPUInfo('basic')
win_delay_load_hook
Quand vous compilez des modules natifs sous Windows, la variable win_delay_load_hook
dans le fichier binding.gyp
doit être mise à vrai (qui l'est par défaut). Si cet accroche n'est pas présente, l'exécution du module natif échouera sur Windows, avec un message d'erreur comme Cannot find module
. Voir le Guide des modules natifs pour plus d'informations.
Changements majeurs prévus de l'API (3.0)
La liste suivante inclut les changements majeurs pour Electron 3.0.
app
// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()
// Deprecated
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property
BrowserWindow
// Déprécié
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// Remplacer par
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)
// Déprécié
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// fait quelque chose
}
})
// Remplacer par
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// fait quelque chose
}
})
clipboard
// Déprécié
clipboard.readRtf()
// Remplacé par
clipboard.readRTF()
// Déprécié
clipboard.writeRtf()
// Remplacé par
clipboard.writeRTF()
// Déprécié
clipboard.readHtml()
// Remplacé par
clipboard.readHTML()
// Déprécié
clipboard.writeHtml()
// Remplacé par
clipboard.writeHTML()
crashReporter
// Déprécié
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// Remplacé par
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})
nativeImage
// Déprécié
nativeImage.createFromBuffer(buffer, 1.0)
// Remplacé par
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})
processus (process)
// Déprécié
const info = process.getProcessMemoryInfo()
screen
// Déprécié
screen.getMenuBarHeight()
// Remplacé par
screen.getPrimaryDisplay().workArea
session
// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})
Tray
// Déprécié
tray.setHighlightMode(true)
// Remplacé par
tray.setHighlightMode('on')
// Déprécié
tray.setHighlightMode(false)
// Remplacé par
tray.setHighlightMode('off')
webContents
// Déprécié
webContents.openDevTools({ detach: true })
// Remplacé par
webContents.openDevTools({ mode: 'detach' })
// Supprimé
webContents.setSize(options)
// Il n'y a pas de remplacement prévu
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>
// Supprimé
webview.setAttribute('disableguestresize', '')
// There is no replacement for this API
// Supprimé
webview.setAttribute('guestinstance', instanceId)
// There is no replacement for this API
// Les écouteurs d'événements ne marchent plus sur les tags webview
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }
Node Headers URL
Il s’agit de l’URL spécifiée comme disturl
dans un fichier .npmrc
ou le flag --dist-url
en ligne de commande lors de la compilation des modules natifs de Node.
Déprécié : https://atom.io/download/atom-shell
Remplacé par : https://atom.io/download/electron
Changements majeurs prévus de l'API (2.0)
La liste suivant inclut les changements majeurs faits dans Electron 2.0.
BrowserWindow
// Déprécié
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Remplacer par
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)
menu
// Supprimé
menu.popup(browserWindow, 100, 200, 2)
// Remplacé par
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })
nativeImage
// Supprimé
nativeImage.toPng()
// Remplacé par
nativeImage.toPNG()
// Supprimé
nativeImage.toJpeg()
// Remplacé par
nativeImage.toJPEG()
processus (process)
process.versions.electron
etprocess.version.chrome
seront mis en lecture seule par souci de cohérence avec la propriétéprocess.versions
définie par Node.
webContents
// Supprimé
webContents.setZoomLevelLimits(1, 2)
// Remplacé par
webContents.setVisualZoomLevelLimits(1, 2)
webFrame
// Supprimé
webFrame.setZoomLevelLimits(1, 2)
// Remplacé par
webFrame.setVisualZoomLevelLimits(1, 2)
<webview>
// Supprimé
webview.setZoomLevelLimits(1, 2)
// Remplacé par
webview.setVisualZoomLevelLimits(1, 2)
Versions ARM dupliquées
Chaque version d'Electron contient deux versions ARM identiques avec des noms légèrement différents, comme electron-v1.7.3-linux-arm.zip
et electron-v1.7.3-linux-armv7l.zip
. Celui avec le préfixe v7l
a été ajouté pour clarifier aux utilisateurs quelle version ARM elle supporte, et supprimer les ambiguïtés des prochains paquets armv6l et arm64 qui pourraient être produites.
Le fichier sans le préfixe est toujours publié afin d'éviter de casser les installations qui pourraient l'utiliser. À partir de la 2.0, le fichier sans préfixe ne sera plus publié.