メインコンテンツへ飛ぶ

破壊的変更

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

破壊的変更の種別​

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

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

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

動作変更: app の login の webContents プロパティ​

app からの login イベントの webContents プロパティは、respondToAuthRequestsFromMainProcess オプションで作成された ユーティリティプロセス からのリクエストに対してイベントがトリガされた場合、null になります。

非推奨: systemPreferences.accessibilityDisplayShouldReduceTransparency​

systemPreferences.accessibilityDisplayShouldReduceTransparency プロパティは非推奨とし、代わりに同一の情報を提供し、クロスプラットフォームで動作する、新規追加の nativeTheme.prefersReducedTransparency を推奨します。

// 非推奨
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency

// こちらで置き換えてください:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency

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

削除: File.path​

ウェブの File オブジェクトの非標準の path プロパティは、レンダラー内ですべてを実行するのが一般的だった時代に、ネイティブのファイルを操作する便利な方法として Electron の初期バージョンで追加されました。 ただし、これは標準からの逸脱であり軽微なセキュリティリスクも伴うため、Electron 32.0 以降では webUtils.getPathForFile メソッドに置き換えられました。

// 以前 (レンダラー)

const file = document.querySelector('input[type=file]')
alert(`Uploaded file path was: ${file.path}`)
// これから (レンダラー)

const file = document.querySelector('input[type=file]')
electron.showFilePath(file)

// (プリロード)
const { contextBridge, webUtils } = require('electron')

contextBridge.exposeInMainWorld('electron', {
  showFilePath (file) {
    // できればウェブコンテンツへの完全なファイルパスを
    // 公開しないことを推奨します。
    const path = webUtils.getPathForFile(file)
    alert(`Uploaded file path was: ${path}`)
  }
})

非推奨: WebContents の clearHistory, canGoBack, goBack, canGoForward, goForward, goToIndex, canGoToOffset, goToOffset​

以前のナビゲーション関連の API は非推奨になりました。

これらの API は、ナビゲーション履歴を管理するより構造化された直感的インターフェースを提供するために、WebContents の navigationHistory プロパティへ移動されました。

// 非推奨
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)

// こちらで置き換えてください
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) は Dock のアイコンを 1 回バウンスするだけ (NSInformationalRequest レベルを使用する場合) で、flashFrame(false) は何も行いません。 新しい動作: flashFrame(false) が呼び出されるまで、持続的に点滅します。 これは NSCriticalRequest レベルを代わりに使用しています。 NSInformationalRequest を明示的に使用してこれまで通り一度だけの Dock のアイコンをバウンスさせたい場合は、dock.bounce('informational') を使用できます。

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

動作変更: クロスオリジンの iframe が権限ポリシーを用いて機能にアクセスするようになりました​

クロスオリジンの 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 つのアプローチの動作は同じでした。 ただしより高度なケースでは、Windows および Linux のカスタムサイズ変更アルゴリズムが macOS の自動サイズ変更 API の動作と完全に一致しませんでした。そのめ、BrowserView の自動サイズ変更は macOS 上では他のプラットフォームとは異なる動作でした。 この自動サイズ変更の動作がすべてのプラットフォーム間で標準化されました。

もしあなたのアプリが BrowserView をウィンドウ全体に表示するよりも複雑な操作を BrowserView.setAutoResize で行っていたのならば、macOS でのこの動作の違いに対処するカスタムロジックを既に用意していたことでしょう。 その場合、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 を使用してください。

// 削除済み
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })

// こちらで置き換えてください
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

削除: WebContents と <webview> の crashed イベント​

WebContents と <webview> にある crashed イベントは削除されました。 代わりに新しいイベントである render-process-gone を使用してください。

// 削除済み
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })

// こちらで置き換えてください
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 イベントを使用してください。

// 削除済み
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })

// こちらで置き換えてください
app.on('child-process-gone', (event, details) => { /* ... */ })

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

動作変更： WebContents.backgroundThrottling をfalseにすると、ホスト WebContents 内のすべての BrowserWindowに影響を与えます​

WebContents.backgroundThrottling を false に設定すると、その BrowserWindow によって表示されるすべての WebContents でのフレーム抑制が無効化されます。

削除: BrowserWindow.setTrafficLightPosition(position)​

BrowserWindow.setTrafficLightPosition(position) は削除され、代わりに BrowserWindow.setWindowButtonPosition(position) API が推奨されています。こちらでデフォルトの位置へリセットする際には、{ x: 0, y: 0 } の代わりに null を受け付けるようになっています。

// Electron 28 で非推奨
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })

// こちらに置き換えてください
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)

削除: BrowserWindow.getTrafficLightPosition()​

BrowserWindow.getTrafficLightPosition() は削除され、代わりに BrowserWindow.getWindowButtonPosition() API を使うようになりました。こちらでカスタム位置が無いときは、{ x: 0, y: 0 } の代わりに null を受け付けるようになっています。

// Electron 28 で削除
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
  // カスタム位置が無い時。
}

// こちらで置き換えてください
const ret = win.getWindowButtonPosition()
if (ret === null) {
  // カスタム位置が無い時。
}

削除: ipcRenderer.sendTo()​

ipcRenderer.sendTo() API は削除されました。 これは、レンダラー間で MessageChannel を設定するように置き換える必要があります。

IpcRendererEvent の senderId と senderIsMainFrame のプロパティも削除されました。

削除: app.runningUnderRosettaTranslation​

app.runningUnderRosettaTranslation プロパティは削除されました。 代わりに app.runningUnderARM64Translation を使用してください。

// 削除されました
console.log(app.runningUnderRosettaTranslation)
// こちらで置き換えてください
console.log(app.runningUnderARM64Translation)

非推奨: app での renderer-process-crashed イベント​

app での renderer-process-crashed イベントは非推奨になりました。 代わりに新しいイベントである render-process-gone を使用してください。

// 非推奨
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })

// こちらに置き換えてください
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

非推奨: WebContents の context-menu にある params.inputFormType​

WebContents からの context-menu イベントの params オブジェクトにある inputFormType プロパティは非推奨になりました。 代わりに新しい formControlType プロパティを使用してください。

非推奨: WebContents と <webview> にある crashed イベント​

WebContents と <webview> にある crashed イベントは非推奨になりました。 代わりに新しいイベントである render-process-gone を使用してください。

// 非推奨
win.webContents.on('crashed', (event, killed) => { /* ... */ })
webview.addEventListener('crashed', (event) => { /* ... */ })

// こちらに置き換えてください
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 イベントを使用してください。

// 非推奨
app.on('gpu-process-crashed', (event, killed) => { /* ... */ })

// こちらに置き換えてください
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-changed
  • high-contrast-color-scheme-changed

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

// 削除されました
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })

// こちらで置き換えてください
nativeTheme.on('updated', () => { /* ... */ })

削除: macOS での window.setVibrancy オプション​

以下の振動オプションは削除されました。

  • 'light'
  • 'medium-light'
  • 'dark'
  • 'ultra-dark'
  • 'appearance-based'

これらは以前から非推奨であり、10.15 で Apple によって削除されました。

削除: webContents.getPrinters​

webContents.getPrinters メソッドは削除されました。 代わりに webContents.getPrintersAsync を使用してください。

const w = new BrowserWindow({ show: false })

// 削除されました
console.log(w.webContents.getPrinters())
// こちらで置き換えてください
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

削除: systemPreferences.{get,set}AppLevelAppearance と systemPreferences.appLevelAppearance​

systemPreferences.appLevelAppearance プロパティと同様に、systemPreferences.getAppLevelAppearance と systemPreferences.setAppLevelAppearance メソッドも削除されました。 代わりに nativeTheme モジュールを使用してください。

// 削除されました
systemPreferences.getAppLevelAppearance()
// こちらで置き換えてください
nativeTheme.shouldUseDarkColors

// 削除されました
systemPreferences.appLevelAppearance
// こちらで置き換えてください
nativeTheme.shouldUseDarkColors

// 削除されました
systemPreferences.setAppLevelAppearance('dark')
// こちらで置き換えてください
nativeTheme.themeSource = 'dark'

削除: systemPreferences.getColor での alternate-selected-control-text の値​

systemPreferences.getColor での alternate-selected-control-text の値は削除されました。 代わりに selected-content-background を使用してください。

// 削除されました
systemPreferences.getColor('alternate-selected-control-text')
// こちらで置き換えてください
systemPreferences.getColor('selected-content-background')

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

非推奨: webContents.getPrinters​

webContents.getPrinters メソッドは非推奨となりました。 代わりに webContents.getPrintersAsync を使用してください。

const w = new BrowserWindow({ show: false })

// 非推奨
console.log(w.webContents.getPrinters())
// こちらで置き換えてください
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

非推奨: systemPreferences.{get,set}AppLevelAppearance と systemPreferences.appLevelAppearance​

systemPreferences.appLevelAppearance プロパティと同様に、systemPreferences.getAppLevelAppearance と systemPreferences.setAppLevelAppearance メソッドも非推奨になりました。 代わりに nativeTheme モジュールを使用してください。

// 非推奨
systemPreferences.getAppLevelAppearance()
// こちらで置き換えてください
nativeTheme.shouldUseDarkColors

// 非推奨
systemPreferences.appLevelAppearance
// こちらで置き換えてください
nativeTheme.shouldUseDarkColors

// 非推奨
systemPreferences.setAppLevelAppearance('dark')
// こちらで置き換えてください
nativeTheme.themeSource = 'dark'

非推奨: systemPreferences.getColor での alternate-selected-control-text の値​

systemPreferences.getColor での alternate-selected-control-text の値は非推奨になりました。 代わりに selected-content-background を使用してください。

// 非推奨
systemPreferences.getColor('alternate-selected-control-text')
// こちらで置き換えてください
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 に置き換えられました。

新しいメソッドは、新しいプロトコルを登録するか、既存のプロトコルを傍受するか、どのタイプの応答も可能です。

// Electron 25 で非推奨
protocol.registerBufferProtocol('some-protocol', () => {
  callback({ mimeType: 'text/html', data: Buffer.from('<h5>Response</h5>') })
})

// こちらで置き換えてください
protocol.handle('some-protocol', () => {
  return new Response(
    Buffer.from('<h5>Response</h5>'), // これは文字列や ReadableStream にもできます。
    { headers: { 'content-type': 'text/html' } }
  )
})
// Electron 25 で非推奨
protocol.registerHttpProtocol('some-protocol', () => {
  callback({ url: 'https://electronjs.org' })
})

// こちらで置き換えてください
protocol.handle('some-protocol', () => {
  return net.fetch('https://electronjs.org')
})
// Electron 25 で非推奨
protocol.registerFileProtocol('some-protocol', () => {
  callback({ filePath: '/path/to/my/file' })
})

// こちらで置き換えてください
protocol.handle('some-protocol', () => {
  return net.fetch('file:///path/to/my/file')
})

非推奨: BrowserWindow.setTrafficLightPosition(position)​

BrowserWindow.setTrafficLightPosition(position) は非推奨になり、代わりに BrowserWindow.setWindowButtonPosition(position) API を使うようになりました。こちらでシステム基底の位置へリセットする際には、{ x: 0, y: 0 } の代わりに null を受け付けるようになっています。

// Electron 25 で非推奨
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })

// こちらで置き換えてください
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)

非推奨: BrowserWindow.getTrafficLightPosition()​

BrowserWindow.getTrafficLightPosition() は非推奨になり、代わりに BrowserWindow.getWindowButtonPosition() API を使うようになりました。こちらでカスタム位置が無いときは、{ x: 0, y: 0 } の代わりに null を受け付けるようになっています。

// Electron 25 で非推奨
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
  // カスタム位置が無い時。
}

// こちらで置き換えてください
const ret = win.getWindowButtonPosition()
if (ret === null) {
  // カスタム位置が無い時。
}

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

API 変更: nativeImage.createThumbnailFromPath(path, size)​

maxSize 引数は size に変更されました。これに渡されたサイズがサムネイルの作成サイズになります。 以前は、Windows は maxSize より小さいときでは画像を拡大せず、macOS は常にサイズを maxSize にしていました。 この挙動がプラットフォーム間で同じなります。

この動作は以下のように更新されました。

// 128x128 の画像。
const imagePath = path.join('path', 'to', 'capybara.png')

// 小さい画像を拡大します。
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
  console.log(result.getSize()) // { width: 256, height: 256 }
})

// 大きい画像を縮小します。
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
  console.log(result.getSize()) // { width: 64, height: 64 }
})

以前の動作 (Windows 上):

// 128x128 の画像
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 でのドラッグ可能領域​

macOS でのドラッグ可能領域 (CSSプロパティ -webkit-app-region: dragを使用したもの) の実装が、Windows や Linux と同じになるように変更されました。 これまで、-webkit-app-region: no-drag を持つ領域と -webkit-app-region: drag を持つ領域が重なった場合、macOS では CSS のレイヤーに関係なく常に 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 イベント を使用してください。

// Electron 23.0 で削除
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// こちらに置換
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 })

// Electron 23 で削除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// こちらに置換
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

削除: webContents.decrementCapturerCount(stayHidden, stayAwake)​

webContents.decrementCapturerCount(stayHidden, stayAwake) 関数は削除されました。 ページのキャプチャ完了時に webContents.capturePage で自動的に処理されるようになりました。

const w = new BrowserWindow({ show: false })

// Electron 23 で削除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// こちらに置換
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 })

// Electron 23 で削除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// こちらに置換
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

非推奨: webContents.decrementCapturerCount(stayHidden, stayAwake)​

webContents.decrementCapturerCount(stayHidden, stayAwake) は非推奨になります。 ページのキャプチャ完了時に webContents.capturePage で自動的に処理されるようになりました。

const w = new BrowserWindow({ show: false })

// Electron 23 で削除
w.webContents.incrementCapturerCount()
w.capturePage().then(image => {
  console.log(image.toDataURL())
  w.webContents.decrementCapturerCount()
})

// こちらに置換
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

削除: WebContents の new-window イベント​

WebContents の new-window イベントは削除されました。 これは webContents.setWindowOpenHandler() に置き換えられます。

// Electron 22 で削除
webContents.on('new-window', (event) => {
  event.preventDefault()
})

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

削除: <webview> の new-window イベント​

<webview> の new-window イベントは削除されました。 直接の代替機能はありません。

// Electron 22 で削除
webview.addEventListener('new-window', (event) => {})
// こちらで置き換えてください

// 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 イベント を使用してください。

// 非推奨
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// こちらに置換
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 デベロッパー ツールプロトコルの Page.printToPDF に準拠するように変更されました。 これは、上流の変更により以前の実装が維持できなくなりバグが多発したため、それに対応するための変更です。

変更された引数

  • pageRanges

削除された引数

  • printSelectionOnly
  • marginsType
  • headerFooter
  • scaleFactor

追加された引数

  • headerTemplate
  • footerTemplate
  • displayHeaderFooter
  • margins
  • scale
  • preferCSSPageSize
// メインプロセス
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 アプリのデフォルトのセキュリティを改善するためのものです。

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

// メインプロセス
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 をご参照ください。

非推奨: app.runningUnderRosettaTranslation​

app.runningUnderRosettaTranslation プロパティは非推奨になりました。 代わりに app.runningUnderARM64Translation を使用してください。

// 非推奨になりました
console.log(app.runningUnderRosettaTranslation)
// こちらで置き換えてください
console.log(app.runningUnderARM64Translation)

予定されている破壊的な 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.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 の値を持つキーとして表示されるようになりました。

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

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

API 変更: session.setPermissionCheckHandler(handler)​

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

// 古いコード
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() を使用してください。

// Electron 13 で削除
shell.moveItemToTrash(path)
// こちらに置換
shell.trashItem(path).then(/* ... */)

削除: BrowserWindow 拡張機能 API​

以下の非推奨の API が削除されました。

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

代わりに以下の 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' }
})

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

削除: Pepper Flash サポート​

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

省略値変更: 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

削除: 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.start の compress オプションの既定値が 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()

非推奨: shell.moveItemToTrash()​

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

// Electron 12 で削除
shell.moveItemToTrash(path)
// こちらに置換
shell.trashItem(path).then(/* ... */)

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

削除: 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 の値を渡します。

// 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 モジュールに残っている非推奨ではないメソッドは、 extraParameterと 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 は同期になり、任意のコールバックは不要になりました。

// 非推奨
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.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()
// 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 オブジェクト (Element、Location、DOMMatrix など)、内部に C++ のクラスがある Node.js オブジェクト (process.env、Stream のいくつかのメンバーなど)、内部に C++ のクラスがある Electron オブジェクト (WebContents、BrowserWindow、WebFrame など) は、構造化複製ではシリアライズできません。 旧アルゴリズムが呼び出されるたびに、非推奨の警告が出力されます。

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

API 変更: shell.openItem は shell.openPath に​

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

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

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

IPC 経由で送信されるオブジェクトのシリアライズに使用されるアルゴリズム (ipcRenderer.send、ipcRenderer.sendSync、WebContents.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.") を投げる
  • 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)

ネイティブな JS 型ではないオブジェクト、すなわち DOM オブジェクト (Element、Location、DOMMatrix など)、Node.js オブジェクト (process.env、Stream のいくつかのメンバーなど)、Electron オブジェクト (WebContents、BrowserWindow、WebFrame など) のようなものは非推奨です。 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.querySystemIdleState は powerMonitor.getSystemIdleState に​

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

API 変更: powerMonitor.querySystemIdleTime は powerMonitor.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'
  })

削除: getBlinkMemoryInfo の marked プロパティ​

このプロパティは 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.screen が remote を介してアクセスするように​

// 非推奨
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.querySystemIdleState を powerMonitor.getSystemIdleState で置換​

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

非推奨: powerMonitor.querySystemIdleTime を powerMonitor.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)​

省略値変更: nodeIntegration と webviewTag の省略値は false に、contextIsolation の省略値は true に​

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

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

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

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

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

nativeWindowOpen オプションで開かれる子ウインドウは、nodeIntegrationInSubFrames が true でなければ 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.getZoomLevel と webContents.getZoomFactor が同期実行に​

webContents.getZoomLevel と webContents.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 ヘッダー 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.electron と process.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.zip や electron-v1.7.3-linux-armv7l.zip のような少しファイル名が異なる 2 つの同様な ARM ビルドが含まれます。 サポートされている ARM バージョンをユーザに明確にし、将来作成される armv6l および arm64 アセットらと明確にするために、v7l という接頭子を持つアセットが追加されました。

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

詳細は、6986 と 7189 を参照してください。