メインコンテンツへ飛ぶ

破壊的変更

破壊的な変更は変更の 一つ前のメジャーバージョン についてここに文書化され、可能であれば非推奨の警告を JS コードに加えます。

破壊的変更の種別

このドキュメントでは、以下の規約によって破壊的な変更を分類しています。

  • API 変更: 古いコードで例外の発生が保証されるように API が変更されました。
  • 動作変更: Electron の動作が変更されましたが、例外が必ず発生する訳ではありません。
  • 省略値変更: 古い省略値に依存するコードは動かなくなるかもしれませんが、必ずしも例外は発生しません。 値を明示することで以前の動作に戻すことができます。
  • 非推奨: API は非推奨になりました。 この API は引き続き機能しますが、非推奨の警告を発し、将来のリリースで削除されます。
  • 削除: API または機能が削除され、Electron でサポートされなくなりました。

予定されている破壊的な API の変更 (23.0)

Removed: BrowserWindow scroll-touch-* events

The deprecated scroll-touch-begin, scroll-touch-end and scroll-touch-edge events on BrowserWindow have been removed. Instead, use the newly available input-event event on WebContents.

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

予定されている破壊的な API の変更 (22.0)

Removed: WebContents new-window event

The new-window event of WebContents has been removed. これは webContents.setWindowOpenHandler() に置き換えられます。

// Removed in Electron 21
webContents.on('new-window', (event) => {
event.preventDefault()
})

// Replace with
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})

Deprecated: BrowserWindow scroll-touch-* events

The scroll-touch-begin, scroll-touch-end and scroll-touch-edge events on BrowserWindow are deprecated. Instead, use the newly available input-event event on WebContents.

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

Behavior Changed: V8 Memory Cage enabled

The V8 memory cage has been enabled, which has implications for native modules which wrap non-V8 memory with ArrayBuffer or Buffer. See the blog post about the V8 memory cage for more details.

API 変更: webContents.printToPDF()

webContents.printToPDF() has been modified to conform to Page.printToPDF in the Chrome DevTools Protocol. This has been changes in order to address changes upstream that made our previous implementation untenable and rife with bugs.

Arguments Changed

  • pageRanges

Arguments Removed

  • printSelectionOnly
  • marginsType
  • headerFooter
  • scaleFactor

Arguments Added

  • headerTemplate
  • footerTemplate
  • displayHeaderFooter
  • margins
  • scale
  • preferCSSPageSize
// 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)

省略値の変更: 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 Changed: session.setDevicePermissionHandler(handler)

The handler invoked when session.setDevicePermissionHandler(handler) is used has a change to its arguments. This handler no longer is passed a frame [WebFrameMain](/ja/docs/latest/api/web-frame-main), but instead is passed the origin, which is the origin that is checking for device permission.

予定されている破壊的な 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 アプリのデフォルトのセキュリティを改善するためのものです。

この機能が必要な場合は、以下のように置換できます。

// メインプロセス
const { ipcMain, desktopCapturer } = require('electron')

ipcMain.handle(
'DESKTOP_CAPTURER_GET_SOURCES',
(event, opts) => desktopCapturer.getSources(opts)
)
// レンダラープロセス
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)

動作変更: crashReporter の実装を Linux の Crashpad に

Linux における crashReporter API の内部実装が Breakpad から Crashpad に変更され、Windows や Mac と同じになりました。 この結果、子プロセスが自動的に監視されるようになり、Node の子プロセスで process.crashReporter.start を呼び出す必要がなくなりました (これは Crashpad レポーターの 2 つ目のインスタンスを起動してしまうため非推奨です)。

また、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 をご参照ください。

予定されている破壊的な API の変更 (14.0)

削除: remote モジュール

remote モジュールは Electron 12 で非推奨となりました。Electron 14 で削除される予定です。 これは @electron/remote モジュールに置き換えられます。

// Electron 12では非推奨:
const { BrowserWindow } = require('electron').remote
// こちらに置換:
const { BrowserWindow } = require('@electron/remote')

// メインプロセスでは:
require('@electron/remote/main').initialize()

削除: app.allowRendererProcessReuse

app.allowRendererProcessReuse プロパティは、セキュリティ、パフォーマンス、保守性のために Chromium のプロセスモデルとより密接に連携する計画の一環として削除されます。

詳細は #18397 を参照してください。

削除: Browser Window の Affinity

BrowserWindow を新規構築する際の affinity オプションは、セキュリティ、パフォーマンス、保守性のために Chromium のプロセスモデルとの共同連携計画の一環として削除されます。

詳細は #18397 を参照してください。

API 変更: window.open()

任意引数 frameName は、ウィンドウのタイトルに設定されなくなります。 これにより、ネイティブの document に対応するパラメータ windowName で説明されている仕様に従うことになりました。

この引数でウインドウのタイトルを設定していた場合は、代わりに win.setTitle(title) を利用できます。

削除: worldSafeExecuteJavaScript

Electron 14 では、 worldSafeExecuteJavaScript が削除されます。 代替手段はありませんので、このプロパティが有効になった上でのコードの動作を確認してください。 これは Electron 12 からデフォルトで有効になっています。 12.

webFrame.executeJavaScriptwebFrame.executeJavaScriptInIsolatedWorld のいずれかを使用している場合、この変更の影響を受けます。 これらのメソッドは同じ値渡しセマンティクスを使用しているため、Context Bridge API がサポートしている戻り値かどうかを確認する必要があります。

削除: 親ウインドウからの BrowserWindowConstructorOptions の継承

Electron 14 より前は、window.open で開いたウインドウは、親ウインドウから transparentresizable などの 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 の値を持つキーとして表示されるようになりました。

// Electron 14 で削除
// window.open('...', '', 'my-key') で動く
webContents.on('did-create-window', (window, details) => {
if (details.additionalFeatures.includes('my-key')) {
// ...
}
})

// こちらに置換
webContents.on('did-create-window', (window, details) => {
if (details.options['my-key']) {
// ...
}
})

Planned Breaking API Changes (13.0)

API 変更: session.setPermissionCheckHandler(handler)

handler メソッドの第 1 引数は、前までは必ず webContents でしたが、これからは null になることもあります。 requestingOriginembeddingOriginsecurityOrigin プロパティを使用して、権限の確認へ正しく対応する必要があります。 webContentsnull になることがあるので、これに依存しないようにしてください。

// 古いコード
session.setPermissionCheckHandler((webContents, permission) => {
if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
return true
}
return false
})

// こちらに置換
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
return true
}
return false
})

削除: shell.moveItemToTrash()

非推奨となっていた同期型の shell.moveItemToTrash() API が削除されました。 代わりに非同期の 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()
// Electron 13 で削除
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// こちらに置換
session.defaultSession.loadExtension(path)
// Electron 13 で削除
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// こちらに置換
session.defaultSession.removeExtension(extension_id)
// Electron 13 で削除
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// こちらに置換
session.defaultSession.getAllExtensions()

削除した systemPreferences のメソッド

以下の systemPreferences のメソッドは非推奨になりました。

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

代わりに、次の nativeTheme プロパティを使用します。

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
// Electron 13 で削除
systemPreferences.isDarkMode()
// こちらに置換
nativeTheme.shouldUseDarkColors

// Electron 13 で削除
systemPreferences.isInvertedColorScheme()
// こちらに置換
nativeTheme.shouldUseInvertedColorScheme

// Electron 13 で削除
systemPreferences.isHighContrastColorScheme()
// こちらに置換
nativeTheme.shouldUseHighContrastColors

非推奨: WebContents new-window イベント

WebContents の new-window イベントは非推奨となりました。 これは webContents.setWindowOpenHandler() に置き換えられます。

// Electron 13 で非推奨
webContents.on('new-window', (event) => {
event.preventDefault()
})

// こちらに置換
webContents.setWindowOpenHandler((details) => {
return { action: 'deny' }
})

Planned Breaking API Changes (12.0)

削除: Pepper Flash サポート

Chromium が Flash のサポートを削除したため、私たちもこれに従わなければなりません。 詳細については、Chromium の Flash Roadmap を参照してください。

省略値変更: worldSafeExecuteJavaScript の省略値を true

Electron 12 からは worldSafeExecuteJavaScript が既定で有効です。 以前の動作に戻すには、WebPreferences で worldSafeExecuteJavaScript: false を指定する必要があります。 このオプションを false に設定すると 安全ではなくなる ことに注意してください。

このオプションは Electron 14 で削除予定なので、デフォルト値をサポートするようにコードを移行してください。

省略値変更: contextIsolation の省略値を true

In Electron 12, contextIsolation will be enabled by default. To restore the previous behavior, contextIsolation: false must be specified in WebPreferences.

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

これは、nodeIntegrationtrue かつ contextIsolationfalse でない限り、require() がレンダラープロセスで使用できなくなるということでもあります。

詳細はこちら: https://github.com/electron/electron/issues/23506

削除: crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory メソッドは削除されました。 app.getPath('crashDumps)に置き換える必要があります。

// Electron 12 で削除
crashReporter.getCrashesDirectory()
// こちらに置換
app.getPath('crashDumps')

削除: レンダラープロセス内での crashReporter メソッド

以下の crashReporter メソッドはレンダラープロセスで利用できなくなります。

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

これらは、メインプロセスから呼び出ことしかできません。

詳しくは #23265 を参照してください。

既定値の変更: crashReporter.start({ compress: true })

crashReporter.startcompress オプションの既定値が false から true へ変更されました。 つまり、クラッシュのダンプは Content-Encoding: gzip ヘッダで、本文が圧縮されてクラッシュ収集サーバーにアップロードされます。

クラッシュ収集サーバーが圧縮形式のペイロードをサポートしていない場合、クラッシュレポーターのオプションで { compress: false } を指定すれば圧縮をオフにできます。

非推奨: remote モジュール

remote モジュールは Electron 12 で非推奨となり、Electron 14 で削除される予定です。 これは @electron/remote モジュールに置き換えられます。

// Electron 12では非推奨:
const { BrowserWindow } = require('electron').remote
// こちらに置換:
const { BrowserWindow } = require('@electron/remote')

// メインプロセスでは:
require('@electron/remote/main').initialize()

Deprecated: shell.moveItemToTrash()

同期的な shell.moveItemToTrash() は、新しく非同期的な shell.trashItem() に置き換えられました。

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

Planned Breaking API Changes (11.0)

削除: BrowserView.{destroy, fromId, fromWebContents, getAllViews}BrowserViewid プロパティ

実験的 API BrowserView.{destroy, fromId, fromWebContents, getAllViews} が削除されました。 加えて、BrowserViewid プロパティも削除されました。

詳細な情報は、#23578 を参照してください。

Planned Breaking API Changes (10.0)

非推奨: crashReporter.start() 関数のcompanyName 引数

crashReporter.start()の引数のcompanyName は以前は必須でしたが、省略可能になり、今後廃止することになりました。 非推奨ではない方法で以前と同じ動作を実現するには、 globalExtra companyName の値を渡します。

// Electron 10 で非推奨
crashReporter.start({ companyName: 'Umbrella Corporation' })
// 置き換え
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

非推奨: crashReporter.getCrashesDirectory()

crashReporter.getCrashesDirectory メソッドは非推奨となりました。 app.getPath('crashDumps)に置き換える必要があります。

// Electron 10 では非推奨
crashReporter.getCrashesDirectory()
// 置き換え
app.getPath('crashDumps')

非推奨: レンダラープロセス内での crashReporter メソッド

レンダラープロセスから以下の crashReporter メソッドを呼び出すことは非推奨になります。:

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

レンダラーの crashReporter モジュールに残っている非推奨ではないメソッドは、 extraParameterremoveExtraParametergetParametersだけです。

上記のすべてのメソッドは、メインプロセスから呼び出されたときに非推奨のままです。

詳しくは #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 は同期になり、任意のコールバックは不要になりました。

// 非推奨
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// こちらに置換
protocol.unregisterProtocol(scheme)

protocol.registerFileProtocol

protocol.registerBufferProtocol

protocol.registerStringProtocol

protocol.registerHttpProtocol

protocol.registerStreamProtocol

protocol.interceptFileProtocol

protocol.interceptStringProtocol

protocol.interceptBufferProtocol

protocol.interceptHttpProtocol

protocol.interceptStreamProtocol

API は同期になり、任意のコールバックは不要になりました。

// 非推奨
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// こちらに置換
protocol.registerFileProtocol(scheme, handler)

登録または干渉されたプロトコルは、ナビゲーションが発生するまで現在のページに影響しません。

protocol.isProtocolHandled

この API は非推奨です。ユーザーは、代わりに protocol.isProtocolRegistered および protocol.isProtocolIntercepted を使用する必要があります。

// 非推奨
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// こちらに置換
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)

予定されている破壊的な API の変更 (9.0)

省略値変更: レンダラープロセス内でコンテキスト未対応のネイティブモジュールのロードがデフォルトで無効に

Electron 9 では、レンダラープロセスでコンテキスト未対応のネイティブモジュールをロードすることはできなくなります。 これは Electron のプロジェクトとしてのセキュリティ、パフォーマンス、保守性を向上させるためです。

これが影響する場合、app.allowRendererProcessReusefalse に設定して一時的に以前の動作に戻すことができます。 このフラグは 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()
// Electron 9 で非推奨化
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// こちらに置換
session.defaultSession.loadExtension(path)
// Electron 9 で非推奨化
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// こちらに置換
session.defaultSession.removeExtension(extension_id)
// Electron 9 で非推奨化
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// こちらに置換
session.defaultSession.getAllExtensions()

削除: <webview>.getWebContents()

Electron 8.0 で非推奨となっていた、この API は削除されました。

// Electron 9.0 で削除
webview.getWebContents()
// こちらに置換
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

削除: webFrame.setLayoutZoomLevelLimits()

Chromium は、レイアウトのズームレベル制限を変更するサポートを削除しました。そのうえ、これは Elcetron でメンテナンスできるものではありません。 この関数は Electron 8.x で非推奨となり、Electron 9.x で削除されました。 レイアウトのズームレベル制限は、こちら で定義されているように最小 0.25 から最大 5.0 に固定されました。

動作変更: IPC で非 JS オブジェクトを送信すると、例外が送出されるように

Electron 8.0 では、構造化複製アルゴリズムを使用するように IPC が変更され、パフォーマンスが大幅に改善されました。 移行を容易にするため、旧 IPC シリアライズアルゴリズムは、構造化複製でシリアライズできない一部のオブジェクトにそのまま使用されます。 特に、DOM オブジェクト (ElementLocationDOMMatrix など)、内部に C++ のクラスがある Node.js オブジェクト (process.envStream のいくつかのメンバーなど)、内部に C++ のクラスがある Electron オブジェクト (WebContentsBrowserWindowWebFrame など) は、構造化複製ではシリアライズできません。 旧アルゴリズムが呼び出されるたびに、非推奨の警告が出力されます。

Electron 9.0 では、旧シリアライズアルゴリズムが削除されました。先ほどのシリアライズ不可能なオブジェクトを送信すると、"object could not be cloned" (オブジェクトを複製できませんでした) というエラーが送出されます。

API 変更: shell.openItemshell.openPath

shell.openItem API は非同期の shell.openPath API に置き換えられました。 元の API の提案と理由は こちら で確認できます。

予定されている破壊的な API の変更 (8.0)

動作変更: IPC を介して送信される値が構造化複製アルゴリズムでシリアライズされるように

IPC を介して (ipcRenderer.sendipcRenderer.sendSyncWebContents.send 及び関連メソッドから) オブジェクトを送信できます。このオブジェクトのシリアライズに使用されるアルゴリズムが、カスタムアルゴリズムから V8 組み込みの 構造化複製アルゴリズム に切り替わります。これは postMessage のメッセージのシリアライズに使用されるものと同じアルゴリズムです。 これにより、大きなメッセージに対するパフォーマンスが 2 倍向上しますが、動作に重大な変更が加えられます。

  • 関数、Promise、WeakMap、WeakSet、これらの値を含むオブジェクトを IPC 経由で送信すると、関数らを暗黙的に undefined に変換していましたが、代わりに例外が送出されるようになります。
// 以前:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => メインプロセスに { value: 3 } が着く

// Electron 8 から:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => Error("() => {} could not be cloned.") を投げる
  • NaNInfinity-Infinity は、null に変換するのではなく、正しくシリアライズします。
  • 循環参照を含むオブジェクトは、null に変換するのではなく、正しくシリアライズします。
  • SetMapErrorRegExp の値は、{} に変換するのではなく、正しくシリアライズします。
  • BigInt の値は、null に変換するのではなく、正しくシリアライズします。
  • 疎配列は、null の密配列に変換するのではなく、そのままシリアライズします。
  • Date オブジェクトは、ISO 文字列表現に変換するのではなく、Date オブジェクトとして転送します。
  • 型付き配列 (Uint8ArrayUint16ArrayUint32Array など) は、Node.js の Buffer に変換するのではなく、そのまま転送します。
  • Node.js の Buffer オブジェクトは、Uint8Array として転送します。 基底となる ArrayBuffer をラップすることで、Uint8Array を Node.js の Buffer に変換できます。
Buffer.from(value.buffer, value.byteOffset, value.byteLength)

ネイティブな JS 型ではないオブジェクト、すなわち DOM オブジェクト (ElementLocationDOMMatrix など)、Node.js オブジェクト (process.envStream のいくつかのメンバーなど)、Electron オブジェクト (WebContentsBrowserWindowWebFrame など) のようなものは非推奨です。 Electron 8 では、これらのオブジェクトは DeprecationWarning メッセージで以前と同様にシリアライズされます。しかし、Electron 9 以降でこういった類のオブジェクトを送信すると "could not be cloned" エラーが送出されます。

非推奨: <webview>.getWebContents()

この API は、パフォーマンスとセキュリティの両方に影響する remote モジュールを使用して実装されます。 したがって、その用途がはっきりとしている必要があります。

// 非推奨
webview.getWebContents()
// こちらに置換
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

ただし、remote モジュールをできる限り使用しないことを推奨します。

// メイン
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()
})

// レンダラー
const { ipcRenderer } = require('electron')

ipcRenderer.invoke('openDevTools', webview.getWebContentsId())

非推奨: webFrame.setLayoutZoomLevelLimits()

Chromium は、レイアウトのズームレベル制限を変更するサポートを削除しました。そのうえ、これは Elcetron でメンテナンスできるものではありません。 この関数は Electron 8.x に警告を出力し、Electron 9.x に存在しなくなります。 レイアウトのズームレベル制限は、こちら で定義されているように最小 0.25 から最大 5.0 に固定されました。

非推奨化した systemPreferences のイベント

以下の systemPreferences のイベントは非推奨になりました。

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

代わりに nativeTheme の新しいイベントである updated を使用してください。

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

// こちらに置換
nativeTheme.on('updated', () => { /* ... */ })

非推奨化した systemPreferences のメソッド

以下の systemPreferences のメソッドは非推奨になりました。

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

代わりに、次の nativeTheme プロパティを使用します。

  • nativeTheme.shouldUseDarkColors
  • nativeTheme.shouldUseInvertedColorScheme
  • nativeTheme.shouldUseHighContrastColors
// Deprecated
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors

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

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

予定されている破壊的なAPIの変更 (7.0)

非推奨: Atom.io の Node ヘッダー URL

これは .npmrc ファイル内の disturl か、ネイティブ Node モジュールをビルドするときの --dist-url コマンドライン引数で指定する URL です。 両方とも近い将来サポートされますが、切り替えることを推奨します。

非推奨: https://atom.io/download/electron

こちらに置換: https://electronjs.org/headers

API 変更: session.clearAuthCache() が引数を受け取らないように

session.clearAuthCache API は、消去対象のオプションを受け入れなくなり、代わりにキャッシュ全体を無条件に消去します。

// 非推奨
session.clearAuthCache({ type: 'password' })
// こちらに置換
session.clearAuthCache()

API 変更: powerMonitor.querySystemIdleStatepowerMonitor.getSystemIdleState

// Electron 7.0 で削除
powerMonitor.querySystemIdleState(threshold, callback)
// こちらの非同期 API に置換
const idleState = powerMonitor.getSystemIdleState(threshold)

API 変更: powerMonitor.querySystemIdleTimepowerMonitor.getSystemIdleTime

// Electron 7.0 で削除
powerMonitor.querySystemIdleTime(callback)
// こちらの非同期 API に置換
const idleTime = powerMonitor.getSystemIdleTime()

API 変更: webFrame.setIsolatedWorldInfo で分散したメソッドを置換

// Electron 7.0 で削除
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// こちらに置換
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})

削除: getBlinkMemoryInfomarked プロパティ

このプロパティは Chromium 77 で削除されたため、利用できなくなりました。

動作変更: <input type="file"/>webkitdirectory 属性でディレクトリの内容を取るように

webkitdirectory プロパティは、HTML ファイル上の input でフォルダーを選択できるようにします。 以前の Electron のバージョンでは、input の event.target.files において、選択したフォルダーに対応する 1 つの File が入った FileList を返すという誤った実装がありました。

Electron 7 では、Chrome、Firefox、Edge と同様 (MDNドキュメントへのリンク) に、FileList はフォルダー内に含まれるすべてのファイルのリストになりました。

例として、以下の構造のフォルダーを使用します。

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

Electron <= 6 では、以下のような File オブジェクトが 1 つ入った FileList を返します。

path/to/folder

Electron 7 では、以下のような File オブジェクトが入った FileList を返します。

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

webkitdirectory は、選択したフォルダーへのパスを公開しないことに注意してください。 フォルダーの内容ではなく選択したフォルダーへのパスが必要な場合は、dialog.showOpenDialog API (リンク) を参照してください。

API 変更: Promise ベースの API の Callback ベース版

Electron 5 とElectron 6 では、既存の非同期 API の Promise ベース版を導入し、対応する古いコールバックベースのものは非推奨にしました。 Electron 7 では、非推奨のコールバックベースの API がすべて削除されます。

これらの関数は Promise を返すようになりました。

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

これらの関数には、同期と Promise ベースの非同期、2 つの形式があります。

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

予定されている破壊的なAPIの変更 (6.0)

API 変更: win.setMenu(null)win.removeMenu()

// 非推奨
win.setMenu(null)
// こちらに置換
win.removeMenu()

API 変更: レンダラープロセスの electron.screenremote を介してアクセスするように

// 非推奨
require('electron').screen
// こちらに置換
require('electron').remote.screen

API 変更: サンドボックスレンダラー内の Node 組み込みの require()remote のものを読み込まないように

// 非推奨
require('child_process')
// こちらに置換
require('electron').remote.require('child_process')

// 非推奨
require('fs')
// こちらに置換
require('electron').remote.require('fs')

// 非推奨
require('os')
// こちらに置換
require('electron').remote.require('os')

// 非推奨
require('path')
// こちらに置換
require('electron').remote.require('path')

非推奨: powerMonitor.querySystemIdleStatepowerMonitor.getSystemIdleState で置換

// 非推奨
powerMonitor.querySystemIdleState(threshold, callback)
// こちらの非同期 API に置換
const idleState = powerMonitor.getSystemIdleState(threshold)

非推奨: powerMonitor.querySystemIdleTimepowerMonitor.getSystemIdleTime で置換

// 非推奨
powerMonitor.querySystemIdleTime(callback)
// こちらの非同期 API に置換
const idleTime = powerMonitor.getSystemIdleTime()

非推奨: app.enableMixedSandbox() が不要に

// 非推奨
app.enableMixedSandbox()

混合サンドボックスモードはデフォルトで有効になりました。

非推奨: Tray.setHighlightMode

macOS Catalina 下では、以前の Tray 実装は破壊されています。 Apple のネイティブの代替実装は、強調表示動作の変更をサポートしていません。

// 非推奨
tray.setHighlightMode(mode)
// API は v7.0 で削除され、置換はできません

予定されている破壊的なAPIの変更 (5.0)

省略値変更: nodeIntegrationwebviewTag の省略値は false に、contextIsolation の省略値は true に

以下の webPreferences オプションの初期値は、以下の記載された新しい初期値のために非推奨になっています。

属性非推奨の初期値新しい初期値
contextIsolationfalsetrue
nodeIntegrationtruefalse
webviewTagnodeIntegration を設定しなければ truefalse

以下は例です。 webviewTag を再有効化しています。

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

動作変更: 子ウインドウ内の nodeIntegrationnativeWindowOpen を介して開かれるように

nativeWindowOpen オプションで開かれる子ウインドウは、nodeIntegrationInSubFramestrue でなければ Node.js インテグレーションが無効化されます。

API 変更: 特権スキームの登録は app の ready より前に行わなければならないように

レンダラプロセス API webFrame.registerURLSchemeAsPrivileged webFrame.registerURLSchemeAsBypassingCSP、ならびにブラウザプロセス API protocol.registerStandardSchemes を削除しました。 新しい API、protocol.registerSchemesAsPrivileged が追加されました。これは、必要な権限でカスタムスキームを登録するために使用する必要があります。 カスタムスキームは、app の ready より前に登録する必要があります。

非推奨: webFrame.setIsolatedWorld*webFrame.setIsolatedWorldInfo で置換

// 非推奨
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// こちらに置換
webFrame.setIsolatedWorldInfo(
worldId,
{
securityOrigin: 'some_origin',
name: 'human_readable_name',
csp: 'content_security_policy'
})

API 変更: webFrame.setSpellCheckProvider が非同期コールバックを取るように

spellCheck コールバックは非同期になり、autoCorrectWord パラメーターは削除されました。

// 非推奨
webFrame.setSpellCheckProvider('en-US', true, {
spellCheck: (text) => {
return !spellchecker.isMisspelled(text)
}
})
// こちらに置換
webFrame.setSpellCheckProvider('en-US', {
spellCheck: (words, callback) => {
callback(words.filter(text => spellchecker.isMisspelled(text)))
}
})

API 変更: webContents.getZoomLevelwebContents.getZoomFactor が同期実行に

webContents.getZoomLevelwebContents.getZoomFactor はコールバック引数を受け取らなくなり、代わりに数値を直接返すようになります。

// 非推奨
webContents.getZoomLevel((level) => {
console.log(level)
})
// こちらに置換
const level = webContents.getZoomLevel()
console.log(level)
// 非推奨
webContents.getZoomFactor((factor) => {
console.log(factor)
})
// こちらに置換
const factor = webContents.getZoomFactor()
console.log(factor)

予定されている破壊的なAPIの変更 (4.0)

以下のリストには Electron 4.0 でなされた破壊的な API の変更が含まれています。

app.makeSingleInstance

// 非推奨
app.makeSingleInstance((argv, cwd) => {
/* ... */
})
// こちらに置換
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
/* ... */
})

app.releaseSingleInstance

// 非推奨
app.releaseSingleInstance()
// こちらに置換
app.releaseSingleInstanceLock()

app.getGPUInfo

app.getGPUInfo('complete')
// macOS 上では `basic` と同様に振る舞う
app.getGPUInfo('basic')

win_delay_load_hook

Windows 向けにネイティブモジュールをビルドするとき、モジュールの binding.gyp 内の win_delay_load_hook 変数は true (これが初期値) にならなければいけません。 このフックが存在しない場合ネイティブモジュールは Windows 上でロードできず、モジュールが見つかりません のようなエラーメッセージが表示されます。 より詳しくは ネイティブモジュールのガイド をご参照ください。

削除: IA32 Linux サポート

Electron 18 は、32 ビット版 Linux システムでは動作しなくなります。 詳細は 32-bit Linux のサポート終了 をご参照ください。

破壊的な API の変更 (3.0)

以下のリストには Electron 3.0 での破壊的な API の変更が含まれています。

app

// 非推奨
app.getAppMemoryInfo()
// こちらに置換
app.getAppMetrics()

// 非推奨
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // 非推奨なプロパティ

BrowserWindow

// 非推奨
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// こちらに置き換えてください
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)

// 非推奨
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play_pause') {
// do something
}
})
// こちらに置き換えてください
window.on('app-command', (e, cmd) => {
if (cmd === 'media-play-pause') {
// do something
}
})

`clipboard

`

// 非推奨
clipboard.readRtf()
// こちらに置換
clipboard.readRTF()

// 非推奨
clipboard.writeRtf()
// こちらに置換
clipboard.writeRTF()

// 非推奨
clipboard.readHtml()
// こちらに置換
clipboard.readHTML()

// 非推奨
clipboard.writeHtml()
// こちらに置換
clipboard.writeHTML()

crashReporter

// 非推奨
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
autoSubmit: true
})
// こちらに置換
crashReporter.start({
companyName: 'Crashly',
submitURL: 'https://crash.server.com',
uploadToServer: true
})

nativeImage

// 非推奨
nativeImage.createFromBuffer(buffer, 1.0)
// こちらに置換
nativeImage.createFromBuffer(buffer, {
scaleFactor: 1.0
})

process

// 非推奨
const info = process.getProcessMemoryInfo()

screen

// 非推奨
screen.getMenuBarHeight()
// こちらに置換
screen.getPrimaryDisplay().workArea

session

// 非推奨
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
callback(true)
})
// こちらに置換
ses.setCertificateVerifyProc((request, callback) => {
callback(0)
})

Tray

// 非推奨
tray.setHighlightMode(true)
// こちらに置換
tray.setHighlightMode('on')

// 非推奨
tray.setHighlightMode(false)
// こちらに置換
tray.setHighlightMode('off')

webContents

// 非推奨
webContents.openDevTools({ detach: true })
// こちらに置換
webContents.openDevTools({ mode: 'detach' })

// 削除されました
webContents.setSize(options)
// この API は置換できません

webFrame

// 非推奨
webFrame.registerURLSchemeAsSecure('app')
// こちらに置換
protocol.registerStandardSchemes(['app'], { secure: true })

// 非推奨
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// こちらに置換
protocol.registerStandardSchemes(['app'], { secure: true })

<webview>

// 削除されました
webview.setAttribute('disableguestresize', '')
// この API は置換できません

// 削除されました
webview.setAttribute('guestinstance', instanceId)
// この API は置換できません

// webview タグ上ではキーボードリスナは動作しなくなります
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node Headers URL

これは .npmrc ファイル内の disturl か、ネイティブ Node モジュールをビルドするときの --dist-url コマンドライン引数で指定する URL です。

非推奨: https://atom.io/download/atom-shell

こちらに置換: https://atom.io/download/electron

破壊的な API の変更 (2.0)

以下のリストには Electron 2.0 でなされた破壊的な API の変更が含まれています。

BrowserWindow

// 非推奨
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// こちらに置換
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)
// 削除されました
menu.popup(browserWindow, 100, 200, 2)
// こちらに置換
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage

// 削除されました
nativeImage.toPng()
// こちらに置換
nativeImage.toPNG()

// 削除されました
nativeImage.toJpeg()
// こちらに置換
nativeImage.toJPEG()

process

  • process.versions.electronprocess.version.chrome は、Node によって定められた他の process.versions プロパティと一貫性を持つために読み取り専用プロパティになりました。

webContents

// 削除されました
webContents.setZoomLevelLimits(1, 2)
// こちらに置換
webContents.setVisualZoomLevelLimits(1, 2)

webFrame

// 削除されました
webFrame.setZoomLevelLimits(1, 2)
// こちらに置換
webFrame.setVisualZoomLevelLimits(1, 2)

<webview>

// 削除されました
webview.setZoomLevelLimits(1, 2)
// こちらに置換
webview.setVisualZoomLevelLimits(1, 2)

重複する ARM アセット

どの Electron リリースにも、electron-v1.7.3-linux-arm.zipelectron-v1.7.3-linux-armv7l.zip のような少しファイル名が異なる2つの同一な ARM ビルドが含まれます。 サポートされている ARM バージョンをユーザに明確にし、将来作成される armv6l および arm64 アセットらと明確にするために、v7l という接頭子を持つアセットが追加されました。

接頭子が付いていない ファイルは、まだそれを使用している可能性がある設定を破壊しないために公開しています。 2.0 からは、接頭子のないファイルは公開されなくなりました。

詳細は、69867189 を参照してください。