破壊的変更
破壊的な変更は変更の 一つ前のメジャーバージョン についてここに文書化され、可能であれば非推奨の警告を JS コードに加えます。
破壊的変更の種別
このドキュメントでは、以下の規約によって破壊的な変更を分類しています。
- API 変更: 古いコードで例外の発生が保証されるように API が変更されました。
- 動作変更: Electron の動作が変更されましたが、例外が必ず発生する訳ではありません。
- 省略値変更: 古い省略値に依存するコードは動かなくなるかもしれませんが、必ずしも例外は発生しません。 値を明示することで以前の動作に戻すことができます。
- 非推奨: API は非推奨になりました。 この API は引き続き機能しますが、非推奨の警告を発し、将来のリリースで削除されます。
- 削除: API または機能が削除され、Electron でサポートされなくなりました。
予定されている破壊的な API の変更 (28.0)
Behavior Changed: WebContents.backgroundThrottling
set to false affects all WebContents
in the host BrowserWindow
WebContents.backgroundThrottling
set to false will disable frames throttling in the BrowserWindow
for all WebContents
displayed by it.
削除: BrowserWindow.setTrafficLightPosition(position)
BrowserWindow.setTrafficLightPosition(position)
has been removed, the BrowserWindow.setWindowButtonPosition(position)
API should be used instead which accepts null
instead of { x: 0, y: 0 }
to reset the position to system default.
// 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()
has been removed, the BrowserWindow.getWindowButtonPosition()
API should be used instead which returns null
instead of { x: 0, y: 0 }
when there is no custom position.
// Removed in Electron 28
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
// No custom position.
}
// こちらで置き換えてください
const ret = win.getWindowButtonPosition()
if (ret === null) {
// カスタム位置が無い時。
}
削除: ipcRenderer.sendTo()
The ipcRenderer.sendTo()
API has been removed. これは、レンダラー間で MessageChannel
を設定するように置き換える必要があります。
The senderId
and senderIsMainFrame
properties of IpcRendererEvent
have been removed as well.
削除: app.runningUnderRosettaTranslation
The app.runningUnderRosettaTranslation
property has been removed. 代わりに app.runningUnderARM64Translation
を使用してください。
// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)
Deprecated: renderer-process-crashed
event on app
The renderer-process-crashed
event on app
has been deprecated. Use the new render-process-gone
event instead.
// Deprecated
app.on('renderer-process-crashed', (event, webContents, killed) => { /* ... */ })
// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })
Deprecated: params.inputFormType
property on context-menu
on WebContents
The inputFormType
property of the params object in the context-menu
event from WebContents
has been deprecated. Use the new formControlType
property instead.
Deprecated: crashed
event on WebContents
and <webview>
The crashed
events on WebContents
and <webview>
have been deprecated. Use the new render-process-gone
event instead.
// 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) => { /* ... */ })
Deprecated: gpu-process-crashed
event on app
The gpu-process-crashed
event on app
has been deprecated. Use the new child-process-gone
event instead.
// 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-changed
high-contrast-color-scheme-changed
代わりに nativeTheme
の新しいイベントである updated
を使用してください。
// 削除されました
systemPreferences.on('inverted-color-scheme-changed', () => { /* ... */ })
systemPreferences.on('high-contrast-color-scheme-changed', () => { /* ... */ })
// こちらで置き換えてください
nativeTheme.on('updated', () => { /* ... */ })
削除: 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.{register,intercept}{Buffer,String,Stream,File,Http}Protocol
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()
#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()
に
// 非推奨
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
オプションの初期値は、以下の記載された新しい初期値のために非推奨になっています。
属性 | 非推奨の初期値 | 新しい初期値 |
---|---|---|
contextIsolation | false | true |
nodeIntegration | true | false |
webviewTag | nodeIntegration を設定しなければ true | false |
以下は例です。 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
// 削除されました
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 からは、接頭子のないファイルは公開されなくなりました。