重大變更

重大變更將在此處記錄，並且在 JS 程式碼中盡可能新增棄用警告，至少在變更實施前的一個主要版本。

重大變更的類型

本文檔使用以下慣例來分類重大變更

API 已變更： API 已變更，以至於未更新的程式碼保證會擲回例外。
行為已變更： Electron 的行為已變更，但並非一定會擲回例外的程度。
預設值已變更： 依賴舊預設值的程式碼可能會中斷，不一定會擲回例外。可以透過明確指定值來還原舊行為。
已棄用： API 已標記為已棄用。API 將繼續運作，但會發出棄用警告，並將在未來的版本中移除。
已移除： API 或功能已移除，且 Electron 不再支援。

計劃中的重大 API 變更 (35.0)

行為已變更：Linux 上 Dialog API 的 `defaultPath` 選項

在 Linux 上，檔案對話框所需的 portal 版本已從 4 還原為 3。除非 portal 後端為 4 或更高版本，否則使用 portal 檔案選擇器對話框時，不支援 Dialog API 的 defaultPath 選項。可以使用 --xdg-portal-required-version 命令列參數來強制應用程式所需的版本。請參閱 #44426 以取得更多詳細資訊。

已棄用：`Session` 上的 `setPreloads`、`getPreloads`

引入了 registerPreloadScript、unregisterPreloadScript 和 getPreloadScripts 作為已棄用方法的替代方案。這些新的 API 允許第三方函式庫註冊 preload 腳本，而無需取代現有的腳本。此外，新的 type 選項允許超出 frame 的其他 preload 目標。

// Deprecated
session.setPreloads([path.join(__dirname, 'preload.js')])

// Replace with:
session.registerPreloadScript({
  type: 'frame',
  id: 'app-preload',
  filePath: path.join(__dirname, 'preload.js')
})

已棄用：`session.serviceWorkers` 上的 `getFromVersionID`

session.serviceWorkers.fromVersionID(versionId) API 已被棄用，改用 session.serviceWorkers.getInfoFromVersionID(versionId)。此變更是為了更清楚地表明傳回哪個物件，同時引入了 session.serviceWorkers.getWorkerFromVersionID(versionId) API。

// Deprecated
session.serviceWorkers.fromVersionID(versionId)

// Replace with
session.serviceWorkers.getInfoFromVersionID(versionId)

已棄用：`WebContents` 上 `console-message` 事件中的 `level`、`message`、`line` 和 `sourceId` 引數

WebContents 上的 console-message 事件已更新，以提供有關 Event 引數的詳細資訊。

// Deprecated
webContents.on('console-message', (event, level, message, line, sourceId) => {})

// Replace with:
webContents.on('console-message', ({ level, message, lineNumber, sourceId, frame }) => {})

此外，level 現在是一個字串，可能的值為 info、warning、error 和 debug。

行為已變更：`WebRequestFilter` 的 `urls` 屬性。

先前，空的 urls 陣列被解釋為包含所有 URL。若要明確包含所有 URL，開發人員現在應使用 <all_urls> 模式，這是一個指定的 URL 模式，符合每個可能的 URL。此變更闡明了意圖並確保更可預測的行為。

// Deprecated
const deprecatedFilter = {
  urls: []
}

// Replace with
const newFilter = {
  urls: ['<all_urls>']
}

已棄用：`systemPreferences.isAeroGlassEnabled()`

systemPreferences.isAeroGlassEnabled() 函式已被棄用，沒有替代方案。自 Electron 23 以來，它一直傳回 true，僅支援 Windows 10+，在其中 DWM 合成不再能被停用。

https://learn.microsoft.com/en-us/windows/win32/dwm/composition-ovw#disabling-dwm-composition-windows7-and-earlier

計劃中的重大 API 變更 (34.0)

這使行為與 Linux 相同。先前行為：在 Windows 上全螢幕期間，選單列仍然可見。新行為：在 Windows 上全螢幕期間，選單列會隱藏。

更正：先前在 Electron 33 中將其列為重大變更，但實際上首次發佈於 Electron 34。

計劃中的重大 API 變更 (33.0)

已棄用：`document.execCommand("paste")`

同步剪貼簿讀取 API document.execCommand("paste") 已被棄用，改用非同步剪貼簿 API。這是為了與瀏覽器預設值對齊。

WebPreferences 上的 enableDeprecatedPaste 選項（會觸發此 API 的權限檢查）以及相關的權限類型 deprecated-sync-clipboard-read 也已棄用。

行為已變更：框架屬性可能會擷取已分離的 WebFrameMain 實例，或完全不擷取

提供對 WebFrameMain 實例存取的 API 可能會傳回 frame.detached 設定為 true 的實例，或可能傳回 null。

當框架執行跨來源導航時，它會進入分離狀態，在此狀態下，它不再附加到頁面。在此狀態下，它可能會在刪除之前執行 unload 處理常式。如果在這種狀態下傳送 IPC，frame.detached 將設定為 true，並且框架將在不久後銷毀。

接收事件時，立即存取接收到的 WebFrameMain 屬性非常重要。否則，不保證它指向與接收時相同的網頁。為了避免錯位的期望，在延遲存取且網頁已變更的情況下，Electron 將傳回 null。

ipcMain.on('unload-event', (event) => {
  event.senderFrame // ✅ accessed immediately
})

ipcMain.on('unload-event', async (event) => {
  await crossOriginNavigationPromise
  event.senderFrame // ❌ returns `null` due to late access
})

行為已變更：Windows 上的自訂協定 URL 處理

由於 Chromium 中為支援非特殊架構 URL 所做的變更，使用 Windows 檔案路徑的自訂協定 URL 將不再與已棄用的 protocol.registerFileProtocol 以及 BrowserWindow.loadURL、WebContents.loadURL 和 <webview>.loadURL 上的 baseURLForDataURL 屬性正確運作。protocol.handle 也無法與這些類型的 URL 搭配使用，但這並非變更，因為它一直都是這樣運作的。

// No longer works
protocol.registerFileProtocol('other', () => {
  callback({ filePath: '/path/to/my/file' })
})

const mainWindow = new BrowserWindow()
mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://C:\\myapp' })
mainWindow.loadURL('other://C:\\myapp\\index.html')

// Replace with
const path = require('node:path')
const nodeUrl = require('node:url')
protocol.handle(other, (req) => {
  const srcPath = 'C:\\myapp\\'
  const reqURL = new URL(req.url)
  return net.fetch(nodeUrl.pathToFileURL(path.join(srcPath, reqURL.pathname)).toString())
})

mainWindow.loadURL('data:text/html,<script src="loaded-from-dataurl.js"></script>', { baseURLForDataURL: 'other://' })
mainWindow.loadURL('other://index.html')

行為已變更：`app` 上 `login` 的 `webContents` 屬性

當從使用 respondToAuthRequestsFromMainProcess 選項建立的 utility 程序提出的請求觸發 login 事件時，app 中 login 事件的 webContents 屬性將為 null。

已棄用：`BrowserWindowConstructorOption.type` 中的 `textured` 選項

BrowserWindowConstructorOptions 中 type 的 textured 選項已被棄用，沒有替代方案。此選項依賴於 macOS 上的 NSWindowStyleMaskTexturedBackground 樣式遮罩，該遮罩已被棄用，沒有替代方案。

已移除：macOS 10.15 支援

Chromium 不再支援 macOS 10.15 (Catalina)。

舊版本的 Electron 將繼續在 Catalina 上執行，但執行 Electron v33.0.0 及更高版本將需要 macOS 11 (Big Sur) 或更高版本。

行為已變更：原生模組現在需要 C++20

由於上游所做的變更，V8 和 Node.js 現在都要求 C++20 作為最低版本。使用原生節點模組的開發人員應使用 --std=c++20 而非 --std=c++17 來建置其模組。使用 gcc9 或更低版本的映像可能需要更新至 gcc10 才能編譯。請參閱 #43555 以取得更多詳細資訊。

已棄用：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

systemPreferences.accessibilityDisplayShouldReduceTransparency 屬性現在已被棄用，改用新的 nativeTheme.prefersReducedTransparency，後者提供相同的資訊並且跨平台運作。

// Deprecated
const shouldReduceTransparency = systemPreferences.accessibilityDisplayShouldReduceTransparency

// Replace with:
const prefersReducedTransparency = nativeTheme.prefersReducedTransparency

計劃中的重大 API 變更 (32.0)

已移除：`File.path`

Web File 物件的非標準 path 屬性在早期版本的 Electron 中新增，作為在渲染器中執行所有操作時使用原生檔案的便利方法。然而，它代表偏離標準，並且也構成輕微的安全風險，因此從 Electron 32.0 開始，它已被移除，改用 webUtils.getPathForFile 方法。

// Before (renderer)

const file = document.querySelector('input[type=file]').files[0]
alert(`Uploaded file path was: ${file.path}`)

// After (renderer)

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

// (preload)
const { contextBridge, webUtils } = require('electron')

contextBridge.exposeInMainWorld('electron', {
  showFilePath (file) {
    // It's best not to expose the full file path to the web content if
    // possible.
    const path = webUtils.getPathForFile(file)
    alert(`Uploaded file path was: ${path}`)
  }
})

已棄用：`WebContents` 上的 `clearHistory`、`canGoBack`、`goBack`、`canGoForward`、`goForward`、`goToIndex`、`canGoToOffset`、`goToOffset`

與導航相關的 API 現在已棄用。

這些 API 已移至 WebContents 的 navigationHistory 屬性，以便為管理導航歷史記錄提供更結構化且直觀的介面。

// Deprecated
win.webContents.clearHistory()
win.webContents.canGoBack()
win.webContents.goBack()
win.webContents.canGoForward()
win.webContents.goForward()
win.webContents.goToIndex(index)
win.webContents.canGoToOffset()
win.webContents.goToOffset(index)

// Replace with
win.webContents.navigationHistory.clear()
win.webContents.navigationHistory.canGoBack()
win.webContents.navigationHistory.goBack()
win.webContents.navigationHistory.canGoForward()
win.webContents.navigationHistory.goForward()
win.webContents.navigationHistory.canGoToOffset()
win.webContents.navigationHistory.goToOffset(index)

行為已變更：`userData` 中的目錄 `databases` 將被刪除

如果您在 app.getPath('userData') 傳回的目錄中有名為 databases 的目錄，則在首次執行 Electron 32 時將會刪除它。databases 目錄由 WebSQL 使用，WebSQL 已在 Electron 31 中移除。Chromium 現在執行清除以刪除此目錄。請參閱 issue #45396。

計劃中的重大 API 變更 (31.0)

已移除：`WebSQL` 支援

Chromium 已在上游移除對 WebSQL 的支援，將其轉換為僅限 Android。請參閱 Chromium 的移除意圖討論以取得更多資訊。

行為已變更：`nativeImage.toDataURL` 將保留 PNG 色彩空間

PNG 解碼器實作已變更為保留色彩空間資料，從此函式傳回的編碼資料現在與其相符。

請參閱 crbug.com/332584706 以取得更多資訊。

行為已變更：macOS 上的 `window.flashFrame(bool)` 將持續閃爍 dock 圖示

這使行為與 Windows 和 Linux 相同。先前行為：第一個 flashFrame(true) 只會彈跳 dock 圖示一次（使用 NSInformationalRequest 層級），而 flashFrame(false) 則不執行任何操作。新行為：持續閃爍，直到呼叫 flashFrame(false) 為止。這改為使用 NSCriticalRequest 層級。若要明確使用 NSInformationalRequest 以造成單次 dock 圖示彈跳，仍然可以使用 dock.bounce('informational')。

計劃中的重大 API 變更 (30.0)

行為已變更：跨來源 iframe 現在使用權限策略來存取功能

跨來源 iframe 現在必須透過 allow 屬性指定給定 iframe 可用的功能，才能存取這些功能。

請參閱文件以取得更多資訊。

已移除：`--disable-color-correct-rendering` 參數

此參數從未正式記錄在案，但此處仍記錄其移除。Chromium 本身現在對色彩空間有更好的支援，因此不應需要此旗標。

行為已變更：macOS 上的 `BrowserView.setAutoResize` 行為

在 Electron 30 中，BrowserView 現在是新 WebContentsView API 的包裝函式。

先前，BrowserView API 的 setAutoResize 函式由 macOS 上的 autoresizing 以及 Windows 和 Linux 上的自訂演算法支援。對於簡單的用例，例如使 BrowserView 填滿整個視窗，這兩種方法的行為是相同的。但是，在更進階的情況下，BrowserView 在 macOS 上的自動調整大小方式與在其他平台上的方式不同，因為 Windows 和 Linux 的自訂調整大小演算法與 macOS 的自動調整大小 API 的行為並不完全匹配。自動調整大小行為現在已在所有平台上標準化。

如果您的應用程式使用 BrowserView.setAutoResize 來執行比使 BrowserView 填滿整個視窗更複雜的操作，則您可能已經有自訂邏輯來處理 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` 傳送

嘗試透過 contextBridge 將整個 ipcRenderer 模組作為物件傳送，現在將導致橋接器的接收端出現空物件。此變更是為了移除/減輕安全隱患。您不應透過橋接器直接公開 ipcRenderer 或其方法。而是提供如下所示的安全包裝函式

contextBridge.exposeInMainWorld('app', {
  onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
})

已移除：`app` 上的 `renderer-process-crashed` 事件

已移除 app 上的 renderer-process-crashed 事件。請改用新的 render-process-gone 事件。

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

// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

已移除：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已移除 WebContents 和 <webview> 上的 crashed 事件。請改用新的 render-process-gone 事件。

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

// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })

已移除：`app` 上的 `gpu-process-crashed` 事件

已移除 app 上的 gpu-process-crashed 事件。請改用新的 child-process-gone 事件。

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

// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })

計劃中的重大 API 變更 (28.0)

行為已變更：設定為 false 的 `WebContents.backgroundThrottling` 會影響主機 `BrowserWindow` 中的所有 `WebContents`

設定為 false 的 WebContents.backgroundThrottling 將停用 BrowserWindow 中顯示的所有 WebContents 的框架節流。

已移除：`BrowserWindow.setTrafficLightPosition(position)`

已移除 BrowserWindow.setTrafficLightPosition(position)，應改用 BrowserWindow.setWindowButtonPosition(position) API，後者接受 null 而非 { x: 0, y: 0 } 以將位置重設為系統預設值。

// Removed in Electron 28
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })

// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)

已移除：`BrowserWindow.getTrafficLightPosition()`

已移除 BrowserWindow.getTrafficLightPosition()，應改用 BrowserWindow.getWindowButtonPosition() API，後者在沒有自訂位置時傳回 null 而非 { x: 0, y: 0 }。

// Removed in Electron 28
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
  // No custom position.
}

// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
  // No custom position.
}

已移除：`ipcRenderer.sendTo()`

已移除 ipcRenderer.sendTo() API。應透過在渲染器之間設定 MessageChannel 來取代它。

IpcRendererEvent 的 senderId 和 senderIsMainFrame 屬性也已移除。

已移除：`app.runningUnderRosettaTranslation`

已移除 app.runningUnderRosettaTranslation 屬性。請改用 app.runningUnderARM64Translation。

// Removed
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)

已棄用：`app` 上的 `renderer-process-crashed` 事件

已棄用 app 上的 renderer-process-crashed 事件。請改用新的 render-process-gone 事件。

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

// Replace with
app.on('render-process-gone', (event, webContents, details) => { /* ... */ })

已棄用：`WebContents` 上 `context-menu` 的 `params.inputFormType` 屬性

已棄用來自 WebContents 的 context-menu 事件中 params 物件的 inputFormType 屬性。請改用新的 formControlType 屬性。

已棄用：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已棄用 WebContents 和 <webview> 上的 crashed 事件。請改用新的 render-process-gone 事件。

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

// Replace with
win.webContents.on('render-process-gone', (event, details) => { /* ... */ })
webview.addEventListener('render-process-gone', (event) => { /* ... */ })

已棄用：`app` 上的 `gpu-process-crashed` 事件

已棄用 app 上的 gpu-process-crashed 事件。請改用新的 child-process-gone 事件。

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

// Replace with
app.on('child-process-gone', (event, details) => { /* ... */ })

計劃中的重大 API 變更 (27.0)

已移除：macOS 10.13 / 10.14 支援

Chromium 不再支援 macOS 10.13 (High Sierra) 和 macOS 10.14 (Mojave)。

舊版本的 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 事件。

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

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

已移除：macOS 上的一些 `window.setVibrancy` 選項

已移除以下 vibrancy 選項

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

這些選項先前已棄用，並已由 Apple 在 10.15 中移除。

已移除：`webContents.getPrinters`

已移除 webContents.getPrinters 方法。請改用 webContents.getPrintersAsync。

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

// Removed
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

已移除：`systemPreferences.{get,set}AppLevelAppearance` 和 `systemPreferences.appLevelAppearance`

已移除 systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 方法，以及 systemPreferences.appLevelAppearance 屬性。請改用 nativeTheme 模組。

// Removed
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors

// Removed
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors

// Removed
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'

已移除：`systemPreferences.getColor` 的 `alternate-selected-control-text` 值

已移除 systemPreferences.getColor 的 alternate-selected-control-text 值。請改用 selected-content-background。

// Removed
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')

計劃中的重大 API 變更 (26.0)

已棄用：`webContents.getPrinters`

已棄用 webContents.getPrinters 方法。請改用 webContents.getPrintersAsync。

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

// Deprecated
console.log(w.webContents.getPrinters())
// Replace with
w.webContents.getPrintersAsync().then((printers) => {
  console.log(printers)
})

已棄用：`systemPreferences.{get,set}AppLevelAppearance` 和 `systemPreferences.appLevelAppearance`

已棄用 systemPreferences.getAppLevelAppearance 和 systemPreferences.setAppLevelAppearance 方法，以及 systemPreferences.appLevelAppearance 屬性。請改用 nativeTheme 模組。

// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'

已棄用：`systemPreferences.getColor` 的 `alternate-selected-control-text` 值

已棄用 systemPreferences.getColor 的 alternate-selected-control-text 值。請改用 selected-content-background。

// Deprecated
systemPreferences.getColor('alternate-selected-control-text')
// Replace with
systemPreferences.getColor('selected-content-background')

計劃中的重大 API 變更 (25.0)

已棄用：`protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` 和 `protocol.isProtocol{Registered,Intercepted}`

protocol.register*Protocol 和 protocol.intercept*Protocol 方法已被 protocol.handle 取代。

新方法可以註冊新的協定或攔截現有的協定，並且回應可以是任何類型。

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

// Replace with
protocol.handle('some-protocol', () => {
  return new Response(
    Buffer.from('<h5>Response</h5>'), // Could also be a string or ReadableStream.
    { headers: { 'content-type': 'text/html' } }
  )
})

// Deprecated in Electron 25
protocol.registerHttpProtocol('some-protocol', () => {
  callback({ url: 'https://electron.dev.org.tw' })
})

// Replace with
protocol.handle('some-protocol', () => {
  return net.fetch('https://electron.dev.org.tw')
})

// Deprecated in Electron 25
protocol.registerFileProtocol('some-protocol', () => {
  callback({ filePath: '/path/to/my/file' })
})

// Replace with
protocol.handle('some-protocol', () => {
  return net.fetch('file:///path/to/my/file')
})

已棄用：`BrowserWindow.setTrafficLightPosition(position)`

已棄用 BrowserWindow.setTrafficLightPosition(position)，應改用 BrowserWindow.setWindowButtonPosition(position) API，後者接受 null 而非 { x: 0, y: 0 } 以將位置重設為系統預設值。

// Deprecated in Electron 25
win.setTrafficLightPosition({ x: 10, y: 10 })
win.setTrafficLightPosition({ x: 0, y: 0 })

// Replace with
win.setWindowButtonPosition({ x: 10, y: 10 })
win.setWindowButtonPosition(null)

已棄用：`BrowserWindow.getTrafficLightPosition()`

已棄用 BrowserWindow.getTrafficLightPosition()，應改用 BrowserWindow.getWindowButtonPosition() API，後者在沒有自訂位置時傳回 null 而非 { x: 0, y: 0 }。

// Deprecated in Electron 25
const pos = win.getTrafficLightPosition()
if (pos.x === 0 && pos.y === 0) {
  // No custom position.
}

// Replace with
const ret = win.getWindowButtonPosition()
if (ret === null) {
  // No custom position.
}

計劃中的重大 API 變更 (24.0)

API 已變更：`nativeImage.createThumbnailFromPath(path, size)`

maxSize 參數已變更為 size，以反映傳入的大小將是建立的縮圖的大小。先前，如果映像小於 maxSize，Windows 將不會放大映像，而 macOS 將始終將大小設定為 maxSize。現在，跨平台的行為相同。

更新的行為

// a 128x128 image.
const imagePath = path.join('path', 'to', 'capybara.png')

// Scaling up a smaller image.
const upSize = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, upSize).then(result => {
  console.log(result.getSize()) // { width: 256, height: 256 }
})

// Scaling down a larger image.
const downSize = { width: 64, height: 64 }
nativeImage.createThumbnailFromPath(imagePath, downSize).then(result => {
  console.log(result.getSize()) // { width: 64, height: 64 }
})

先前的行為 (在 Windows 上)

// a 128x128 image
const imagePath = path.join('path', 'to', 'capybara.png')
const size = { width: 256, height: 256 }
nativeImage.createThumbnailFromPath(imagePath, size).then(result => {
  console.log(result.getSize()) // { width: 128, height: 128 }
})

計劃性重大 API 變更 (23.0)

行為變更：macOS 上的可拖曳區域

macOS 上可拖曳區域（使用 CSS 屬性 -webkit-app-region: drag）的實作方式已變更，以使其與 Windows 和 Linux 一致。先前，當具有 -webkit-app-region: no-drag 的區域與具有 -webkit-app-region: drag 的區域重疊時，無論 CSS 圖層為何，no-drag 區域在 macOS 上始終優先。也就是說，如果 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 將繼續在這些作業系統上執行，但需要 Windows 10 或更高版本才能執行 Electron v23.0.0 及更高版本。

已移除：BrowserWindow `scroll-touch-*` 事件

BrowserWindow 上已棄用的 scroll-touch-begin、scroll-touch-end 和 scroll-touch-edge 事件已被移除。請改為使用 WebContents 上新提供的 input-event 事件。

// Removed in Electron 23.0
win.on('scroll-touch-begin', scrollTouchBegin)
win.on('scroll-touch-edge', scrollTouchEdge)
win.on('scroll-touch-end', scrollTouchEnd)

// Replace with
win.webContents.on('input-event', (_, event) => {
  if (event.type === 'gestureScrollBegin') {
    scrollTouchBegin()
  } else if (event.type === 'gestureScrollUpdate') {
    scrollTouchEdge()
  } else if (event.type === 'gestureScrollEnd') {
    scrollTouchEnd()
  }
})

已移除：`webContents.incrementCapturerCount(stayHidden, stayAwake)`

webContents.incrementCapturerCount(stayHidden, stayAwake) 函數已被移除。現在當頁面擷取完成時，會由 webContents.capturePage 自動處理。

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

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

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已移除：`webContents.decrementCapturerCount(stayHidden, stayAwake)`

webContents.decrementCapturerCount(stayHidden, stayAwake) 函數已被移除。現在當頁面擷取完成時，會由 webContents.capturePage 自動處理。

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

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

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

計劃性重大 API 變更 (22.0)

已棄用：`webContents.incrementCapturerCount(stayHidden, stayAwake)`

webContents.incrementCapturerCount(stayHidden, stayAwake) 已被棄用。現在當頁面擷取完成時，會由 webContents.capturePage 自動處理。

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

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

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已棄用：`webContents.decrementCapturerCount(stayHidden, stayAwake)`

webContents.decrementCapturerCount(stayHidden, stayAwake) 已被棄用。現在當頁面擷取完成時，會由 webContents.capturePage 自動處理。

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

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

// Replace with
w.capturePage().then(image => {
  console.log(image.toDataURL())
})

已移除：WebContents `new-window` 事件

WebContents 的 new-window 事件已被移除。它已被 webContents.setWindowOpenHandler() 取代。

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

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

已移除：`<webview>` `new-window` 事件

<webview> 的 new-window 事件已被移除。沒有直接的替代方案。

// Removed in Electron 22
webview.addEventListener('new-window', (event) => {})

// Replace with

// main.js
mainWindow.webContents.on('did-attach-webview', (event, wc) => {
  wc.setWindowOpenHandler((details) => {
    mainWindow.webContents.send('webview-new-window', wc.id, details)
    return { action: 'deny' }
  })
})

// preload.js
const { ipcRenderer } = require('electron')
ipcRenderer.on('webview-new-window', (e, webContentsId, details) => {
  console.log('webview-new-window', webContentsId, details)
  document.getElementById('webview').dispatchEvent(new Event('new-window'))
})

// renderer.js
document.getElementById('webview').addEventListener('new-window', () => {
  console.log('got new-window event')
})

已棄用：BrowserWindow `scroll-touch-*` 事件

BrowserWindow 上的 scroll-touch-begin、scroll-touch-end 和 scroll-touch-edge 事件已被棄用。請改為使用 WebContents 上新提供的 input-event 事件。

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

// Replace with
win.webContents.on('input-event', (_, event) => {
  if (event.type === 'gestureScrollBegin') {
    scrollTouchBegin()
  } else if (event.type === 'gestureScrollUpdate') {
    scrollTouchEdge()
  } else if (event.type === 'gestureScrollEnd') {
    scrollTouchEnd()
  }
})

計劃性重大 API 變更 (21.0)

行為變更：已啟用 V8 Memory Cage

V8 memory cage 已啟用，這對使用 ArrayBuffer 或 Buffer 包裝非 V8 記憶體的原生模組產生影響。有關更多詳細資訊，請參閱關於 V8 memory cage 的部落格文章。

API 變更：`webContents.printToPDF()`

webContents.printToPDF() 已修改為符合 Chrome DevTools Protocol 中的 Page.printToPDF。此變更是為了解決上游的變更，這些變更使得我們先前的實作變得難以維持且充滿錯誤。

參數變更

pageRanges

參數已移除

printSelectionOnly
marginsType
headerFooter
scaleFactor

參數已新增

headerTemplate
footerTemplate
displayHeaderFooter
margins
scale
preferCSSPageSize

// Main process
const { webContents } = require('electron')

webContents.printToPDF({
  landscape: true,
  displayHeaderFooter: true,
  printBackground: true,
  scale: 2,
  pageSize: 'Ledger',
  margins: {
    top: 2,
    bottom: 2,
    left: 2,
    right: 2
  },
  pageRanges: '1-5, 8, 11-13',
  headerTemplate: '<h1>Title</h1>',
  footerTemplate: '<div><span class="pageNumber"></span></div>',
  preferCSSPageSize: true
}).then(data => {
  fs.writeFile(pdfPath, data, (error) => {
    if (error) throw error
    console.log(`Wrote PDF successfully to ${pdfPath}`)
  })
}).catch(error => {
  console.log(`Failed to write PDF to ${pdfPath}: `, error)
})

計劃性重大 API 變更 (20.0)

已移除：macOS 10.11 / 10.12 支援

macOS 10.11 (El Capitan) 和 macOS 10.12 (Sierra) 不再受 Chromium 支援。

舊版本的 Electron 將繼續在這些作業系統上執行，但需要 macOS 10.13 (High Sierra) 或更高版本才能執行 Electron v20.0.0 及更高版本。

預設變更：沒有 `nodeIntegration: true` 的渲染器預設為沙盒化

先前，指定預載腳本的渲染器預設為非沙盒化。這表示預設情況下，預載腳本可以存取 Node.js。在 Electron 20 中，此預設值已變更。從 Electron 20 開始，除非指定 nodeIntegration: true 或 sandbox: false，否則渲染器預設為沙盒化。

如果您的預載腳本不依賴 Node，則無需採取任何動作。如果您的預載腳本確實依賴 Node，請重新架構它們以從渲染器中移除 Node 使用，或為相關渲染器明確指定 sandbox: false。

已移除：Linux 上的 `skipTaskbar`

在 X11 上，skipTaskbar 會向 X11 視窗管理器發送 _NET_WM_STATE_SKIP_TASKBAR 訊息。Wayland 沒有直接的等效功能，而且已知的工作區間具有不可接受的權衡（例如，GNOME 中的 Window.is_skip_taskbar 需要不安全模式），因此 Electron 無法在 Linux 上支援此功能。

API 變更：`session.setDevicePermissionHandler(handler)`

使用 session.setDevicePermissionHandler(handler) 時調用的處理常式，其參數已變更。此處理常式不再傳遞 frame WebFrameMain，而是傳遞 origin，即正在檢查裝置權限的來源。

計劃性重大 API 變更 (19.0)

已移除：IA32 Linux 二進制檔案

這是 Chromium 102.0.4999.0 停止支援 IA32 Linux 的結果。這結束了移除對 IA32 Linux 的支援。

計劃性重大 API 變更 (18.0)

已移除：`nativeWindowOpen`

在 Electron 15 之前，window.open 預設會被墊片以使用 BrowserWindowProxy。這表示 window.open('about:blank') 無法開啟同步可腳本化的子視窗，以及其他不相容性。自 Electron 15 以來，預設已啟用 nativeWindowOpen。

有關更多詳細資訊，請參閱 Electron 中的 window.open 的文件。

計劃性重大 API 變更 (17.0)

已移除：渲染器中的 `desktopCapturer.getSources`

desktopCapturer.getSources API 現在僅在主處理程序中可用。此變更是為了提高 Electron 應用程式的預設安全性。

如果您需要此功能，可以按如下方式取代它

// Main process
const { ipcMain, desktopCapturer } = require('electron')

ipcMain.handle(
  'DESKTOP_CAPTURER_GET_SOURCES',
  (event, opts) => desktopCapturer.getSources(opts)
)

// Renderer process
const { ipcRenderer } = require('electron')

const desktopCapturer = {
  getSources: (opts) => ipcRenderer.invoke('DESKTOP_CAPTURER_GET_SOURCES', opts)
}

但是，您應該考慮進一步限制返回給渲染器的資訊；例如，向使用者顯示來源選擇器，並且僅返回選定的來源。

已棄用：`nativeWindowOpen`

有關更多詳細資訊，請參閱 Electron 中的 window.open 的文件。

計劃性重大 API 變更 (16.0)

行為變更：`crashReporter` 實作已切換到 Linux 上的 Crashpad

Linux 上 crashReporter API 的底層實作已從 Breakpad 變更為 Crashpad，使其與 Windows 和 Mac 一致。因此，現在會自動監控子處理程序，並且不再需要在 Node 子處理程序中呼叫 process.crashReporter.start（也不建議這樣做，因為這會啟動 Crashpad 報告器的第二個實例）。

Linux 上註解的報告方式也存在一些細微的變更，包括長值將不再在附加了 __1、__2 等的註解之間分割，而是會在（新的、更長的）註解值限制處截斷。

已棄用：渲染器中的 `desktopCapturer.getSources`

已棄用在渲染器中使用 desktopCapturer.getSources API，並且將會移除。此變更提高了 Electron 應用程式的預設安全性。

有關如何在您的應用程式中取代此 API 的詳細資訊，請參閱此處。

計劃性重大 API 變更 (15.0)

預設變更：`nativeWindowOpen` 預設為 `true`

在 Electron 15 之前，window.open 預設會被墊片以使用 BrowserWindowProxy。這表示 window.open('about:blank') 無法開啟同步可腳本化的子視窗，以及其他不相容性。nativeWindowOpen 不再是實驗性的，現在是預設值。

有關更多詳細資訊，請參閱 Electron 中的 window.open 的文件。

已棄用：`app.runningUnderRosettaTranslation`

app.runningUnderRosettaTranslation 屬性已被棄用。請改用 app.runningUnderARM64Translation。

// Deprecated
console.log(app.runningUnderRosettaTranslation)
// Replace with
console.log(app.runningUnderARM64Translation)

計劃性重大 API 變更 (14.0)

已移除：`remote` 模組

remote 模組已在 Electron 12 中棄用，並將在 Electron 14 中移除。它已被 @electron/remote 模組取代。

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote

// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

已移除：`app.allowRendererProcessReuse`

app.allowRendererProcessReuse 屬性將被移除，作為我們更緊密地與 Chromium 的處理程序模型保持一致以提高安全性、效能和可維護性的計劃的一部分。

有關更多詳細資訊，請參閱 #18397。

已移除：瀏覽器視窗親和性

在建構新的 BrowserWindow 時，affinity 選項將被移除，作為我們更緊密地與 Chromium 的處理程序模型保持一致以提高安全性、效能和可維護性的計劃的一部分。

有關更多詳細資訊，請參閱 #18397。

API 變更：`window.open()`

可選參數 frameName 將不再設定視窗的標題。現在，這遵循原生文件中對應參數 windowName 所述的規範。

如果您使用此參數來設定視窗的標題，則可以改用 win.setTitle(title)。

已移除：`worldSafeExecuteJavaScript`

在 Electron 14 中，worldSafeExecuteJavaScript 將被移除。沒有替代方案，請確保您的程式碼在此屬性啟用時可以運作。自 Electron 12 以來，它已預設為啟用。

如果您使用 webFrame.executeJavaScript 或 webFrame.executeJavaScriptInIsolatedWorld，您將會受到此變更的影響。您需要確保這些方法返回的值受到 Context Bridge API 的支援，因為這些方法使用相同的值傳遞語義。

已移除：BrowserWindowConstructorOptions 從父視窗繼承

在 Electron 14 之前，使用 window.open 開啟的視窗將從其父視窗繼承 BrowserWindow 建構函式選項，例如 transparent 和 resizable。從 Electron 14 開始，此行為已移除，並且視窗將不再從其父視窗繼承任何 BrowserWindow 建構函式選項。

請改為使用 setWindowOpenHandler 明確設定新視窗的選項

webContents.setWindowOpenHandler((details) => {
  return {
    action: 'allow',
    overrideBrowserWindowOptions: {
      // ...
    }
  }
})

已移除：`additionalFeatures`

WebContents 的 new-window 和 did-create-window 事件中已棄用的 additionalFeatures 屬性已被移除。由於 new-window 使用位置引數，因此該引數仍然存在，但始終為空陣列 []。（但請注意，new-window 事件本身已被棄用，並且已被 setWindowOpenHandler 取代。）視窗功能中的裸金鑰現在將在選項物件中顯示為值為 true 的金鑰。

// Removed in Electron 14
// Triggered by window.open('...', '', 'my-key')
webContents.on('did-create-window', (window, details) => {
  if (details.additionalFeatures.includes('my-key')) {
    // ...
  }
})

// Replace with
webContents.on('did-create-window', (window, details) => {
  if (details.options['my-key']) {
    // ...
  }
})

計劃性重大 API 變更 (13.0)

API 變更：`session.setPermissionCheckHandler(handler)`

handler 方法的第一個參數以前始終是 webContents，現在有時可能是 null。您應該使用 requestingOrigin、embeddingOrigin 和 securityOrigin 屬性來正確回應權限檢查。由於 webContents 可以為 null，因此不再可以依賴它。

// Old code
session.setPermissionCheckHandler((webContents, permission) => {
  if (webContents.getURL().startsWith('https://google.com/') && permission === 'notification') {
    return true
  }
  return false
})

// Replace with
session.setPermissionCheckHandler((webContents, permission, requestingOrigin) => {
  if (new URL(requestingOrigin).hostname === 'google.com' && permission === 'notification') {
    return true
  }
  return false
})

已移除：`shell.moveItemToTrash()`

已棄用的同步 shell.moveItemToTrash() API 已被移除。請改用異步 shell.trashItem()。

// Removed in Electron 13
shell.moveItemToTrash(path)
// Replace with
shell.trashItem(path).then(/* ... */)

已移除：`BrowserWindow` 擴充功能 API

已棄用的擴充功能 API 已被移除

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

請改用 session API

ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()

// Removed in Electron 13
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)

// Removed in Electron 13
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)

// Removed in Electron 13
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

已移除：`systemPreferences` 中的方法

以下 systemPreferences 方法已被棄用

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

請改用以下 nativeTheme 屬性

nativeTheme.shouldUseDarkColors
nativeTheme.shouldUseInvertedColorScheme
nativeTheme.shouldUseHighContrastColors

// Removed in Electron 13
systemPreferences.isDarkMode()
// Replace with
nativeTheme.shouldUseDarkColors

// Removed in Electron 13
systemPreferences.isInvertedColorScheme()
// Replace with
nativeTheme.shouldUseInvertedColorScheme

// Removed in Electron 13
systemPreferences.isHighContrastColorScheme()
// Replace with
nativeTheme.shouldUseHighContrastColors

已棄用：WebContents `new-window` 事件

WebContents 的 new-window 事件已被棄用。它已被 webContents.setWindowOpenHandler() 取代。

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

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

計劃性重大 API 變更 (12.0)

已移除：Pepper Flash 支援

Chromium 已移除對 Flash 的支援，因此我們也必須跟進。有關更多詳細資訊，請參閱 Chromium 的 Flash 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') 取代用法。

// Removed in Electron 12
crashReporter.getCrashesDirectory()
// Replace with
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 模組取代。

// Deprecated in Electron 12:
const { BrowserWindow } = require('electron').remote

// Replace with:
const { BrowserWindow } = require('@electron/remote')

// In the main process:
require('@electron/remote/main').initialize()

已棄用：`shell.moveItemToTrash()`

同步 shell.moveItemToTrash() 已被新的異步 shell.trashItem() 取代。

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

計劃性重大 API 變更 (11.0)

已移除：`BrowserView.{destroy, fromId, fromWebContents, getAllViews}` 和 `BrowserView` 的 `id` 屬性

實驗性 API BrowserView.{destroy, fromId, fromWebContents, getAllViews} 現已移除。此外，BrowserView 的 id 屬性也已移除。

有關更多詳細資訊，請參閱 #23578。

計劃性重大 API 變更 (10.0)

已棄用：`crashReporter.start()` 的 `companyName` 參數

先前為必填項的 crashReporter.start() 的 companyName 參數現在為可選，並且已進一步棄用。若要以非棄用的方式獲得相同的行為，您可以在 globalExtra 中傳遞 companyName 值。

// Deprecated in Electron 10
crashReporter.start({ companyName: 'Umbrella Corporation' })
// Replace with
crashReporter.start({ globalExtra: { _companyName: 'Umbrella Corporation' } })

已棄用：`crashReporter.getCrashesDirectory()`

crashReporter.getCrashesDirectory 方法已被棄用。應使用 app.getPath('crashDumps') 取代用法。

// Deprecated in Electron 10
crashReporter.getCrashesDirectory()
// Replace with
app.getPath('crashDumps')

已棄用：渲染器處理程序中的 `crashReporter` 方法

從渲染器處理程序中呼叫以下 crashReporter 方法已被棄用

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

渲染器中 crashReporter 模組中唯一剩餘的非棄用方法是 addExtraParameter、removeExtraParameter 和 getParameters。

從主處理程序呼叫時，以上所有方法仍然是非棄用的。

有關更多詳細資訊，請參閱 #23265。

已棄用：`crashReporter.start({ compress: false })`

在 crashReporter.start 中設定 { compress: false } 已被棄用。幾乎所有損毀接收伺服器都支援 gzip 壓縮。此選項將在未來版本的 Electron 中移除。

預設變更：`enableRemoteModule` 預設為 `false`

在 Electron 9 中，在未使用 enableRemoteModule WebPreferences 選項明確啟用的情況下使用 remote 模組，開始發出警告。在 Electron 10 中，remote 模組現在預設為停用。若要使用 remote 模組，必須在 WebPreferences 中指定 enableRemoteModule: true

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

我們建議遠離 remote 模組。

`protocol.unregisterProtocol`

`protocol.uninterceptProtocol`

這些 API 現在是同步的，並且不再需要可選的回呼。

// Deprecated
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// Replace with
protocol.unregisterProtocol(scheme)

`protocol.registerFileProtocol`

`protocol.registerBufferProtocol`

`protocol.registerStringProtocol`

`protocol.registerHttpProtocol`

`protocol.registerStreamProtocol`

`protocol.interceptFileProtocol`

`protocol.interceptStringProtocol`

`protocol.interceptBufferProtocol`

`protocol.interceptHttpProtocol`

`protocol.interceptStreamProtocol`

這些 API 現在是同步的，並且不再需要可選的回呼。

// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
protocol.registerFileProtocol(scheme, handler)

已註冊或攔截的協定在導航發生之前對目前頁面沒有影響。

`protocol.isProtocolHandled`

此 API 已棄用，使用者應改用 protocol.isProtocolRegistered 和 protocol.isProtocolIntercepted。

// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)

計劃性重大 API 變更 (9.0)

預設變更：預設情況下，在渲染器處理程序中停用載入非上下文感知原生模組

從 Electron 9 開始，我們不允許在渲染器處理程序中載入非上下文感知原生模組。這是為了提高 Electron 作為專案的安全性、效能和可維護性。

如果這影響到您，您可以暫時將 app.allowRendererProcessReuse 設定為 false 以還原為舊的行為。此標誌僅在 Electron 11 之前是一個選項，因此您應該計劃更新您的原生模組以使其成為上下文感知的。

有關更多詳細資訊，請參閱 #18397。

已棄用：`BrowserWindow` 擴充功能 API

以下擴充功能 API 已被棄用

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

請改用 session API

ses.loadExtension(path)
ses.removeExtension(extension_id)
ses.getAllExtensions()

// Deprecated in Electron 9
BrowserWindow.addExtension(path)
BrowserWindow.addDevToolsExtension(path)
// Replace with
session.defaultSession.loadExtension(path)

// Deprecated in Electron 9
BrowserWindow.removeExtension(name)
BrowserWindow.removeDevToolsExtension(name)
// Replace with
session.defaultSession.removeExtension(extension_id)

// Deprecated in Electron 9
BrowserWindow.getExtensions()
BrowserWindow.getDevToolsExtensions()
// Replace with
session.defaultSession.getAllExtensions()

已移除：`<webview>.getWebContents()`

此 API 已在 Electron 8.0 中棄用，現在已被移除。

// Removed in Electron 9.0
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

已移除：`webFrame.setLayoutZoomLevelLimits()`

Chromium 已移除對變更佈局縮放級別限制的支援，並且超出 Electron 的能力範圍來維護它。該函數已在 Electron 8.x 中棄用，並已在 Electron 9.x 中移除。佈局縮放級別限制現在固定為最小 0.25 和最大 5.0，如此處定義。

行為變更：透過 IPC 發送非 JS 物件現在會拋出例外

在 Electron 8.0 中，IPC 已變更為使用結構化複製演算法 (Structured Clone Algorithm)，帶來顯著的效能提升。為了 облегчить 過渡，舊的 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 倍的效能提升，但也帶來了一些行為上的重大變更。

透過 IPC 傳送函式、Promise、WeakMap、WeakSet 或包含任何此類值的物件，現在會拋出例外，而不是靜默地將函式轉換為 undefined。

// Previously:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => results in { value: 3 } arriving in the main process

// From Electron 8:
ipcRenderer.send('channel', { value: 3, someFunction: () => {} })
// => throws Error("() => {} could not be cloned.")

NaN、Infinity 和 -Infinity 現在將被正確序列化，而不是被轉換為 null。
包含循環參照的物件現在將被正確序列化，而不是被轉換為 null。
Set、Map、Error 和 RegExp 值將被正確序列化，而不是被轉換為 {}。
BigInt 值將被正確序列化，而不是被轉換為 null。
稀疏陣列將按原樣序列化，而不是被轉換為帶有 null 的密集陣列。
Date 物件將作為 Date 物件傳輸，而不是被轉換為其 ISO 字串表示形式。
類型化陣列 (例如 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 中，這些物件將像以前一樣被序列化，並顯示棄用警告訊息，但從 Electron 9 開始，傳送這些類型的物件將會拋出 'could not be cloned' 錯誤。

已棄用：`<webview>.getWebContents()`

此 API 是使用 remote 模組實作的，這具有效能和安全性方面的影響。因此，應明確使用它。

// Deprecated
webview.getWebContents()
// Replace with
const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId())

但是，建議完全避免使用 remote 模組。

// main
const { ipcMain, webContents } = require('electron')

const getGuestForWebContents = (webContentsId, contents) => {
  const guest = webContents.fromId(webContentsId)
  if (!guest) {
    throw new Error(`Invalid webContentsId: ${webContentsId}`)
  }
  if (guest.hostWebContents !== contents) {
    throw new Error('Access denied to webContents')
  }
  return guest
}

ipcMain.handle('openDevTools', (event, webContentsId) => {
  const guest = getGuestForWebContents(webContentsId, event.sender)
  guest.openDevTools()
})

// renderer
const { ipcRenderer } = require('electron')

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

已棄用：`webFrame.setLayoutZoomLevelLimits()`

Chromium 已移除對變更版面配置縮放比例限制的支援，並且 Electron 無力維護它。此函式將在 Electron 8.x 中發出警告，並在 Electron 9.x 中停止存在。版面配置縮放比例限制現在固定為最小 0.25 和最大 5.0，如此處定義。

`systemPreferences` 中已棄用的事件

以下 systemPreferences 事件已被棄用

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

請改用 nativeTheme 模組上的新 updated 事件。

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

// Replace with
nativeTheme.on('updated', () => { /* ... */ })

`systemPreferences` 中已棄用的方法

以下 systemPreferences 方法已被棄用

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

請改用以下 nativeTheme 屬性

nativeTheme.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.shouldUseHighContrastColors

計畫中的重大 API 變更 (7.0)

已棄用：Atom.io Node Headers URL

這是 .npmrc 檔案中指定為 disturl 或在建置原生 Node 模組時作為 --dist-url 命令列旗標的 URL。在可預見的未來，兩者都將受到支援，但建議您切換。

已棄用：https://atom.io/download/electron

替換為：https://electron.dev.org.tw/headers

API 變更：`session.clearAuthCache()` 不再接受選項

session.clearAuthCache API 不再接受用於清除內容的選項，而是無條件清除整個快取。

// Deprecated
session.clearAuthCache({ type: 'password' })
// Replace with
session.clearAuthCache()

API 變更：`powerMonitor.querySystemIdleState` 現在是 `powerMonitor.getSystemIdleState`

// Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)

API 變更：`powerMonitor.querySystemIdleTime` 現在是 `powerMonitor.getSystemIdleTime`

// Removed in Electron 7.0
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()

API 變更：`webFrame.setIsolatedWorldInfo` 取代了個別方法

// Removed in Electron 7.0
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

已移除：`getBlinkMemoryInfo` 上的 `marked` 屬性

此屬性已在 Chromium 77 中移除，因此不再可用。

行為變更：`<input type="file"/>` 的 `webkitdirectory` 屬性現在列出目錄內容

HTML 檔案輸入上的 webkitdirectory 屬性允許它們選取資料夾。先前版本的 Electron 有一個不正確的實作，其中輸入的 event.target.files 回傳一個 FileList，該 FileList 回傳一個對應於所選資料夾的 File。

從 Electron 7 開始，該 FileList 現在是資料夾中包含的所有檔案的列表，與 Chrome、Firefox 和 Edge 類似 (連結到 MDN 文件)。

作為說明，以具有以下結構的資料夾為例

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

在 Electron <=6 中，這將回傳一個 FileList，其中包含一個用於以下的 File 物件

path/to/folder

在 Electron 7 中，這現在回傳一個 FileList，其中包含一個用於以下的 File 物件

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

請注意，webkitdirectory 不再公開所選資料夾的路徑。如果您需要所選資料夾的路徑而不是資料夾內容，請參閱 dialog.showOpenDialog API (連結)。

API 變更：基於回呼的承諾 API 版本

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 的非同步

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

計畫中的重大 API 變更 (6.0)

API 變更：`win.setMenu(null)` 現在是 `win.removeMenu()`

// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()

API 變更：在渲染器程序中，`electron.screen` 應透過 `remote` 存取

// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen

API 變更：在沙盒渲染器中 `require()` 節點內建模組不再隱式載入 `remote` 版本

// Deprecated
require('child_process')
// Replace with
require('electron').remote.require('child_process')

// Deprecated
require('fs')
// Replace with
require('electron').remote.require('fs')

// Deprecated
require('os')
// Replace with
require('electron').remote.require('os')

// Deprecated
require('path')
// Replace with
require('electron').remote.require('path')

已棄用：`powerMonitor.querySystemIdleState` 已替換為 `powerMonitor.getSystemIdleState`

// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = powerMonitor.getSystemIdleState(threshold)

已棄用：`powerMonitor.querySystemIdleTime` 已替換為 `powerMonitor.getSystemIdleTime`

// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = powerMonitor.getSystemIdleTime()

已棄用：不再需要 `app.enableMixedSandbox()`

// Deprecated
app.enableMixedSandbox()

混合沙盒模式現在預設為啟用。

已棄用：`Tray.setHighlightMode`

在 macOS Catalina 下，我們先前的 Tray 實作已損壞。Apple 的原生替代方案不支援變更醒目提示行為。

// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.

計畫中的重大 API 變更 (5.0)

預設變更：`nodeIntegration` 和 `webviewTag` 預設為 false，`contextIsolation` 預設為 true

以下 webPreferences 選項預設值已被棄用，而改用下面列出的新預設值。

屬性	已棄用的預設值	新的預設值
`contextIsolation`	`false`	`true`
`nodeIntegration`	`true`	`false`
`webviewTag`	`nodeIntegration` (如果已設定) 否則為 `true`	`false`

例如，重新啟用 webviewTag

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

行為變更：透過 `nativeWindowOpen` 開啟的子視窗中的 `nodeIntegration`

除非 nodeIntegrationInSubFrames 為 true，否則使用 nativeWindowOpen 選項開啟的子視窗將始終停用 Node.js 整合。

API 變更：現在必須在 app ready 之前完成登錄特權架構

渲染器程序 API webFrame.registerURLSchemeAsPrivileged 和 webFrame.registerURLSchemeAsBypassingCSP 以及瀏覽器程序 API protocol.registerStandardSchemes 已移除。已新增一個新的 API protocol.registerSchemesAsPrivileged，應用於登錄具有所需特權的自訂架構。自訂架構需要在 app ready 之前登錄。

已棄用：`webFrame.setIsolatedWorld*` 已替換為 `webFrame.setIsolatedWorldInfo`

// Deprecated
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

API 變更：`webFrame.setSpellCheckProvider` 現在採用非同步回呼

spellCheck 回呼現在是非同步的，並且已移除 autoCorrectWord 參數。

// Deprecated
webFrame.setSpellCheckProvider('en-US', true, {
  spellCheck: (text) => {
    return !spellchecker.isMisspelled(text)
  }
})
// Replace with
webFrame.setSpellCheckProvider('en-US', {
  spellCheck: (words, callback) => {
    callback(words.filter(text => spellchecker.isMisspelled(text)))
  }
})

API 變更：`webContents.getZoomLevel` 和 `webContents.getZoomFactor` 現在是同步的

webContents.getZoomLevel 和 webContents.getZoomFactor 不再採用回呼參數，而是直接回傳其數字值。

// Deprecated
webContents.getZoomLevel((level) => {
  console.log(level)
})
// Replace with
const level = webContents.getZoomLevel()
console.log(level)

// Deprecated
webContents.getZoomFactor((factor) => {
  console.log(factor)
})
// Replace with
const factor = webContents.getZoomFactor()
console.log(factor)

計畫中的重大 API 變更 (4.0)

以下列表包含 Electron 4.0 中所做的重大 API 變更。

`app.makeSingleInstance`

// Deprecated
app.makeSingleInstance((argv, cwd) => {
  /* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
  /* ... */
})

`app.releaseSingleInstance`

// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()

`app.getGPUInfo`

app.getGPUInfo('complete')
// Now behaves the same with `basic` on macOS
app.getGPUInfo('basic')

`win_delay_load_hook`

在為 Windows 建置原生模組時，模組的 binding.gyp 中的 win_delay_load_hook 變數必須為 true (這是預設值)。如果此 hook 不存在，則原生模組將無法在 Windows 上載入，並顯示類似 Cannot find module 的錯誤訊息。請參閱原生模組指南以取得更多資訊。

已移除：IA32 Linux 支援

Electron 18 將不再在 32 位元 Linux 系統上執行。請參閱終止對 32 位元 Linux 的支援以取得更多資訊。

重大 API 變更 (3.0)

以下列表包含 Electron 3.0 中的重大 API 變更。

`app`

// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()

// Deprecated
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property

`BrowserWindow`

// Deprecated
const optionsA = { webPreferences: { blinkFeatures: '' } }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { webPreferences: { enableBlinkFeatures: '' } }
const windowB = new BrowserWindow(optionsB)

// Deprecated
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play_pause') {
    // do something
  }
})
// Replace with
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play-pause') {
    // do something
  }
})

`clipboard`

// Deprecated
clipboard.readRtf()
// Replace with
clipboard.readRTF()

// Deprecated
clipboard.writeRtf()
// Replace with
clipboard.writeRTF()

// Deprecated
clipboard.readHtml()
// Replace with
clipboard.readHTML()

// Deprecated
clipboard.writeHtml()
// Replace with
clipboard.writeHTML()

`crashReporter`

// Deprecated
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  autoSubmit: true
})
// Replace with
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  uploadToServer: true
})

`nativeImage`

// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
  scaleFactor: 1.0
})

`process`

// Deprecated
const info = process.getProcessMemoryInfo()

`screen`

// Deprecated
screen.getMenuBarHeight()
// Replace with
screen.getPrimaryDisplay().workArea

`session`

// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
  callback(0)
})

`Tray`

// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')

// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')

`webContents`

// Deprecated
webContents.openDevTools({ detach: true })
// Replace with
webContents.openDevTools({ mode: 'detach' })

// Removed
webContents.setSize(options)
// There is no replacement for this API

`webFrame`

// Deprecated
webFrame.registerURLSchemeAsSecure('app')
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

// Deprecated
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

`<webview>`

// Removed
webview.setAttribute('disableguestresize', '')
// There is no replacement for this API

// Removed
webview.setAttribute('guestinstance', instanceId)
// There is no replacement for this API

// Keyboard listeners no longer work on webview tag
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node Headers URL

這是 .npmrc 檔案中指定為 disturl 或在建置原生 Node 模組時作為 --dist-url 命令列旗標的 URL。

已棄用：https://atom.io/download/atom-shell

替換為：https://atom.io/download/electron

重大 API 變更 (2.0)

以下列表包含 Electron 2.0 中所做的重大 API 變更。

`BrowserWindow`

// Deprecated
const optionsA = { titleBarStyle: 'hidden-inset' }
const windowA = new BrowserWindow(optionsA)
// Replace with
const optionsB = { titleBarStyle: 'hiddenInset' }
const windowB = new BrowserWindow(optionsB)

`menu`

// Removed
menu.popup(browserWindow, 100, 200, 2)
// Replaced with
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

`nativeImage`

// Removed
nativeImage.toPng()
// Replaced with
nativeImage.toPNG()

// Removed
nativeImage.toJpeg()
// Replaced with
nativeImage.toJPEG()

`process`

為了與 Node 設定的其他 process.versions 屬性保持一致，process.versions.electron 和 process.version.chrome 將設為唯讀屬性。

`webContents`

// Removed
webContents.setZoomLevelLimits(1, 2)
// Replaced with
webContents.setVisualZoomLevelLimits(1, 2)

`webFrame`

// Removed
webFrame.setZoomLevelLimits(1, 2)
// Replaced with
webFrame.setVisualZoomLevelLimits(1, 2)

`<webview>`

// Removed
webview.setZoomLevelLimits(1, 2)
// Replaced with
webview.setVisualZoomLevelLimits(1, 2)

重複的 ARM 資產

每個 Electron 版本都包含兩個相同的 ARM 建置版本，但檔案名稱略有不同，例如 electron-v1.7.3-linux-arm.zip 和 electron-v1.7.3-linux-armv7l.zip。新增帶有 v7l 字首的資產，以向使用者闡明它支援的 ARM 版本，並將其與未來可能產生的 armv6l 和 arm64 資產區分開來。

不帶字首的檔案仍在發布，以避免破壞任何可能正在使用它的設定。從 2.0 開始，將不再發布不帶字首的檔案。

如需詳細資訊，請參閱 6986 和 7189。

重大變更類型
計畫中的重大 API 變更 (35.0)
- 行為變更：Dialog API 在 Linux 上的 defaultPath 選項
- 已棄用：Session 上的 setPreloads、getPreloads
- 已棄用：session.serviceWorkers 上的 getFromVersionID
- 已棄用：WebContents 上的 console-message 事件中的 level、message、line 和 sourceId 引數
- 行為變更：WebRequestFilter 的 urls 屬性。
- 已棄用：systemPreferences.isAeroGlassEnabled()
計畫中的重大 API 變更 (34.0)
- 行為變更：在 Windows 上全螢幕期間將隱藏選單列
計畫中的重大 API 變更 (33.0)
- 已棄用：document.execCommand("paste")
- 行為變更：框架屬性可能會擷取已分離的 WebFrameMain 實例，或完全不擷取
- 行為變更：Windows 上的自訂協定 URL 處理
- 行為變更：app 上 login 的 webContents 屬性
- 已棄用：BrowserWindowConstructorOption.type 中的 textured 選項
- 已移除：macOS 10.15 支援
- 行為變更：原生模組現在需要 C++20
- 已棄用：systemPreferences.accessibilityDisplayShouldReduceTransparency
計畫中的重大 API 變更 (32.0)
- 已移除：File.path
- 已棄用：WebContents 上的 clearHistory、canGoBack、goBack、canGoForward、goForward、goToIndex、canGoToOffset、goToOffset
- 行為變更：userData 中的目錄 databases 將被刪除
計畫中的重大 API 變更 (31.0)
- 已移除：WebSQL 支援
- 行為變更：nativeImage.toDataURL 將保留 PNG 色彩空間
- 行為變更：window.flashFrame(bool) 將在 macOS 上持續閃爍 Dock 圖示
計畫中的重大 API 變更 (30.0)
- 行為變更：跨來源 iframe 現在使用權限政策來存取功能
- 已移除：--disable-color-correct-rendering 切換器
- 行為變更：macOS 上的 BrowserView.setAutoResize 行為
- 已棄用：BrowserView
- 已移除：WebContents 上 context-menu 的 params.inputFormType 屬性
- 已移除：process.getIOCounters()
計畫中的重大 API 變更 (29.0)
- 行為變更：ipcRenderer 無法再透過 contextBridge 傳送
- 已移除：app 上的 renderer-process-crashed 事件
- 已移除：WebContents 和 <webview> 上的 crashed 事件
- 已移除：app 上的 gpu-process-crashed 事件
計畫中的重大 API 變更 (28.0)
- 行為變更：設定為 false 的 WebContents.backgroundThrottling 會影響主機 BrowserWindow 中的所有 WebContents
- 已移除：BrowserWindow.setTrafficLightPosition(position)
- 已移除：BrowserWindow.getTrafficLightPosition()
- 已移除：ipcRenderer.sendTo()
- 已移除：app.runningUnderRosettaTranslation
- 已棄用：app 上的 renderer-process-crashed 事件
- 已棄用：WebContents 上 context-menu 的 params.inputFormType 屬性
- 已棄用：WebContents 和 <webview> 上的 crashed 事件
- 已棄用：app 上的 gpu-process-crashed 事件
計畫中的重大 API 變更 (27.0)
- 已移除：macOS 10.13 / 10.14 支援
- 已棄用：ipcRenderer.sendTo()
- 已移除：systemPreferences 中的色彩配置事件
- 已移除：macOS 上某些 window.setVibrancy 選項
- 已移除：webContents.getPrinters
- 移除：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance
- 移除：systemPreferences.getColor 的 alternate-selected-control-text 值
計劃中的重大 API 變更 (26.0)
- 已棄用：webContents.getPrinters
- 已棄用：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance
- 已棄用：systemPreferences.getColor 的 alternate-selected-control-text 值
計劃中的重大 API 變更 (25.0)
- 已棄用：protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol 和 protocol.isProtocol{Registered,Intercepted}
- 已棄用：BrowserWindow.setTrafficLightPosition(position)
- 已棄用：BrowserWindow.getTrafficLightPosition()
計劃中的重大 API 變更 (24.0)
- API 變更：nativeImage.createThumbnailFromPath(path, size)
計劃中的重大 API 變更 (23.0)
- 行為變更：macOS 上的可拖曳區域
- 移除：Windows 7 / 8 / 8.1 支援
- 移除：BrowserWindow scroll-touch-* 事件
- 移除：webContents.incrementCapturerCount(stayHidden, stayAwake)
- 移除：webContents.decrementCapturerCount(stayHidden, stayAwake)
計劃中的重大 API 變更 (22.0)
- 已棄用：webContents.incrementCapturerCount(stayHidden, stayAwake)
- 已棄用：webContents.decrementCapturerCount(stayHidden, stayAwake)
- 移除：WebContents new-window 事件
- 移除：<webview> new-window 事件
- 已棄用：BrowserWindow scroll-touch-* 事件
計劃中的重大 API 變更 (21.0)
- 行為變更：V8 Memory Cage 已啟用
- API 變更：webContents.printToPDF()
計劃中的重大 API 變更 (20.0)
- 移除：macOS 10.11 / 10.12 支援
- 預設變更：未啟用 nodeIntegration: true 的渲染器預設為沙盒模式
- 移除：Linux 上的 skipTaskbar
- API 變更：session.setDevicePermissionHandler(handler)
計劃中的重大 API 變更 (19.0)
- 移除：IA32 Linux 二進制檔案
計劃中的重大 API 變更 (18.0)
- 移除：nativeWindowOpen
計劃中的重大 API 變更 (17.0)
- 移除：渲染器中的 desktopCapturer.getSources
- 已棄用：nativeWindowOpen
計劃中的重大 API 變更 (16.0)
- 行為變更：Linux 上 crashReporter 實作已切換至 Crashpad
- 已棄用：渲染器中的 desktopCapturer.getSources
計劃中的重大 API 變更 (15.0)
- 預設變更：nativeWindowOpen 預設為 true
- 已棄用：app.runningUnderRosettaTranslation
計劃中的重大 API 變更 (14.0)
- 移除：remote 模組
- 移除：app.allowRendererProcessReuse
- 移除：瀏覽器視窗親和性
- API 變更：window.open()
- 移除：worldSafeExecuteJavaScript
- 移除：BrowserWindowConstructorOptions 從父視窗繼承
- 移除：additionalFeatures
計劃中的重大 API 變更 (13.0)
- API 變更：session.setPermissionCheckHandler(handler)
- 移除：shell.moveItemToTrash()
- 移除：BrowserWindow 擴充 API
- 移除：systemPreferences 中的方法
- 已棄用：WebContents new-window 事件
計劃中的重大 API 變更 (12.0)
- 移除：Pepper Flash 支援
- 預設變更：worldSafeExecuteJavaScript 預設為 true
- 預設變更：contextIsolation 預設為 true
- 移除：crashReporter.getCrashesDirectory()
- 移除：渲染器進程中的 crashReporter 方法
- 預設變更：crashReporter.start({ compress: true })
- 已棄用：remote 模組
- 已棄用：shell.moveItemToTrash()
計劃中的重大 API 變更 (11.0)
- 移除：BrowserView.{destroy, fromId, fromWebContents, getAllViews} 和 BrowserView 的 id 屬性
計劃中的重大 API 變更 (10.0)
- 已棄用：crashReporter.start() 的 companyName 參數
- 已棄用：crashReporter.getCrashesDirectory()
- 已棄用：渲染器進程中的 crashReporter 方法
- 已棄用：crashReporter.start({ compress: false })
- 預設變更：enableRemoteModule 預設為 false
- 取消註冊協定
- 取消攔截協定
- 註冊檔案協定
- 註冊緩衝區協定
- 註冊字串協定
- 註冊 HTTP 協定
- 註冊串流協定
- 攔截檔案協定
- 攔截字串協定
- 攔截緩衝區協定
- 攔截 HTTP 協定
- 攔截串流協定
- 協定是否被處理
計劃中的重大 API 變更 (9.0)
- 預設變更：預設情況下，在渲染器進程中載入非 context-aware 原生模組已被禁用
- 已棄用：BrowserWindow 擴充 API
- 移除：<webview>.getWebContents()
- 移除：webFrame.setLayoutZoomLevelLimits()
- 行為變更：透過 IPC 發送非 JS 物件現在會拋出例外
- API 變更：shell.openItem 現在是 shell.openPath
計劃中的重大 API 變更 (8.0)
- 行為變更：透過 IPC 發送的值現在使用結構化複製演算法序列化
- 已棄用：<webview>.getWebContents()
- 已棄用：webFrame.setLayoutZoomLevelLimits()
- systemPreferences 中已棄用的事件
- 已棄用：systemPreferences 中的方法
計劃中的重大 API 變更 (7.0)
- 已棄用：Atom.io Node Headers URL
- API 變更：session.clearAuthCache() 不再接受選項
- API 變更：powerMonitor.querySystemIdleState 現在是 powerMonitor.getSystemIdleState
- API 變更：powerMonitor.querySystemIdleTime 現在是 powerMonitor.getSystemIdleTime
- API 變更：webFrame.setIsolatedWorldInfo 取代了個別的方法
- 移除：getBlinkMemoryInfo 上的 marked 屬性
- 行為變更：<input type="file"/> 的 webkitdirectory 屬性現在列出目錄內容
- API 變更：基於回调的 Promise 化 API 版本
計劃中的重大 API 變更 (6.0)
- API 變更：win.setMenu(null) 現在是 win.removeMenu()
- API 變更：渲染器進程中的 electron.screen 應透過 remote 存取
- API 變更：在沙盒渲染器中 require() node 內建模組不再隱式載入 remote 版本
- 已棄用：powerMonitor.querySystemIdleState 已被 powerMonitor.getSystemIdleState 取代
- 已棄用：powerMonitor.querySystemIdleTime 已被 powerMonitor.getSystemIdleTime 取代
- 已棄用：不再需要 app.enableMixedSandbox()
- 已棄用：Tray.setHighlightMode
計劃中的重大 API 變更 (5.0)
- 預設變更：nodeIntegration 和 webviewTag 預設為 false，contextIsolation 預設為 true
- 行為變更：透過 nativeWindowOpen 開啟的子視窗中的 nodeIntegration
- API 變更：現在必須在 app ready 事件之前註冊特權 schemes
- 已棄用：webFrame.setIsolatedWorld* 已被 webFrame.setIsolatedWorldInfo 取代
- API 變更：webFrame.setSpellCheckProvider 現在接受異步回调
- API 變更：webContents.getZoomLevel 和 webContents.getZoomFactor 現在是同步的
計劃中的重大 API 變更 (4.0)
- 建立單一實例
- 釋放單一實例
- 取得 GPU 資訊
- win_delay_load_hook
- 移除：IA32 Linux 支援
重大 API 變更 (3.0)
- 應用程式
- 瀏覽器視窗
- 剪貼簿
- 崩溃報告器
- 原生映像
- 進程
- 螢幕
- 會話
- 系統匣
- WebContents
- WebFrame
- <webview>
- Node Headers URL
重大 API 變更 (2.0)
- 瀏覽器視窗
- 選單
- 原生映像
- 進程
- WebContents
- WebFrame
- <webview>
- 重複的 ARM 資產

重大變更的類型​

計劃中的重大 API 變更 (35.0)​

行為已變更：Linux 上 Dialog API 的 defaultPath 選項​

已棄用：Session 上的 setPreloads、getPreloads​

已棄用：session.serviceWorkers 上的 getFromVersionID​

已棄用：WebContents 上 console-message 事件中的 level、message、line 和 sourceId 引數​

行為已變更：WebRequestFilter 的 urls 屬性。​

已棄用：systemPreferences.isAeroGlassEnabled()​

計劃中的重大 API 變更 (34.0)​

行為已變更：在 Windows 上全螢幕期間，選單列將會隱藏​

計劃中的重大 API 變更 (33.0)​

已棄用：document.execCommand("paste")​

行為已變更：框架屬性可能會擷取已分離的 WebFrameMain 實例，或完全不擷取​

行為已變更：Windows 上的自訂協定 URL 處理​

行為已變更：app 上 login 的 webContents 屬性​

已棄用：BrowserWindowConstructorOption.type 中的 textured 選項​

已移除：macOS 10.15 支援​

行為已變更：原生模組現在需要 C++20​

已棄用：systemPreferences.accessibilityDisplayShouldReduceTransparency​

計劃中的重大 API 變更 (32.0)​

已移除：File.path​

已棄用：WebContents 上的 clearHistory、canGoBack、goBack、canGoForward、goForward、goToIndex、canGoToOffset、goToOffset​

行為已變更：userData 中的目錄 databases 將被刪除​

計劃中的重大 API 變更 (31.0)​

已移除：WebSQL 支援​

行為已變更：nativeImage.toDataURL 將保留 PNG 色彩空間​

行為已變更：macOS 上的 window.flashFrame(bool) 將持續閃爍 dock 圖示​

計劃中的重大 API 變更 (30.0)​

行為已變更：跨來源 iframe 現在使用權限策略來存取功能​

已移除：--disable-color-correct-rendering 參數​

行為已變更：macOS 上的 BrowserView.setAutoResize 行為​

已棄用：BrowserView​

已移除：WebContents 上 context-menu 的 params.inputFormType 屬性​

已移除：process.getIOCounters()​

計劃中的重大 API 變更 (29.0)​

行為已變更：ipcRenderer 無法再透過 contextBridge 傳送​

已移除：app 上的 renderer-process-crashed 事件​

已移除：WebContents 和 <webview> 上的 crashed 事件​

已移除：app 上的 gpu-process-crashed 事件​

計劃中的重大 API 變更 (28.0)​

行為已變更：設定為 false 的 WebContents.backgroundThrottling 會影響主機 BrowserWindow 中的所有 WebContents​

已移除：BrowserWindow.setTrafficLightPosition(position)​

已移除：BrowserWindow.getTrafficLightPosition()​

已移除：ipcRenderer.sendTo()​

已移除：app.runningUnderRosettaTranslation​

已棄用：app 上的 renderer-process-crashed 事件​

已棄用：WebContents 上 context-menu 的 params.inputFormType 屬性​

已棄用：WebContents 和 <webview> 上的 crashed 事件​

已棄用：app 上的 gpu-process-crashed 事件​

計劃中的重大 API 變更 (27.0)​

已移除：macOS 10.13 / 10.14 支援​

已棄用：ipcRenderer.sendTo()​

已移除：systemPreferences 中的色彩配置事件​

已移除：macOS 上的一些 window.setVibrancy 選項​

已移除：webContents.getPrinters​

已移除：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance​

已移除：systemPreferences.getColor 的 alternate-selected-control-text 值​

計劃中的重大 API 變更 (26.0)​

已棄用：webContents.getPrinters​

已棄用：systemPreferences.{get,set}AppLevelAppearance 和 systemPreferences.appLevelAppearance​

已棄用：systemPreferences.getColor 的 alternate-selected-control-text 值​

計劃中的重大 API 變更 (25.0)​

已棄用：protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol 和 protocol.isProtocol{Registered,Intercepted}​

已棄用：BrowserWindow.setTrafficLightPosition(position)​

已棄用：BrowserWindow.getTrafficLightPosition()​

計劃中的重大 API 變更 (24.0)​

API 已變更：nativeImage.createThumbnailFromPath(path, size)​

計劃性重大 API 變更 (23.0)​

行為變更：macOS 上的可拖曳區域​

已移除：Windows 7 / 8 / 8.1 支援​

已移除：BrowserWindow scroll-touch-* 事件​

已移除：webContents.incrementCapturerCount(stayHidden, stayAwake)​

已移除：webContents.decrementCapturerCount(stayHidden, stayAwake)​

計劃性重大 API 變更 (22.0)​

已棄用：webContents.incrementCapturerCount(stayHidden, stayAwake)​

已棄用：webContents.decrementCapturerCount(stayHidden, stayAwake)​

已移除：WebContents new-window 事件​

已移除：<webview> new-window 事件​

已棄用：BrowserWindow scroll-touch-* 事件​

計劃性重大 API 變更 (21.0)​

重大變更的類型

計劃中的重大 API 變更 (35.0)

行為已變更：Linux 上 Dialog API 的 `defaultPath` 選項

已棄用：`Session` 上的 `setPreloads`、`getPreloads`

已棄用：`session.serviceWorkers` 上的 `getFromVersionID`

已棄用：`WebContents` 上 `console-message` 事件中的 `level`、`message`、`line` 和 `sourceId` 引數

行為已變更：`WebRequestFilter` 的 `urls` 屬性。

已棄用：`systemPreferences.isAeroGlassEnabled()`

計劃中的重大 API 變更 (34.0)

行為已變更：在 Windows 上全螢幕期間，選單列將會隱藏

計劃中的重大 API 變更 (33.0)

已棄用：`document.execCommand("paste")`

行為已變更：框架屬性可能會擷取已分離的 WebFrameMain 實例，或完全不擷取

行為已變更：Windows 上的自訂協定 URL 處理

行為已變更：`app` 上 `login` 的 `webContents` 屬性

已棄用：`BrowserWindowConstructorOption.type` 中的 `textured` 選項

已移除：macOS 10.15 支援

行為已變更：原生模組現在需要 C++20

已棄用：`systemPreferences.accessibilityDisplayShouldReduceTransparency`

計劃中的重大 API 變更 (32.0)

已移除：`File.path`

已棄用：`WebContents` 上的 `clearHistory`、`canGoBack`、`goBack`、`canGoForward`、`goForward`、`goToIndex`、`canGoToOffset`、`goToOffset`

行為已變更：`userData` 中的目錄 `databases` 將被刪除

計劃中的重大 API 變更 (31.0)

已移除：`WebSQL` 支援

行為已變更：`nativeImage.toDataURL` 將保留 PNG 色彩空間

行為已變更：macOS 上的 `window.flashFrame(bool)` 將持續閃爍 dock 圖示

計劃中的重大 API 變更 (30.0)

行為已變更：跨來源 iframe 現在使用權限策略來存取功能

已移除：`--disable-color-correct-rendering` 參數

行為已變更：macOS 上的 `BrowserView.setAutoResize` 行為

已棄用：`BrowserView`

已移除：`WebContents` 上 `context-menu` 的 `params.inputFormType` 屬性

已移除：`process.getIOCounters()`

計劃中的重大 API 變更 (29.0)

行為已變更：`ipcRenderer` 無法再透過 `contextBridge` 傳送

已移除：`app` 上的 `renderer-process-crashed` 事件

已移除：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已移除：`app` 上的 `gpu-process-crashed` 事件

計劃中的重大 API 變更 (28.0)

行為已變更：設定為 false 的 `WebContents.backgroundThrottling` 會影響主機 `BrowserWindow` 中的所有 `WebContents`

已移除：`BrowserWindow.setTrafficLightPosition(position)`

已移除：`BrowserWindow.getTrafficLightPosition()`

已移除：`ipcRenderer.sendTo()`

已移除：`app.runningUnderRosettaTranslation`

已棄用：`app` 上的 `renderer-process-crashed` 事件

已棄用：`WebContents` 上 `context-menu` 的 `params.inputFormType` 屬性

已棄用：`WebContents` 和 `<webview>` 上的 `crashed` 事件

已棄用：`app` 上的 `gpu-process-crashed` 事件

計劃中的重大 API 變更 (27.0)

已移除：macOS 10.13 / 10.14 支援

已棄用：`ipcRenderer.sendTo()`

已移除：`systemPreferences` 中的色彩配置事件

已移除：macOS 上的一些 `window.setVibrancy` 選項

已移除：`webContents.getPrinters`

已移除：`systemPreferences.{get,set}AppLevelAppearance` 和 `systemPreferences.appLevelAppearance`

已移除：`systemPreferences.getColor` 的 `alternate-selected-control-text` 值

計劃中的重大 API 變更 (26.0)

已棄用：`webContents.getPrinters`

已棄用：`systemPreferences.{get,set}AppLevelAppearance` 和 `systemPreferences.appLevelAppearance`

已棄用：`systemPreferences.getColor` 的 `alternate-selected-control-text` 值

計劃中的重大 API 變更 (25.0)

已棄用：`protocol.{un,}{register,intercept}{Buffer,String,Stream,File,Http}Protocol` 和 `protocol.isProtocol{Registered,Intercepted}`

已棄用：`BrowserWindow.setTrafficLightPosition(position)`

已棄用：`BrowserWindow.getTrafficLightPosition()`

計劃中的重大 API 變更 (24.0)

API 已變更：`nativeImage.createThumbnailFromPath(path, size)`

計劃性重大 API 變更 (23.0)

行為變更：macOS 上的可拖曳區域

已移除：Windows 7 / 8 / 8.1 支援

已移除：BrowserWindow `scroll-touch-*` 事件

已移除：`webContents.incrementCapturerCount(stayHidden, stayAwake)`

已移除：`webContents.decrementCapturerCount(stayHidden, stayAwake)`

計劃性重大 API 變更 (22.0)

已棄用：`webContents.incrementCapturerCount(stayHidden, stayAwake)`

已棄用：`webContents.decrementCapturerCount(stayHidden, stayAwake)`

已移除：WebContents `new-window` 事件

已移除：`<webview>` `new-window` 事件

已棄用：BrowserWindow `scroll-touch-*` 事件

計劃性重大 API 變更 (21.0)