破壊的変更
破壊的変更については、ここで説明し、可能な限りJSコードに非推奨警告を追加します。少なくとも変更が行われるメジャーバージョン1つ前には。
破壊的変更の種類
このドキュメントでは、以下の規約を使用して破壊的変更を分類しています。
- APIの変更: 更新されていないコードが例外をスローすることが保証されるような方法でAPIが変更されました。
- 動作の変更: Electronの動作が変更されましたが、必ずしも例外がスローされるわけではありません。
- デフォルトの変更: 古いデフォルトに依存しているコードは、例外がスローされない場合でも、動作が中断される可能性があります。古い動作は、値を明示的に指定することで復元できます。
- 非推奨: APIが非推奨としてマークされました。APIは引き続き機能しますが、非推奨警告が発行され、将来のリリースで削除されます。
- 削除: APIまたは機能が削除され、Electronではもはやサポートされていません。
計画されている破壊的API変更 (33.0)
動作の変更: appのloginイベントのwebContentsプロパティ
respondToAuthRequestsFromMainProcessオプションを使用して作成されたユーティリティプロセスからのリクエストに対してイベントがトリガーされた場合、appのloginイベントのwebContentsプロパティはnullになります。
非推奨: systemPreferences.accessibilityDisplayShouldReduceTransparency
systemPreferences.accessibilityDisplayShouldReduceTransparencyプロパティは、同一の情報を提供し、クロスプラットフォームで動作する新しいnativeTheme.prefersReducedTransparencyに置き換えられました。
// Deprecated
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency
// Replace with:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency
計画されている破壊的API変更 (32.0)
削除: File.path
WebのFileオブジェクトの非標準的なpathプロパティは、Electronの初期バージョンで、レンダラーですべてを行うことがより一般的だったときに、ネイティブファイルの処理を容易にするための便利なメソッドとして追加されました。しかし、これは標準からの逸脱を表しており、レンダラーですべてを行うことがより一般的だったときに、ネイティブファイルの処理を容易にするための便利なメソッドとして追加されました。Electron 32.0以降、webUtils.getPathForFileメソッドに置き換えられました。
// Before (renderer)
const file = document.querySelector('input[type=file]')
alert(`Uploaded file path was: ${file.path}`)
// After (renderer)
const file = document.querySelector('input[type=file]')
electron.showFilePath(file)
// (preload)
const { contextBridge, webUtils } = require('electron')
contextBridge.exposeInMainWorld('electron', {
showFilePath (file) {
// It's best not to expose the full file path to the web content if
// possible.
const path = webUtils.getPathForFile(file)
alert(`Uploaded file path was: ${path}`)
}
})
非推奨: WebContentsのclearHistory、canGoBack、goBack、canGoForward、goForward、goToIndex、canGoToOffset、goToOffset
ナビゲーション関連のAPIは非推奨になりました。
これらのAPIは、WebContentsのnavigationHistoryプロパティに移動され、ナビゲーション履歴の管理のためのより構造化され、直感的なインターフェースを提供します。
// Deprecated
win.webContents.clearHistory()
win.webContents.canGoBack()
win.webContents.goBack()
win.webContents.canGoForward()
win.webContents.goForward()
win.webContents.goToIndex(index)
win.webContents.canGoToOffset()
win.webContents.goToOffset(index)
// Replace with
win.webContents.navigationHistory.clear()
win.webContents.navigationHistory.canGoBack()
win.webContents.navigationHistory.goBack()
win.webContents.navigationHistory.canGoForward()
win.webContents.navigationHistory.goForward()
win.webContents.navigationHistory.canGoToOffset()
win.webContents.navigationHistory.goToOffset(index)
計画されている破壊的API変更 (31.0)
削除: WebSQLサポート
ChromiumはアップストリームでWebSQLのサポートを削除し、Androidのみに移行しました。詳細については、Chromiumの削除に関する議論を参照してください。
動作の変更: nativeImage.toDataURLはPNGの色空間を保持します
PNGデコーダーの実装が変更され、色空間データが保持されるようになりました。この関数から返されるエンコードされたデータは、これと一致するようになりました。
詳細については、crbug.com/332584706を参照してください。
動作の変更: window.flashFrame(bool)はmacOSでドックアイコンを連続的に点滅させます
これにより、動作がWindowsとLinuxと同一になります。以前の動作: 最初のflashFrame(true)はドックアイコンを一度だけバウンスさせます（NSInformationalRequestレベルを使用）、flashFrame(false)は何もしません。新しい動作: flashFrame(false)が呼び出されるまで連続的に点滅します。NSCriticalRequestレベルを使用します。ドックアイコンを一度だけバウンスさせるためにNSInformationalRequestを明示的に使用するには、dock.bounce('informational')を使用できます。
計画されている破壊的API変更 (30.0)
動作の変更: クロスオリジンのiframeは、機能にアクセスするためにPermission Policyを使用するようになりました
クロスオリジンのiframeは、アクセスするために、指定されたiframeで使用可能な機能をallow属性で指定する必要があります。
詳細については、ドキュメントを参照してください。
削除: --disable-color-correct-renderingスイッチ
このスイッチは正式に文書化されていませんでしたが、削除はここで言及されています。Chromium自体は色空間をより適切にサポートするようになったため、このフラグは必要ありません。
動作の変更: macOSでのBrowserView.setAutoResizeの動作
Electron 30では、BrowserViewは新しいWebContentsView APIのラッパーになりました。
以前は、BrowserView APIのsetAutoResize関数は、macOSではautoresizingによって、WindowsとLinuxではカスタムアルゴリズムによってサポートされていました。BrowserViewをウィンドウ全体に合わせるなど、単純なユースケースでは、これら2つのアプローチの動作は同一でした。しかし、より高度なケースでは、カスタムのリサイズアルゴリズムはmacOSのautoresizing APIの動作と完全に一致しなかったため、BrowserViewはmacOSと他のプラットフォームで異なるサイズに変更されました。autoresizing動作は、すべてのプラットフォームで標準化されました。
アプリでBrowserView.setAutoResizeを使用して、BrowserViewをウィンドウ全体に合わせる以外のより複雑な処理を行う場合、macOSでのこの動作の違いを処理するためのカスタムロジックがすでに存在している可能性があります。その場合、autoresizing動作が整合しているため、Electron 30ではそのロジックは不要になります。
非推奨: BrowserView
BrowserViewクラスは非推奨となり、新しいWebContentsViewクラスに置き換えられました。
BrowserWindowのBrowserView関連メソッドも非推奨になりました。
BrowserWindow.fromBrowserView(browserView)
win.setBrowserView(browserView)
win.getBrowserView()
win.addBrowserView(browserView)
win.removeBrowserView(browserView)
win.setTopBrowserView(browserView)
win.getBrowserViews()
削除: WebContentsのcontext-menuイベントのparams.inputFormTypeプロパティ
WebContentsのcontext-menuイベントのparamsオブジェクトのinputFormTypeプロパティは削除されました。代わりに新しいformControlTypeプロパティを使用してください。
削除: process.getIOCounters()
Chromiumはこの情報のアクセスを削除しました。
計画されている破壊的API変更 (29.0)
動作の変更: ipcRendererはcontextBridge経由で送信できなくなりました
ipcRenderer モジュール全体をオブジェクトとしてcontextBridge経由で送信しようとすると、ブリッジの受信側では空のオブジェクトになります。この変更は、セキュリティ上の問題を解消/軽減するために行われました。ipcRendererまたはそのメソッドをブリッジ経由で直接公開しないでください。代わりに、下記のような安全なラッパーを用意してください。
contextBridge.exposeInMainWorld('app', {
onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})
削除済み: appのrenderer-process-crashedイベント
appのrenderer-process-crashedイベントは削除されました。代わりに新しいrender-process-goneイベントを使用してください。
// Removed
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
削除済み: WebContentsと<webview>のcrashedイベント
WebContentsと<webview>のcrashedイベントは削除されました。代わりに新しいrender-process-goneイベントを使用してください。
// Removed
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })
// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
削除済み: appのgpu-process-crashedイベント
appのgpu-process-crashedイベントは削除されました。代わりに新しいchild-process-goneイベントを使用してください。
// Removed
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
計画されている破壊的API変更 (28.0)
動作変更: WebContents.backgroundThrottlingをfalseに設定すると、ホストBrowserWindow内のすべてのWebContentsに影響します
WebContents.backgroundThrottlingをfalseに設定すると、表示されているすべてのWebContentsについて、BrowserWindowのフレームのスロットリングが無効になります。
削除済み: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position)は削除されました。代わりにBrowserWindow.setWindowButtonPosition(position) APIを使用してください。これは、位置をシステムデフォルトにリセットするためにnullを受け入れます。
// Removed in Electron 28
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })
// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)
削除済み: BrowserWindow.getTrafficLightPosition()
BrowserWindow.getTrafficLightPosition()は削除されました。代わりにBrowserWindow.getWindowButtonPosition() APIを使用してください。これは、カスタム位置がない場合にnullを返します。
// Removed in Electron 28
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
// No custom position.
}
削除済み: ipcRenderer.sendTo()
ipcRenderer.sendTo() APIは削除されました。レンダラー間でMessageChannelをセットアップすることによって置き換える必要があります。
IpcRendererEventのsenderIdプロパティとsenderIsMainFrameプロパティも削除されました。
削除済み: app.runningUnderRosettaTranslation
app.runningUnderRosettaTranslationプロパティは削除されました。代わりにapp.runningUnderARM64Translationを使用してください。
// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
非推奨: appのrenderer-process-crashedイベント
appのrenderer-process-crashedイベントは非推奨となりました。代わりに新しいrender-process-goneイベントを使用してください。
// Deprecated
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
非推奨: WebContentsのcontext-menuのparams.inputFormTypeプロパティ
WebContentsのcontext-menuイベントのパラメーターオブジェクトのinputFormTypeプロパティは非推奨となりました。代わりに新しいformControlTypeプロパティを使用してください。
非推奨: WebContentsと<webview>のcrashedイベント
WebContentsと<webview>のcrashedイベントは非推奨となりました。代わりに新しいrender-process-goneイベントを使用してください。
// Deprecated
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })
// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })
非推奨: appのgpu-process-crashedイベント
appのgpu-process-crashedイベントは非推奨となりました。代わりに新しいchild-process-goneイベントを使用してください。
// Deprecated
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })
// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })
計画されている破壊的API変更 (27.0)
削除済み: macOS 10.13 / 10.14サポート
macOS 10.13 (High Sierra)とmacOS 10.14 (Mojave)は、Chromiumではサポートされなくなりました。
以前のバージョンのElectronではこれらのオペレーティングシステムで動作し続けますが、Electron v27.0.0以降を実行するには、macOS 10.15 (Catalina)以降が必要です。
非推奨: ipcRenderer.sendTo()
ipcRenderer.sendTo() APIは非推奨となりました。レンダラー間でMessageChannelをセットアップすることによって置き換える必要があります。
IpcRendererEventのsenderIdプロパティとsenderIsMainFrameプロパティも非推奨となりました。
削除済み: systemPreferencesの色スキームイベント
次のsystemPreferencesイベントは削除されました。
inverted-color-scheme-changedhigh-contrast-color-scheme-changed
代わりにnativeThemeモジュールの新しいupdatedイベントを使用してください。
// Removed
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replace with
nativeTheme.on('updated', () => { /* ... */ })
削除済み: macOSの一部のwindow.setVibrancyオプション
次のvibrancyオプションは削除されました。
- 'light'
- 'medium-light'
- 'dark'
- 'ultra-dark'
- 'appearance-based'
これらは以前非推奨とされており、Appleによって10.15で削除されました。
削除済み: webContents.getPrinters
webContents.getPrintersメソッドは削除されました。代わりにwebContents.getPrintersAsyncを使用してください。
const w = new BrowserWindow({ show: false })
// Removed
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
削除済み: systemPreferences.{get,set}AppLevelAppearanceとsystemPreferences.appLevelAppearance
systemPreferences.getAppLevelAppearanceメソッドとsystemPreferences.setAppLevelAppearanceメソッド、およびsystemPreferences.appLevelAppearanceプロパティは削除されました。代わりにnativeThemeモジュールを使用してください。
// Removed
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Removed
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
削除済み: systemPreferences.getColorのalternate-selected-control-text値
systemPreferences.getColorのalternate-selected-control-text値は削除されました。代わりにselected-content-backgroundを使用してください。
// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
計画されている破壊的API変更 (26.0)
非推奨: webContents.getPrinters
webContents.getPrintersメソッドは非推奨となりました。代わりにwebContents.getPrintersAsyncを使用してください。
const w = new BrowserWindow({ show: false })
// Deprecated
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
console.log(printers)
})
非推奨: systemPreferences.{get,set}AppLevelAppearanceとsystemPreferences.appLevelAppearance
systemPreferences.getAppLevelAppearanceメソッドとsystemPreferences.setAppLevelAppearanceメソッド、およびsystemPreferences.appLevelAppearanceプロパティは非推奨となりました。代わりにnativeThemeモジュールを使用してください。
// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors
// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
非推奨: systemPreferences.getColorのalternate-selected-control-text値
systemPreferences.getColorのalternate-selected-control-text値は非推奨となりました。代わりにselected-content-backgroundを使用してください。
// Deprecated
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')
計画されている破壊的API変更 (25.0)
非推奨: protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocolとprotocol.isProtocol{Registered,Intercepted}
protocol.register*Protocolメソッドとprotocol.intercept*Protocolメソッドはprotocol.handleに置き換えられました。
新しいメソッドは、新しいプロトコルを登録するか、既存のプロトコルをインターセプトするかを選択でき、応答は任意の型にすることができます。
// Deprecated in Electron 25
protocol.registerBufferProtocol('some-protocol', () => {
callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})
// Replace with
protocol.handle('some-protocol', () => {
return new Response(
Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
{ headers: { 'content-type': 'text/html' } }
)
})
// Deprecated in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
callback({ url: 'https://electron.dokyumento.jp' })
})
// Replace with
protocol.handle('some-protocol', () => {
return net.fetch('https://electron.dokyumento.jp')
})
// Deprecated in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
callback({ filePath: '/path/to/my/file' })
})
// Replace with
protocol.handle('some-protocol', () => {
return net.fetch('file:///path/to/my/file')
})
非推奨: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position) は非推奨となりました。代わりに BrowserWindow.setWindowButtonPosition(position) API を使用してください。このAPIは、位置をシステムデフォルトにリセットするために { x: 0, y: 0 } の代わりに null を受け入れます。
// Deprecated in Electron 25
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })
// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)
非推奨: BrowserWindow.getTrafficLightPosition()
BrowserWindow.getTrafficLightPosition() は非推奨となりました。代わりに BrowserWindow.getWindowButtonPosition() API を使用してください。これは、カスタム位置がない場合に { x: 0, y: 0 } の代わりに null を返します。
// Deprecated in Electron 25
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
// No custom position.
}
計画されている破壊的なAPI変更 (24.0)
API変更: nativeImage.createThumbnailFromPath(path, size)
maxSize パラメータは、作成されるサムネイルのサイズを表す size に変更されました。以前は、WindowsではmaxSizeよりも小さい場合に画像を拡大せず、macOSでは常にサイズをmaxSizeに設定していました。現在はプラットフォーム間で動作が統一されました。
動作の更新
// a 128x128 image.
const imagePath = path.join('path', 'to', 'capybara.png')
// Scaling up a smaller image.
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
console.log(result.getSize()) // { width: 256, height: 256 }
})
// Scaling down a larger image.
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
console.log(result.getSize()) // { width: 64, height: 64 }
})
以前の動作 (Windows)
// a 128x128 image
const imagePath = path.join('path', 'to', 'capybara.png')
const size = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, size).then(result => {
console.log(result.getSize()) // { width: 128, height: 128 }
})
計画されている破壊的なAPI変更 (23.0)
動作変更: macOSでのドラッグ可能な領域
ドラッグ可能な領域の実装（CSSプロパティ-webkit-app-region: dragを使用）がmacOSで変更され、WindowsおよびLinuxと一致するようになりました。以前は、-webkit-app-region: no-dragの領域が-webkit-app-region: dragの領域と重なっている場合、CSSのレイヤーに関わらず、macOSでは常にno-drag領域が優先されていました。つまり、drag領域がno-drag領域の上に存在する場合、無視されていました。Electron 23以降、no-drag領域の上にあるdrag領域は、正しくドラッグ可能になります。
さらに、以前はcustomButtonsOnHover BrowserWindowプロパティによって、-webkit-app-region CSSプロパティを無視するドラッグ可能な領域が作成されていました。これは修正されました（詳細は#37210を参照）。
その結果、macOSでフレームレスウィンドウとドラッグ可能な領域を使用するアプリの場合、Electron 23でドラッグ可能な領域が変更される可能性があります。
削除: Windows 7 / 8 / 8.1サポート
Windows 7、Windows 8、およびWindows 8.1はサポートされなくなりました。Electronは計画されているChromiumの非推奨ポリシーに従っており、Chromium 109以降でWindows 7のサポートが廃止されます。
古いバージョンのElectronはこれらのオペレーティングシステムで引き続き実行されますが、Electron v23.0.0以降を実行するにはWindows 10以降が必要です。
削除: BrowserWindow scroll-touch-* イベント
BrowserWindowの非推奨となったscroll-touch-begin、scroll-touch-end、およびscroll-touch-edgeイベントは削除されました。代わりに、WebContentsで新しく利用可能なinput-eventイベントを使用してください。
// Removed in Electron 23.0
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)
// Replace with
win.webContents.on('input-event', (_, event) => {
if (event.type === 'gestureScrollBegin') {
scrollTouchBegin()
} else if (event.type === 'gestureScrollUpdate') {
scrollTouchEdge()
} else if (event.type === 'gestureScrollEnd') {
scrollTouchEnd()
}
})
削除: webContents.incrementCapturerCount(stayHidden, stayAwake)
webContents.incrementCapturerCount(stayHidden, stayAwake)関数は削除されました。ページキャプチャが完了すると、webContents.capturePageによって自動的に処理されるようになりました。
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
削除: webContents.decrementCapturerCount(stayHidden, stayAwake)
webContents.decrementCapturerCount(stayHidden, stayAwake)関数は削除されました。ページキャプチャが完了すると、webContents.capturePageによって自動的に処理されるようになりました。
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
計画されている破壊的なAPI変更 (22.0)
非推奨: webContents.incrementCapturerCount(stayHidden, stayAwake)
webContents.incrementCapturerCount(stayHidden, stayAwake)は非推奨となりました。ページキャプチャが完了すると、webContents.capturePageによって自動的に処理されるようになりました。
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
非推奨: webContents.decrementCapturerCount(stayHidden, stayAwake)
webContents.decrementCapturerCount(stayHidden, stayAwake)は非推奨となりました。ページキャプチャが完了すると、webContents.capturePageによって自動的に処理されるようになりました。
const w = new BrowserWindow({ show: false })
// Removed in Electron 23
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
console.log(image.toDataURL())
w.webContents.decrementCapturerCount()
})
// Replace with
w.capturePage().then(image => {
console.log(image.toDataURL())
})
削除: WebContents new-window イベント
WebContentsのnew-windowイベントは削除されました。webContents.setWindowOpenHandler()に置き換えられました。
// Removed in Electron 22
webContents.on('new-window', (event) => {
event.preventDefault()
})
// Replace with
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})
削除: <webview> new-window イベント
<webview>のnew-windowイベントは削除されました。直接的な代替手段はありません。
// Removed in Electron 22
webview.addEventListener('new-window', (event) => {})
// Replace with
// main.js
mainWindow.webContents.on('did-attach-webview', (event, wc) => {
wc.setWindowOpenHandler((details) => {
mainWindow.webContents.send('webview-new-window', wc.id, details)
return { action: 'deny' }
})
})
// preload.js
const { ipcRenderer } = require('electron')
ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
console.log('webview-new-window', webContentsId, details)
document.getElementById('webview').dispatchEvent(new Event('new-window'))
})
// renderer.js
document.getElementById('webview').addEventListener('new-window', () => {
console.log('got new-window event')
})
非推奨: BrowserWindow scroll-touch-* イベント
BrowserWindowのscroll-touch-begin、scroll-touch-end、およびscroll-touch-edgeイベントは非推奨となりました。代わりに、WebContentsで新しく利用可能なinput-eventイベントを使用してください。
// Deprecated
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)
// Replace with
win.webContents.on('input-event', (_, event) => {
if (event.type === 'gestureScrollBegin') {
scrollTouchBegin()
} else if (event.type === 'gestureScrollUpdate') {
scrollTouchEdge()
} else if (event.type === 'gestureScrollEnd') {
scrollTouchEnd()
}
})
計画されている破壊的なAPI変更 (21.0)
動作変更: V8メモリケージが有効化
V8メモリケージが有効化されました。これにより、ArrayBufferまたはBufferを使用して非V8メモリをラップするネイティブモジュールに影響があります。詳細は、V8メモリケージに関するブログ記事を参照してください。
API変更: webContents.printToPDF()
webContents.printToPDF()は、Chrome DevToolsプロトコルのPage.printToPDFに準拠するように変更されました。これは、以前の実装が維持できなくなり、バグが多発していたための上流の変更に対応するためです。
引数の変更
pageRanges
削除された引数
printSelectionOnlymarginsTypeheaderFooterscaleFactor
追加された引数
headerTemplatefooterTemplatedisplayHeaderFootermarginsscalepreferCSSPageSize
// Main process
const { webContents } = require('electron')
webContents.printToPDF({
landscape: true,
displayHeaderFooter: true,
printBackground: true,
scale: 2,
pageSize: 'Ledger',
margins: {
top: 2,
bottom: 2,
left: 2,
right: 2
},
pageRanges: '1-5, 8, 11-13',
headerTemplate: '<h1>Title</h1>',
footerTemplate: '<div><span class="pageNumber"></span></div>',
preferCSSPageSize: true
}).then(data => {
fs.writeFile(pdfPath, data, (error) => {
if (error) throw error
console.log(`Wrote PDF successfully to ${pdfPath}`)
})
}).catch(error => {
console.log(`Failed to write PDF to ${pdfPath}: `, error)
})
計画されている破壊的なAPI変更 (20.0)
削除: macOS 10.11 / 10.12サポート
macOS 10.11 (El Capitan)とmacOS 10.12 (Sierra)はChromiumでサポートされなくなりました。
古いバージョンのElectronはこれらのオペレーティングシステムで引き続き実行されますが、Electron v20.0.0以降を実行するにはmacOS 10.13 (High Sierra)以降が必要です。
デフォルトの変更: nodeIntegration: trueを指定していないレンダラーはデフォルトでサンドボックス化
以前は、プリロードスクリプトを指定したレンダラーはデフォルトでサンドボックス化されていませんでした。これは、デフォルトでプリロードスクリプトがNode.jsにアクセスできることを意味していました。Electron 20では、このデフォルトが変更されました。Electron 20以降、nodeIntegration: trueまたはsandbox: falseが指定されていない限り、レンダラーはデフォルトでサンドボックス化されます。
プリロードスクリプトがNodeに依存しない場合、何もする必要はありません。プリロードスクリプトがNodeに依存する場合は、レンダラーからNodeの使用を削除するか、関連するレンダラーに対してsandbox: falseを明示的に指定してください。
削除: LinuxでのskipTaskbar
X11では、skipTaskbarは_NET_WM_STATE_SKIP_TASKBARメッセージをX11ウィンドウマネージャーに送信します。Waylandには直接的な同等物はなく、既知の回避策には受け入れられないトレードオフがあります（例：GNOMEのWindow.is_skip_taskbarは安全でないモードが必要です）。そのため、ElectronはLinuxでこの機能をサポートできません。
API変更: session.setDevicePermissionHandler(handler)
session.setDevicePermissionHandler(handler)で使用されるハンドラーの引数が変更されました。このハンドラーには、フレームWebFrameMainが渡されなくなりましたが、代わりにデバイスの権限を確認しているオリジンであるoriginが渡されます。
計画されている破壊的なAPI変更 (19.0)
削除: IA32 Linuxバイナリ
これは、Chromium 102.0.4999.0がIA32 Linuxのサポートを削除した結果です。これにより、IA32 Linuxのサポートの削除が完了しました。
計画されている破壊的なAPI変更 (18.0)
削除済み: nativeWindowOpen
Electron 15 より前は、window.open はデフォルトで BrowserWindowProxy を使用してシムされていました。これは、window.open('about:blank') が同期的にスクリプト可能な子ウィンドウを開くのに機能しないことなど、いくつかの非互換性がありました。Electron 15 以降、nativeWindowOpen はデフォルトで有効になっています。
詳細は、Electron のwindow.open のドキュメントを参照してください。
計画されている破壊的 API 変更 (17.0)
削除済み: レンダラー内の desktopCapturer.getSources
desktopCapturer.getSources API は、メインプロセスでのみ使用可能になりました。これは、Electron アプリのデフォルトのセキュリティを向上させるために変更されました。
この機能が必要な場合は、次のように置き換えることができます。
// 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)
}
ただし、レンダラーに返される情報をさらに制限することを検討する必要があります。たとえば、ユーザーにソースセレクターを表示し、選択されたソースのみを返すなどです。
非推奨: nativeWindowOpen
Electron 15 より前は、window.open はデフォルトで BrowserWindowProxy を使用してシムされていました。これは、window.open('about:blank') が同期的にスクリプト可能な子ウィンドウを開くのに機能しないことなど、いくつかの非互換性がありました。Electron 15 以降、nativeWindowOpen はデフォルトで有効になっています。
詳細は、Electron のwindow.open のドキュメントを参照してください。
計画されている破壊的 API 変更 (16.0)
動作変更: Linux での crashReporter の実装が Crashpad に切り替えられました
Linux での crashReporter API の基盤となる実装が Breakpad から Crashpad に変更され、Windows と Mac との整合性が取れるようになりました。この結果、子プロセスは自動的に監視されるようになり、Node 子プロセスで process.crashReporter.start を呼び出す必要がなくなりました（2 番目の Crashpad レポーターインスタンスが起動するため、推奨されません）。
Linux での注釈の報告方法にも微妙な変更があります。具体的には、長い値が __1、__2 などで追加された注釈間に分割されなくなり、代わりに新しい（より長い）注釈値の制限で切り捨てられるようになりました。
非推奨: レンダラー内の desktopCapturer.getSources
レンダラー内での desktopCapturer.getSources API の使用は非推奨となり、削除される予定です。この変更により、Electron アプリのデフォルトのセキュリティが向上します。
アプリでこの API を置き換える方法については、ここを参照してください。
計画されている破壊的 API 変更 (15.0)
デフォルトの変更: nativeWindowOpen のデフォルトが true になりました
Electron 15 より前は、window.open はデフォルトで BrowserWindowProxy を使用してシムされていました。これは、window.open('about:blank') が同期的にスクリプト可能な子ウィンドウを開くのに機能しないことなど、いくつかの非互換性がありました。nativeWindowOpen は実験的ではなくなり、現在はデフォルトになっています。
詳細は、Electron のwindow.open のドキュメントを参照してください。
非推奨: app.runningUnderRosettaTranslation
app.runningUnderRosettaTranslation プロパティは非推奨になりました。代わりに app.runningUnderARM64Translation を使用してください。
// Deprecated
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
計画されている破壊的 API 変更 (14.0)
削除済み: 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()
削除済み: app.allowRendererProcessReuse
セキュリティ、パフォーマンス、保守性の向上のため、Chromium のプロセスモデルにより近づける計画の一環として、app.allowRendererProcessReuse プロパティは削除されます。
詳細については、#18397 を参照してください。
削除済み: ブラウザーウィンドウのアフィニティ
新しい BrowserWindow を構築する際の affinity オプションは、セキュリティ、パフォーマンス、保守性の向上のため、Chromium のプロセスモデルにより近づける計画の一環として削除されます。
詳細については、#18397 を参照してください。
API 変更: window.open()
オプションパラメーター frameName は、ウィンドウのタイトルを設定しなくなりました。これは、対応するパラメーター windowName の下にネイティブドキュメントで記述されている仕様に従うようになりました。
このパラメーターを使用してウィンドウのタイトルを設定していた場合は、代わりにwin.setTitle(title) を使用できます。
削除済み: worldSafeExecuteJavaScript
Electron 14 では、worldSafeExecuteJavaScript が削除されます。代替手段はありません。コードがこのプロパティが有効になっている状態で動作することを確認してください。Electron 12 以降、デフォルトで有効になっています。
webFrame.executeJavaScript または webFrame.executeJavaScriptInIsolatedWorld のいずれかを使用している場合、この変更の影響を受けます。これらのメソッドは同じ値渡しセマンティクスを使用するため、これらのメソッドによって返される値がContext Bridge API でサポートされていることを確認する必要があります。
削除済み: 親ウィンドウから継承する BrowserWindowConstructorOptions
Electron 14 より前、window.open で開かれたウィンドウは、transparent や resizable などの BrowserWindow コンストラクターオプションを親ウィンドウから継承していました。Electron 14 以降、この動作は削除され、ウィンドウは親から BrowserWindow コンストラクターオプションを継承しなくなります。
代わりに、setWindowOpenHandler を使用して新しいウィンドウのオプションを明示的に設定してください。
webContents.setWindowOpenHandler((details) => {
return {
action: 'allow',
overrideBrowserWindowOptions: {
// ...
}
}
})
削除済み: additionalFeatures
WebContents の new-window イベントと did-create-window イベントの非推奨の additionalFeatures プロパティが削除されました。new-window は位置引数を使用するため、引数は存在しますが、常に空の配列 [] になります。（ただし、new-window イベント自体は非推奨であり、setWindowOpenHandler に置き換えられています。）ウィンドウ機能のベアナキーは、オプションオブジェクトで値 true を持つキーとして表示されるようになります。
// 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 になる可能性があるため、それ以上は依存できません。
// Old code
session.setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
return true
}
return false
})
// Replace with
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
return true
}
return false
})
削除済み: shell.moveItemToTrash()
非推奨の同期 API shell.moveItemToTrash() が削除されました。代わりに非同期の shell.trashItem() を使用してください。
// Removed in Electron 13
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)
削除済み: BrowserWindow 拡張 API
非推奨の拡張 API が削除されました。
BrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()
代わりに session API を使用してください。
ses.loadExtension(path)ses.removeExtension(extension_id)ses.getAllExtensions()
// Removed in Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)
// Removed in Electron 13
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)
// Removed in Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()
削除済み: systemPreferences のメソッド
次の systemPreferences メソッドは非推奨になりました。
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()
代わりに次の nativeTheme プロパティを使用してください。
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.shouldUseHighContrastColors
// Removed in Electron 13
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors
// Removed in Electron 13
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme
// Removed in Electron 13
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors
非推奨: WebContents の new-window イベント
WebContents の new-window イベントは非推奨になりました。webContents.setWindowOpenHandler() に置き換えられました。
// Deprecated in Electron 13
webContents.on('new-window', (event) => {
event.preventDefault()
})
// Replace with
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})
計画されている破壊的 API 変更 (12.0)
削除済み: Pepper Flash のサポート
Chromium は Flash のサポートを削除したため、それに従う必要があります。詳細については、Chromium のFlash ロードマップを参照してください。
デフォルトの変更: worldSafeExecuteJavaScript のデフォルトが true になりました
Electron 12 では、worldSafeExecuteJavaScript がデフォルトで有効になります。以前の動作に戻すには、WebPreferences に worldSafeExecuteJavaScript: false を指定する必要があります。ただし、このオプションを false に設定することは安全ではありません。
このオプションは Electron 14 で削除されるため、デフォルト値をサポートするようにコードを移行してください。
デフォルト値の変更: contextIsolation のデフォルト値が true になりました
Electron 12 では、contextIsolation がデフォルトで有効になります。以前の動作に戻すには、WebPreferences に contextIsolation: false を指定する必要があります。
アプリケーションのセキュリティのために、contextIsolation を有効にすることを推奨します。
別の影響として、nodeIntegration が true であり、contextIsolation が false でない限り、レンダラープロセスで require() を使用することはできません。
詳細については、https://github.com/electron/electron/issues/23506 を参照してください。
削除されたAPI: crashReporter.getCrashesDirectory()
crashReporter.getCrashesDirectory メソッドは削除されました。app.getPath('crashDumps') に置き換えてください。
// Removed in Electron 12
crashReporter.getCrashesDirectory()
// Replace with
app.getPath('crashDumps')
削除されたAPI: レンダラープロセス内の crashReporter メソッド
以下の crashReporter メソッドは、レンダラープロセスでは使用できなくなりました。
crashReporter.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectory
これらはメインプロセスからのみ呼び出す必要があります。
詳細については、#23265 を参照してください。
デフォルト値の変更: crashReporter.start({ compress: true })
crashReporter.start の compress オプションのデフォルト値が 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変更 (11.0)
削除されたAPI: BrowserView.{destroy, fromId, fromWebContents, getAllViews} および BrowserView の id プロパティ
実験的なAPIである BrowserView.{destroy, fromId, fromWebContents, getAllViews} は削除されました。さらに、BrowserView の id プロパティも削除されました。
詳細については、#23578 を参照してください。
計画されている破壊的なAPI変更 (10.0)
非推奨: crashReporter.start() への companyName 引数
以前は必須だった crashReporter.start() への companyName 引数は、現在はオプションになり、さらに非推奨となりました。非推奨ではない方法で同じ動作を得るには、globalExtra に companyName の値を渡すことができます。
// 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.startcrashReporter.getLastCrashReportcrashReporter.getUploadedReportscrashReporter.getUploadToServercrashReporter.setUploadToServercrashReporter.getCrashesDirectory
レンダラー内の crashReporter モジュールに残っている非推奨ではないメソッドは、addExtraParameter、removeExtraParameter、および getParameters のみです。
上記のすべてのメソッドは、メインプロセスから呼び出される場合、非推奨ではありません。
詳細については、#23265 を参照してください。
非推奨: crashReporter.start({ compress: false })
crashReporter.start で { compress: false } を設定することは非推奨です。ほとんどすべてのクラッシュインジェクションサーバーは gzip 圧縮をサポートしています。このオプションは将来の Electron のバージョンで削除されます。
デフォルト値の変更: enableRemoteModule のデフォルト値が false になりました
Electron 9 では、enableRemoteModule WebPreferences オプションを介して明示的に有効にせずに remote モジュールを使用すると、警告が出力されるようになりました。Electron 10 では、remote モジュールはデフォルトで無効になっています。remote モジュールを使用するには、WebPreferences に enableRemoteModule: true を指定する必要があります。
const w = new BrowserWindow({
webPreferences: {
enableRemoteModule: true
}
})
remote モジュールから離れることを推奨します。
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)
デフォルト値の変更: レンダラープロセスでのコンテキスト非依存ネイティブモジュールの読み込みがデフォルトで無効になりました
Electron 9 以降、レンダラープロセスでのコンテキスト非依存ネイティブモジュールの読み込みは許可されません。これは、Electron のプロジェクトとしてのセキュリティ、パフォーマンス、保守性を向上させるためです。
これが影響を与える場合は、一時的に app.allowRendererProcessReuse を false に設定して、以前の動作に戻すことができます。このフラグは Electron 11 までしかオプションではないため、ネイティブモジュールをコンテキスト依存するように更新する計画を立ててください。
詳細については、#18397 を参照してください。
非推奨: BrowserWindow 拡張API
以下の拡張APIは非推奨となりました。
BrowserWindow.addExtension(path)BrowserWindow.addDevToolsExtension(path)BrowserWindow.removeExtension(name)BrowserWindow.removeDevToolsExtension(name)BrowserWindow.getExtensions()BrowserWindow.getDevToolsExtensions()
代わりに session 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()
削除されたAPI: <webview>.getWebContents()
Electron 8.0 で非推奨となったこのAPIは、削除されました。
// Removed in Electron 9.0
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())
削除されたAPI: webFrame.setLayoutZoomLevelLimits()
Chromium はレイアウトズームレベル制限の変更のサポートを削除しており、Electron がそれを維持することはできません。この関数は Electron 8.x で非推奨となり、Electron 9.x で削除されました。レイアウトズームレベル制限は、ここに定義されているように、最小 0.25、最大 5.0 に固定されました。
動作の変更: IPC を介して非 JS オブジェクトを送信すると、例外がスローされるようになりました
Electron 8.0 では、IPC は構造化クローンアルゴリズムを使用するように変更され、パフォーマンスが大幅に向上しました。移行を容易にするために、古い IPC シリアル化アルゴリズムが保持され、構造化クローンでシリアル化できない一部のオブジェクトに使用されました。特に、DOM オブジェクト（例：Element、Location、DOMMatrix）、C++ クラスによってバックアップされた Node.js オブジェクト（例：process.env、Stream の一部のメンバー）、および C++ クラスによってバックアップされた Electron オブジェクト（例：WebContents、BrowserWindow、WebFrame）は、構造化クローンでシリアル化できません。古いアルゴリズムが呼び出されるたびに、非推奨警告が出力されました。
Electron 9.0 では、古いシリアル化アルゴリズムが削除され、そのようなシリアル化不可能なオブジェクトを送信すると、「オブジェクトを複製できませんでした」というエラーがスローされるようになりました。
APIの変更: shell.openItem は shell.openPath になりました
shell.openItem API は、非同期 API である shell.openPath API に置き換えられました。元の API の提案と理由については、こちらを参照してください。
計画されている破壊的 API 変更 (8.0)
動作変更: IPC を介して送信される値は、Structured Clone Algorithm でシリアル化されるようになりました
IPC（ipcRenderer.send、ipcRenderer.sendSync、WebContents.send、および関連メソッド）を介して送信されるオブジェクトのシリアル化に使用されるアルゴリズムが、カスタムアルゴリズムから V8 の組み込みStructured Clone Algorithmに変更されました。これは、postMessageのメッセージのシリアル化に使用されるアルゴリズムと同じです。これにより、大規模なメッセージの処理速度が 2 倍に向上しますが、動作にいくつかの破壊的変更がもたらされます。
- 関数、Promise、WeakMap、WeakSet、またはこれらの値を含むオブジェクトを IPC を介して送信すると、関数を
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に変換される代わりに、正しくシリアル化されるようになりました。- 疎な配列は、
nullを含む密な配列に変換される代わりに、そのままシリアル化されます。 Dateオブジェクトは、ISO文字列表現に変換される代わりに、Dateオブジェクトとして転送されます。- 型付き配列（
Uint8Array、Uint16Array、Uint32Arrayなど）は、Node.jsのBufferに変換される代わりに、そのまま転送されます。 - Node.jsの
Bufferオブジェクトは、Uint8Arrayとして転送されます。基礎となるArrayBufferをラップすることで、Uint8ArrayをNode.jsのBufferに戻すことができます。
Buffer.from(value.buffer, value.byteOffset, value.byteLength)
DOMオブジェクト（例：Element、Location、DOMMatrix）、Node.jsオブジェクト（例：process.env、Stream）、またはElectronオブジェクト（例：WebContents、BrowserWindow、WebFrame）など、ネイティブなJS型ではないオブジェクトの送信は非推奨となりました。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に固定されました。
systemPreferencesの非推奨イベント
以下のsystemPreferencesイベントは非推奨となりました。
inverted-color-scheme-changedhigh-contrast-color-scheme-changed
代わりにnativeThemeモジュールの新しいupdatedイベントを使用してください。
// Deprecated
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// Replace with
nativeTheme.on('updated', () => { /* ... */ })
非推奨: systemPreferencesのメソッド
次の systemPreferences メソッドは非推奨になりました。
systemPreferences.isDarkMode()systemPreferences.isInvertedColorScheme()systemPreferences.isHighContrastColorScheme()
代わりに次の nativeTheme プロパティを使用してください。
nativeTheme.shouldUseDarkColorsnativeTheme.shouldUseInvertedColorSchemenativeTheme.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)
非推奨: Atom.io Node Headers URL
これは、ネイティブNodeモジュールのビルド時に.npmrcファイルのdisturlとして、または--dist-urlコマンドラインフラグとして指定されるURLです。どちらも当面はサポートされますが、切り替えることをお勧めします。
非推奨: https://atom.io/download/electron
代わりに使用してください: https://electron.dokyumento.jp/headers
API変更: session.clearAuthCache()はオプションを受け付けなくなりました
session.clearAuthCache API は、何をクリアするかについてのオプションを受け付けなくなり、代わりにキャッシュ全体を無条件にクリアするようになりました。
// 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'
})
削除: getBlinkMemoryInfoのmarkedプロパティ
このプロパティはChromium 77で削除されたため、使用できなくなりました。
動作変更: <input type="file"/>のwebkitdirectory属性は、ディレクトリの内容をリストするようになりました
HTMLファイル入力のwebkitdirectoryプロパティを使用すると、フォルダを選択できます。以前のバージョンのElectronでは、入力のevent.target.filesが選択されたフォルダに対応する1つのFileを返すFileListを返すという、正しくない実装がありました。
Electron 7以降、そのFileListはChrome、Firefox、Edgeと同様に、フォルダに含まれるすべてのファイルのリストになります（MDNドキュメントへのリンク）。
例として、次の構造のフォルダを挙げます。
folder
├── file1
├── file2
└── file3
Electron <=6では、これは～を返す`FileList`を返しました。
path/to/folder
Electron 7では、これは～を返す`FileList`を返します。
/path/to/folder/file3
/path/to/folder/file2
/path/to/folder/file1
webkitdirectoryは、選択したフォルダへのパスではなく、フォルダの内容を公開することに注意してください。選択したフォルダへのパスではなく、フォルダの内容が必要な場合は、dialog.showOpenDialog API を参照してください（リンク）。
API変更: Promise化されたAPIのコールバックベースのバージョン
Electron 5とElectron 6では、既存の非同期APIのPromiseベースのバージョンが導入され、古いコールバックベースの対応物が非推奨となりました。Electron 7では、非推奨となったすべてのコールバックベースのAPIが削除されました。
これらの関数は、Promiseのみを返すようになりました。
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()#16176webContents.loadFile()#15855webContents.loadURL()#15855webContents.hasServiceWorker()#16535webContents.printToPDF()#16795webContents.savePage()#16742webFrame.executeJavaScript()#17312webFrame.executeJavaScriptInIsolatedWorld()#17312webviewTag.executeJavaScript()#17312win.capturePage()#15743
これらの関数は、同期型とPromiseベースの非同期型の2つの形式を持つようになりました。
dialog.showMessageBox()/dialog.showMessageBoxSync()#17298dialog.showOpenDialog()/dialog.showOpenDialogSync()#16973dialog.showSaveDialog()/dialog.showSaveDialogSync()#17054
計画されている破壊的API変更 (6.0)
API変更: win.setMenu(null) は win.removeMenu() になりました
// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()
API変更: レンダラープロセス内の electron.screen には、remote を介してアクセスする必要があります
// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen
API変更: サンドボックス化されたレンダラーで require() を使用してNode組み込みモジュールを読み込むと、暗黙的に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の実装が機能しなくなります。Appleのネイティブ代替手段では、強調表示の動作を変更することはできません。
// 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
}
})
動作の変更: nativeWindowOpen を介して開かれた子ウィンドウの nodeIntegration
nativeWindowOpen オプションを使用して開かれた子ウィンドウでは、nodeIntegrationInSubFrames が true でない限り、常にNode.jsの統合が無効になります。
API変更: 特権付きスキームの登録は、アプリの準備が整う前に行う必要があります
レンダラープロセスAPI webFrame.registerURLSchemeAsPrivileged と webFrame.registerURLSchemeAsBypassingCSP、およびブラウザプロセスAPI protocol.registerStandardSchemes は削除されました。新しいAPIである protocol.registerSchemesAsPrivileged が追加され、必要な特権を持つカスタムスキームの登録に使用されるようになりました。カスタムスキームは、アプリの準備が整う前に登録する必要があります。
非推奨: 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変更: webContents.getZoomLevel と webContents.getZoomFactor は同期になりました
webContents.getZoomLevel と webContents.getZoomFactor は、コールバックパラメーターを受け取らなくなり、数値を直接返します。
// 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)
次のリストには、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用のネイティブモジュールをビルドする際、モジュールのbinding.gyp内のwin_delay_load_hook変数はtrueである必要があります（これがデフォルトです）。このフックが存在しない場合、ネイティブモジュールはWindowsでロードに失敗し、「モジュールが見つかりません」のようなエラーメッセージが表示されます。詳細については、ネイティブモジュールガイドを参照してください。
削除済み: IA32 Linuxのサポート
Electron 18以降は、32ビットLinuxシステムでは実行されなくなります。詳細については、32ビットLinuxのサポート終了を参照してください。
破壊的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 */ }
NodeヘッダーURL
これは、ネイティブNodeモジュールをビルドする際に、.npmrcファイルのdisturlとして、または--dist-urlコマンドラインフラグとして指定されるURLです。
非推奨: https://atom.io/download/atom-shell
置き換え: https://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)
menu
// 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リリースには、ファイル名がわずかに異なる2つの同一のARMビルドが含まれています（例：electron-v1.7.3-linux-arm.zipとelectron-v1.7.3-linux-armv7l.zip）。v7lプレフィックス付きのアセットは、ユーザーにサポートされるARMバージョンを明確にし、将来生成される可能性のあるarmv6lおよびarm64アセットと区別するために追加されました。
プレフィックスのないファイルは、それを利用している設定を壊さないように引き続き公開されています。2.0以降、プレフィックスのないファイルは公開されなくなります。