BrowserWindow
建立和控制瀏覽器視窗。
程序：主要
此模組在 app 模組發出 ready 事件之前無法使用。
// In the main process.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
// Load a remote URL
win.loadURL('https://github.com')
// Or load a local HTML file
win.loadFile('index.html')
視窗自訂
BrowserWindow 類別公開了多種方式來修改應用程式視窗的外觀和行為。如需更多詳細資訊，請參閱視窗自訂教學課程。
優雅地顯示視窗
當直接在視窗中載入頁面時，使用者可能會看到頁面逐步載入，這對於原生應用程式來說不是好的體驗。為了使視窗顯示時不會出現視覺閃爍，針對不同的情況有兩種解決方案。
使用 ready-to-show 事件
在載入頁面時，如果視窗尚未顯示，則當渲染器程序首次渲染頁面時，將發出 ready-to-show 事件。在此事件之後顯示視窗將不會有視覺閃爍
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
win.show()
})
此事件通常在 did-finish-load 事件之後發出，但對於具有許多遠端資源的頁面，它可能會在 did-finish-load 事件之前發出。
請注意，使用此事件意味著即使 show 為 false，渲染器也會被視為「可見」並進行繪製。如果您使用 paintWhenInitiallyHidden: false，則此事件永遠不會觸發
設定 backgroundColor 屬性
對於複雜的應用程式，ready-to-show 事件可能會發出得太晚，使應用程式感覺緩慢。在這種情況下，建議立即顯示視窗，並使用接近應用程式背景的 backgroundColor
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')
請注意，即使對於使用 ready-to-show 事件的應用程式，仍然建議設定 backgroundColor 以使應用程式感覺更原生。
一些有效的 backgroundColor 值範例包括
const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')
有關這些顏色類型的更多資訊，請參閱win.setBackgroundColor中的有效選項。
父視窗和子視窗
透過使用 parent 選項，您可以建立子視窗
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()
child 視窗將始終顯示在 top 視窗之上。
強制回應視窗
強制回應視窗是停用父視窗的子視窗。若要建立強制回應視窗，您必須同時設定 parent 和 modal 選項
const { BrowserWindow } = require('electron')
const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
child.show()
})
頁面可見性
頁面可見性 API 的運作方式如下
- 在所有平台上，可見性狀態都會追蹤視窗是否已隱藏/最小化。
- 此外，在 macOS 上，可見性狀態也會追蹤視窗遮蔽狀態。如果視窗被另一個視窗遮蔽（即完全覆蓋），則可見性狀態將為
hidden。在其他平台上，只有當視窗最小化或使用win.hide()明確隱藏時，可見性狀態才會為hidden。 - 如果使用
show: false建立BrowserWindow，則儘管視窗實際上已隱藏，但初始可見性狀態仍為visible。 - 如果停用了
backgroundThrottling，即使視窗最小化、遮蔽或隱藏，可見性狀態仍將保持visible。
建議您在可見性狀態為 hidden 時暫停昂貴的操作，以最大程度地減少功耗。
平台注意事項
- 在 macOS 上，強制回應視窗將顯示為附加到父視窗的表單。
- 在 macOS 上，當父視窗移動時，子視窗將保持相對於父視窗的位置，而在 Windows 和 Linux 上，子視窗將不會移動。
- 在 Linux 上，強制回應視窗的類型將變更為
dialog。 - 在 Linux 上，許多桌面環境不支援隱藏強制回應視窗。
類別：BrowserWindow 繼承自 BaseWindow
建立和控制瀏覽器視窗。
程序：主要
BrowserWindow 是一個 EventEmitter。
它會使用 options 設定的原生屬性建立新的 BrowserWindow。
new BrowserWindow([options])
實例事件
使用 new BrowserWindow 建立的物件會發出以下事件
注意：某些事件僅在特定作業系統上可用，並標記為此類。
事件：'page-title-updated'
傳回
event事件title字串explicitSetboolean
當文件變更其標題時發出，呼叫 event.preventDefault() 將阻止原生視窗的標題變更。當標題從檔案 URL 合成時，explicitSet 為 false。
事件：'close'
傳回
event事件
當視窗即將關閉時發出。它在 DOM 的 beforeunload 和 unload 事件之前發出。呼叫 event.preventDefault() 將取消關閉。
通常，您會希望使用 beforeunload 處理常式來決定是否應關閉視窗，這也會在重新載入視窗時呼叫。在 Electron 中，傳回 undefined 以外的任何值都會取消關閉。例如
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
// Unlike usual browsers that a message box will be prompted to users, returning
// a non-void value will silently cancel the close.
// It is recommended to use the dialog API to let the user confirm closing the
// application.
e.returnValue = false
}
注意：window.onbeforeunload = handler 和 window.addEventListener('beforeunload', handler) 的行為之間存在細微差異。建議始終明確設定 event.returnValue，而不是僅傳回值，因為前者在 Electron 中更一致地運作。
事件：'closed'
當視窗關閉時發出。收到此事件後，您應移除對視窗的參照，並避免再使用它。
事件：'query-session-end' Windows
傳回
eventWindowSessionEndEvent
當 session 即將因關機、機器重新啟動或使用者登出而結束時發出。呼叫 event.preventDefault() 可以延遲系統關機，但通常最好尊重使用者結束 session 的選擇。但是，如果結束 session 會使使用者面臨遺失資料的風險，您可以選擇使用它。
事件：'session-end' Windows
傳回
eventWindowSessionEndEvent
當 session 即將因關機、機器重新啟動或使用者登出而結束時發出。一旦此事件觸發，就無法阻止 session 結束。
事件：'unresponsive'
當網頁變得沒有回應時發出。
事件：'responsive'
當沒有回應的網頁再次變得有回應時發出。
事件：'blur'
當視窗失去焦點時發出。
事件：'focus'
當視窗獲得焦點時發出。
事件：'show'
當視窗顯示時發出。
事件：'hide'
當視窗隱藏時發出。
事件：'ready-to-show'
當網頁已渲染（在未顯示時）且視窗可以顯示而沒有視覺閃爍時發出。
請注意，使用此事件意味著即使 show 為 false，渲染器也會被視為「可見」並進行繪製。如果您使用 paintWhenInitiallyHidden: false，則此事件永遠不會觸發
事件：'maximize'
當視窗最大化時發出。
事件：'unmaximize'
當視窗從最大化狀態退出時發出。
事件：'minimize'
當視窗最小化時發出。
事件：'restore'
當視窗從最小化狀態還原時發出。
事件：'will-resize' macOS Windows
傳回
event事件newBoundsRectangle - 視窗正在調整大小的尺寸。details物件edge(string) - 視窗被拖曳以調整大小的邊緣。可以是bottom、left、right、top-left、top-right、bottom-left或bottom-right。
在視窗調整大小之前發出。呼叫 event.preventDefault() 將阻止視窗調整大小。
請注意，這僅在手動調整視窗大小時發出。使用 setBounds/setSize 調整視窗大小不會發出此事件。
edge 選項的可能值和行為取決於平台。可能的值為
- 在 Windows 上，可能的值為
bottom、top、left、right、top-left、top-right、bottom-left、bottom-right。 - 在 macOS 上，可能的值為
bottom和right。- 值
bottom用於表示垂直調整大小。 - 值
right用於表示水平調整大小。
- 值
事件：'resize'
在視窗調整大小後發出。
事件：'resized' macOS Windows
在視窗完成調整大小後發出一次。
這通常在手動調整視窗大小時發出。在 macOS 上，使用 setBounds/setSize 調整視窗大小並將 animate 參數設定為 true 也會在調整大小完成後發出此事件。
事件：'will-move' macOS Windows
傳回
event事件newBoundsRectangle - 視窗正在移動到的位置。
在視窗移動之前發出。在 Windows 上，呼叫 event.preventDefault() 將阻止視窗移動。
請注意，這僅在手動移動視窗時發出。使用 setPosition/setBounds/center 移動視窗不會發出此事件。
事件：'move'
當視窗正在移動到新位置時發出。
事件：'moved' macOS Windows
當視窗移動到新位置時發出一次。
注意：在 macOS 上，此事件是 move 的別名。
事件：'enter-full-screen'
當視窗進入全螢幕狀態時發出。
事件：'leave-full-screen'
當視窗離開全螢幕狀態時發出。
事件：'enter-html-full-screen'
當視窗進入由 HTML API 觸發的全螢幕狀態時發出。
事件：'leave-html-full-screen'
當視窗離開由 HTML API 觸發的全螢幕狀態時發出。
事件：'always-on-top-changed'
傳回
event事件isAlwaysOnTop布林值
當視窗被設定或取消設定為永遠顯示在其他視窗之上時發出。
事件：'app-command' Windows Linux
傳回
event事件command字串
當 應用程式命令 被調用時發出。這些通常與鍵盤媒體鍵或瀏覽器命令，以及某些 Windows 滑鼠內建的「返回」按鈕有關。
命令會轉換為小寫，底線會替換為連字符號，並且 APPCOMMAND_ 前綴會被移除。例如，APPCOMMAND_BROWSER_BACKWARD 會作為 browser-backward 發出。
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
// Navigate the window back when the user hits their mouse back button
if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
win.webContents.goBack()
}
})
以下應用程式命令在 Linux 上明確支援
browser-backwardbrowser-forward
事件：'swipe' macOS
傳回
event事件direction字串
在三指滑動時發出。可能的方向為 up、right、down、left。
此事件的底層方法旨在處理舊式 macOS 風格的觸控板滑動，其中螢幕上的內容不會隨著滑動而移動。大多數 macOS 觸控板不再配置為允許這種滑動，因此為了使其正確發出，系統偏好設定 > 觸控式軌跡板 > 更多手勢 中的「在頁面之間滑動」偏好設定必須設定為「使用兩指或三指滑動」。
事件：'rotate-gesture' macOS
傳回
event事件rotation浮點數
在觸控板旋轉手勢時發出。持續發出直到旋轉手勢結束。每次發出的 rotation 值是自上次發出以來旋轉的角度（以度為單位）。旋轉手勢結束時最後發出的事件值始終為 0。逆時針旋轉值為正值，而順時針旋轉值為負值。
事件：'sheet-begin' macOS
當視窗開啟工作表時發出。
事件：'sheet-end' macOS
當視窗已關閉工作表時發出。
事件：'new-window-for-tab' macOS
當原生新分頁按鈕被點擊時發出。
事件：'system-context-menu' Windows
傳回
event事件pointPoint - 上下文選單被觸發時的螢幕座標
當系統上下文選單在視窗上被觸發時發出，這通常僅在使用者在視窗的非客戶區點擊滑鼠右鍵時觸發。這是視窗標題列或您在無邊框視窗中宣告為 -webkit-app-region: drag 的任何區域。
呼叫 event.preventDefault() 將阻止選單顯示。
靜態方法
BrowserWindow 類別具有以下靜態方法
BrowserWindow.getAllWindows()
回傳 BrowserWindow[] - 所有已開啟瀏覽器視窗的陣列。
BrowserWindow.getFocusedWindow()
回傳 BrowserWindow | null - 此應用程式中獲得焦點的視窗，否則回傳 null。
BrowserWindow.fromWebContents(webContents)
webContentsWebContents
回傳 BrowserWindow | null - 擁有給定 webContents 的視窗，如果內容不屬於任何視窗，則回傳 null。
BrowserWindow.fromBrowserView(browserView) 已棄用
browserViewBrowserView
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
回傳 BrowserWindow | null - 擁有給定 browserView 的視窗。如果給定的視圖未附加到任何視窗，則回傳 null。
BrowserWindow.fromId(id)
id整數
回傳 BrowserWindow | null - 具有給定 id 的視窗。
實例屬性
使用 new BrowserWindow 建立的物件具有以下屬性
const { BrowserWindow } = require('electron')
// In this example `win` is our instance
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')
win.webContents 唯讀
此視窗擁有的 WebContents 物件。所有網頁相關事件和操作都將透過它完成。
請參閱 webContents 文件 以了解其方法和事件。
win.id 唯讀
一個 整數 屬性，表示視窗的唯一 ID。每個 ID 在整個 Electron 應用程式的所有 BrowserWindow 實例中都是唯一的。
win.tabbingIdentifier macOS 唯讀
一個 字串 (可選) 屬性，等於傳遞給 BrowserWindow 建構子的 tabbingIdentifier，如果未設定則為 undefined。
win.autoHideMenuBar
一個 布林值 屬性，決定視窗選單列是否應自動隱藏。設定後，選單列只會在使用者按下單個 Alt 鍵時顯示。
如果選單列已可見，將此屬性設定為 true 不會立即隱藏它。
win.simpleFullScreen
一個 布林值 屬性，決定視窗是否處於簡單 (pre-Lion) 全螢幕模式。
win.fullScreen
一個 布林值 屬性，決定視窗是否處於全螢幕模式。
win.focusable Windows macOS
一個 布林值 屬性，決定視窗是否可獲得焦點。
win.visibleOnAllWorkspaces macOS Linux
一個 布林值 屬性，決定視窗是否在所有工作區上可見。
注意： 在 Windows 上始終回傳 false。
win.shadow
一個 布林值 屬性，決定視窗是否具有陰影。
win.menuBarVisible Windows Linux
一個 布林值 屬性，決定選單列是否應該可見。
注意： 如果選單列是自動隱藏的，使用者仍然可以透過按下單個 Alt 鍵來顯示選單列。
win.kiosk
一個 布林值 屬性，決定視窗是否處於 kiosk 模式。
win.documentEdited macOS
一個 布林值 屬性，指定視窗的文件是否已被編輯。
當設定為 true 時，標題列中的圖示將變為灰色。
win.representedFilename macOS
一個 字串 屬性，決定視窗代表的檔案路徑名稱，檔案的圖示將顯示在視窗的標題列中。
win.title
一個 字串 屬性，決定原生視窗的標題。
注意： 網頁的標題可能與原生視窗的標題不同。
win.minimizable macOS Windows
一個 布林值 屬性，決定視窗是否可以由使用者手動最小化。
在 Linux 上，setter 是空操作，但 getter 回傳 true。
win.maximizable macOS Windows
一個 布林值 屬性，決定視窗是否可以由使用者手動最大化。
在 Linux 上，setter 是空操作，但 getter 回傳 true。
win.fullScreenable
一個 布林值 屬性，決定最大化/縮放視窗按鈕是切換全螢幕模式還是最大化視窗。
win.resizable
一個 布林值 屬性，決定視窗是否可以由使用者手動調整大小。
win.closable macOS Windows
一個 布林值 屬性，決定視窗是否可以由使用者手動關閉。
在 Linux 上，setter 是空操作，但 getter 回傳 true。
win.movable macOS Windows
一個 布林值 屬性，決定視窗是否可以由使用者移動。
在 Linux 上，setter 是空操作，但 getter 回傳 true。
win.excludedFromShownWindowsMenu macOS
一個 布林值 屬性，決定視窗是否從應用程式的 Windows 選單中排除。預設為 false。
const win = new BrowserWindow({ height: 600, width: 600 })
const template = [
{
role: 'windowmenu'
}
]
win.excludedFromShownWindowsMenu = true
const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)
win.accessibleTitle
一個 字串 屬性，定義僅提供給輔助工具（如螢幕閱讀器）的替代標題。此字串不會直接向使用者顯示。
實例方法
使用 new BrowserWindow 建立的物件具有以下實例方法
注意： 某些方法僅在特定作業系統上可用，並已如此標示。
win.destroy()
強制關閉視窗，網頁不會發出 unload 和 beforeunload 事件，此視窗也不會發出 close 事件，但它保證會發出 closed 事件。
win.close()
嘗試關閉視窗。這與使用者手動點擊視窗的關閉按鈕具有相同的效果。網頁可能會取消關閉。請參閱 close 事件。
win.focus()
將焦點放在視窗上。
win.blur()
從視窗中移除焦點。
win.isFocused()
回傳 布林值 - 視窗是否獲得焦點。
win.isDestroyed()
回傳 布林值 - 視窗是否已銷毀。
win.show()
顯示視窗並給予焦點。
win.showInactive()
顯示視窗但不給予焦點。
win.hide()
隱藏視窗。
win.isVisible()
回傳 布林值 - 視窗在應用程式前景中是否對使用者可見。
win.isModal()
回傳 布林值 - 目前視窗是否為模態視窗。
win.maximize()
最大化視窗。如果視窗尚未顯示，這也將顯示（但不給予焦點）視窗。
win.unmaximize()
取消最大化視窗。
win.isMaximized()
回傳 布林值 - 視窗是否已最大化。
win.minimize()
最小化視窗。在某些平台上，最小化的視窗將顯示在 Dock 中。
win.restore()
將視窗從最小化狀態還原到其先前狀態。
win.isMinimized()
回傳 布林值 - 視窗是否已最小化。
win.setFullScreen(flag)
flag布林值
設定視窗是否應處於全螢幕模式。
注意： 在 macOS 上，全螢幕轉換是異步發生的。如果後續操作取決於全螢幕狀態，請使用 'enter-full-screen' 或 'leave-full-screen' 事件。
win.isFullScreen()
回傳 布林值 - 視窗是否處於全螢幕模式。
注意： 在 macOS 上，全螢幕轉換是異步發生的。當查詢 BrowserWindow 的全螢幕狀態時，您應確保已發出 'enter-full-screen' 或 'leave-full-screen' 事件。
win.setSimpleFullScreen(flag) macOS
flag布林值
進入或離開簡單全螢幕模式。
簡單全螢幕模式模擬 macOS Lion (10.7) 之前版本中發現的原生全螢幕行為。
win.isSimpleFullScreen() macOS
回傳 布林值 - 視窗是否處於簡單 (pre-Lion) 全螢幕模式。
win.isNormal()
回傳 布林值 - 視窗是否處於正常狀態（未最大化、未最小化、未處於全螢幕模式）。
win.setAspectRatio(aspectRatio[, extraSize])
aspectRatio浮點數 - 要為內容視圖的某些部分維護的縱橫比。extraSizeSize (可選) macOS - 在維持縱橫比時不包含的額外大小。
這將使視窗維持縱橫比。額外大小允許開發人員擁有以像素為單位指定的空間，而不包含在縱橫比計算中。此 API 已經考慮到視窗大小與其內容大小之間的差異。
考慮一個具有 HD 影片播放器和相關控制項的普通視窗。也許在左邊緣有 15 像素的控制項，在右邊緣有 25 像素的控制項，在播放器下方有 50 像素的控制項。為了在播放器本身內維持 16:9 的縱橫比（HD @1920x1080 的標準縱橫比），我們將使用 16/9 和 { width: 40, height: 50 } 的參數呼叫此函數。第二個參數不關心額外的寬度和高度在內容視圖中的位置，只關心它們存在。總結您在整個內容視圖中擁有的任何額外寬度和高度區域。
當使用 win.setSize 等 API 以程式方式調整視窗大小時，縱橫比將不會被遵守。
若要重設縱橫比，請將 0 作為 aspectRatio 值傳遞：win.setAspectRatio(0)。
win.setBackgroundColor(backgroundColor)
backgroundColor字串 - 十六進位、RGB、RGBA、HSL、HSLA 或具名 CSS 色彩格式的顏色。alpha 通道對於十六進位類型是可選的。
有效 backgroundColor 值的範例
- 十六進位
- #fff (簡寫 RGB)
- #ffff (簡寫 ARGB)
- #ffffff (RGB)
- #ffffffff (ARGB)
- RGB
rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)- 例如 rgb(255, 255, 255)
- RGBA
rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)- 例如 rgba(255, 255, 255, 1.0)
- HSL
hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)- 例如 hsl(200, 20%, 50%)
- HSLA
hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)- 例如 hsla(200, 20%, 50%, 0.5)
- 色彩名稱
- 選項列在 SkParseColor.cpp
- 類似於 CSS Color Module Level 3 關鍵字，但區分大小寫。
- 例如
blueviolet或red
- 例如
設定視窗的背景顏色。請參閱 設定 backgroundColor。
win.previewFile(path[, displayName]) macOS
path字串 - 使用 QuickLook 預覽檔案的絕對路徑。這很重要，因為 Quick Look 使用路徑上的檔案名稱和副檔名來判斷要開啟的檔案的內容類型。displayName字串 (可選) - 要在 Quick Look 模態視圖上顯示的檔案名稱。這純粹是視覺效果，不會影響檔案的內容類型。預設為path。
使用 Quick Look 預覽給定路徑的檔案。
win.closeFilePreview() macOS
關閉目前開啟的 Quick Look 面板。
win.setBounds(bounds[, animate])
boundsPartial<Rectangle>animate布林值 (可選) macOS
調整視窗大小並將其移動到提供的邊界。任何未提供的屬性都將預設為其目前值。
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// set all bounds properties
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })
// set a single bounds property
win.setBounds({ width: 100 })
// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())
注意： 在 macOS 上，y 座標值不能小於 Tray 高度。Tray 高度隨時間而變化，並且取決於作業系統，但在 20-40 像素之間。傳遞小於 Tray 高度的值將導致視窗與 Tray 平齊。
win.getBounds()
回傳 Rectangle - 視窗的 bounds 作為 Object。
注意： 在 macOS 上，回傳的 y 座標值將至少為 Tray 高度。例如，使用 Tray 高度為 38 呼叫 win.setBounds({ x: 25, y: 20, width: 800, height: 600 }) 表示 win.getBounds() 將回傳 { x: 25, y: 38, width: 800, height: 600 }。
win.getBackgroundColor()
回傳 字串 - 以十六進位 (#RRGGBB) 格式取得視窗的背景顏色。
請參閱 設定 backgroundColor。
注意： alpha 值 *不會* 與紅色、綠色和藍色值一起回傳。
win.setContentBounds(bounds[, animate])
boundsRectangleanimate布林值 (可選) macOS
調整視窗用戶端區域（例如網頁）的大小並將其移動到提供的邊界。
win.getContentBounds()
回傳 Rectangle - 視窗用戶端區域的 bounds 作為 Object。
win.getNormalBounds()
回傳 Rectangle - 包含正常狀態的視窗邊界
注意： 無論視窗的目前狀態為何：最大化、最小化或全螢幕，此函數始終回傳正常狀態下視窗的位置和大小。在正常狀態下，getBounds 和 getNormalBounds 回傳相同的 Rectangle。
win.setEnabled(enable)
enable布林值
停用或啟用視窗。
win.isEnabled()
回傳 布林值 - 視窗是否已啟用。
win.setSize(width, height[, animate])
width整數height整數animate布林值 (可選) macOS
將視窗大小調整為 width 和 height。如果 width 或 height 低於任何設定的最小尺寸約束，視窗將貼齊其最小尺寸。
win.getSize()
回傳 整數[] - 包含視窗的寬度和高度。
win.setContentSize(width, height[, animate])
width整數height整數animate布林值 (可選) macOS
將視窗的用戶端區域（例如網頁）大小調整為 width 和 height。
win.getContentSize()
回傳 整數[] - 包含視窗用戶端區域的寬度和高度。
win.setMinimumSize(width, height)
width整數height整數
設定視窗的最小尺寸為 width 和 height。
win.getMinimumSize()
回傳 整數[] - 包含視窗的最小寬度和高度。
win.setMaximumSize(width, height)
width整數height整數
設定視窗的最大尺寸為 width 和 height。
win.getMaximumSize()
回傳 整數[] - 包含視窗的最大寬度和高度。
win.setResizable(resizable)
resizableboolean
設定視窗是否可讓使用者手動調整大小。
win.isResizable()
回傳 boolean - 視窗是否可讓使用者手動調整大小。
win.setMovable(movable) macOS Windows
movableboolean
設定視窗是否可讓使用者移動。在 Linux 上不會執行任何動作。
win.isMovable() macOS Windows
回傳 boolean - 視窗是否可讓使用者移動。
在 Linux 上永遠回傳 true。
win.setMinimizable(minimizable) macOS Windows
minimizableboolean
設定視窗是否可讓使用者手動最小化。在 Linux 上不會執行任何動作。
win.isMinimizable() macOS Windows
回傳 boolean - 視窗是否可讓使用者手動最小化。
在 Linux 上永遠回傳 true。
win.setMaximizable(maximizable) macOS Windows
maximizableboolean
設定視窗是否可讓使用者手動最大化。在 Linux 上不會執行任何動作。
win.isMaximizable() macOS Windows
回傳 boolean - 視窗是否可讓使用者手動最大化。
在 Linux 上永遠回傳 true。
win.setFullScreenable(fullscreenable)
fullscreenableboolean
設定最大化/縮放視窗按鈕是否切換為全螢幕模式或最大化視窗。
win.isFullScreenable()
回傳 boolean - 最大化/縮放視窗按鈕是否切換為全螢幕模式或最大化視窗。
win.setClosable(closable) macOS Windows
closableboolean
設定視窗是否可讓使用者手動關閉。在 Linux 上不會執行任何動作。
win.isClosable() macOS Windows
回傳 boolean - 視窗是否可讓使用者手動關閉。
在 Linux 上永遠回傳 true。
win.setHiddenInMissionControl(hidden) macOS
hiddenboolean
設定當使用者切換到「調度中心」時，視窗是否會被隱藏。
win.isHiddenInMissionControl() macOS
回傳 boolean - 當使用者切換到「調度中心」時，視窗是否會被隱藏。
win.setAlwaysOnTop(flag[, level][, relativeLevel])
flag布林值levelstring (選用) macOS Windows - 值包含normal、floating、torn-off-menu、modal-panel、main-menu、status、pop-up-menu、screen-saver和dockflag為 true 時，預設值為floating。當 flag 為 false 時，level會重設為normal。請注意，從floating到status(包含)，視窗會放置在 macOS 上的 Dock 下方以及 Windows 上的工作列下方。從pop-up-menu到更高的層級，它會顯示在 macOS 上的 Dock 上方以及 Windows 上的工作列上方。請參閱 macOS 文件 以取得更多詳細資訊。relativeLevelInteger (選用) macOS - 相對於給定的level，此視窗要設定高出多少層。預設值為0。請注意，Apple 不建議將層級設定高於screen-saver之上 1 層。
設定視窗是否應始終顯示在其他視窗之上。設定此選項後，視窗仍然是普通視窗，而不是無法聚焦的工具箱視窗。
win.isAlwaysOnTop()
回傳 boolean - 視窗是否始終在其他視窗之上。
win.moveAbove(mediaSourceId)
mediaSourceIdstring - 視窗 ID 格式為 DesktopCapturerSource 的 ID。例如 "window:1869:0"。
在 Z 軸順序上，將視窗移動到來源視窗上方。如果 mediaSourceId 不是視窗類型，或者視窗不存在，則此方法會擲回錯誤。
win.moveTop()
將視窗移動到最頂層 (Z 軸順序)，無論焦點為何。
win.center()
將視窗移動到螢幕中心。
win.setPosition(x, y[, animate])
xIntegeryIntegeranimate布林值 (可選) macOS
將視窗移動到 x 和 y。
win.getPosition()
回傳 Integer[] - 包含視窗目前的座標。
win.setTitle(title)
title字串
將原生視窗的標題變更為 title。
win.getTitle()
回傳 string - 原生視窗的標題。
注意： 網頁的標題可能與原生視窗的標題不同。
win.setSheetOffset(offsetY[, offsetX]) macOS
offsetYFloatoffsetXFloat (選用)
變更 macOS 上工作表的附加點。預設情況下，工作表會附加在視窗框架的正下方，但您可能會想要將它們顯示在 HTML 呈現的工具列下方。例如
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)
win.flashFrame(flag)
flag布林值
開始或停止閃爍視窗以吸引使用者注意。
win.setSkipTaskbar(skip) macOS Windows
skipboolean
使視窗不顯示在工作列中。
win.setKiosk(flag)
flag布林值
進入或離開 Kiosk 模式。
win.isKiosk()
回傳 boolean - 視窗是否處於 Kiosk 模式。
win.isTabletMode() Windows
回傳 boolean - 視窗是否處於 Windows 10 平板電腦模式。
由於 Windows 10 使用者可以將其 PC 當作平板電腦使用，在此模式下，應用程式可以選擇最佳化其平板電腦的 UI，例如放大標題列和隱藏標題列按鈕。
此 API 會回傳視窗是否處於平板電腦模式，並且 resize 事件可用於監聽平板電腦模式的變更。
win.getMediaSourceId()
回傳 string - 視窗 ID 格式為 DesktopCapturerSource 的 ID。例如 "window:1324:0"。
更精確的格式為 window:id:other_id，其中 id 在 Windows 上是 HWND，在 macOS 上是 CGWindowID (uint64_t)，在 Linux 上是 Window (unsigned long)。other_id 用於識別 Web 內容 (分頁)，因此在同一個最上層視窗中。
win.getNativeWindowHandle()
回傳 Buffer - 視窗的平台特定控制代碼。
控制代碼的原生類型在 Windows 上是 HWND，在 macOS 上是 NSView*，在 Linux 上是 Window (unsigned long)。
win.hookWindowMessage(message, callback) Windows
messageIntegercallbackFunctionwParamBuffer - 提供給 WndProc 的wParamlParamBuffer - 提供給 WndProc 的lParam
掛鉤視窗訊息。當訊息在 WndProc 中收到時，會呼叫 callback。
win.isWindowMessageHooked(message) Windows
messageInteger
回傳 boolean - true 或 false，取決於訊息是否被掛鉤。
win.unhookWindowMessage(message) Windows
messageInteger
取消掛鉤視窗訊息。
win.unhookAllWindowMessages() Windows
取消掛鉤所有視窗訊息。
win.setRepresentedFilename(filename) macOS
filenamestring
設定視窗代表的檔案路徑名稱，檔案的圖示將顯示在視窗的標題列中。
win.getRepresentedFilename() macOS
回傳 string - 視窗代表的檔案路徑名稱。
win.setDocumentEdited(edited) macOS
editedboolean
指定視窗的文件是否已被編輯，當設定為 true 時，標題列中的圖示將變為灰色。
win.isDocumentEdited() macOS
回傳 boolean - 視窗的文件是否已被編輯。
win.focusOnWebView()
win.blurWebView()
win.capturePage([rect, opts])
rectRectangle (選用) - 要擷取的邊界optsObject (選用)stayHiddenboolean (選用) - 保持頁面隱藏而不是可見。預設值為false。stayAwakeboolean (選用) - 保持系統喚醒，而不是允許其進入睡眠狀態。預設值為false。
回傳 Promise<NativeImage> - 使用 NativeImage 解析
擷取 rect 內頁面的快照。省略 rect 將擷取整個可見頁面。如果頁面不可見，則 rect 可能為空。當頁面的瀏覽器視窗隱藏且擷取器計數不為零時，頁面會被視為可見。如果您希望頁面保持隱藏，則應確保將 stayHidden 設定為 true。
win.loadURL(url[, options])
urlstring
回傳 Promise<void> - 當頁面完成載入時，promise 將會解析 (請參閱 did-finish-load)，如果頁面載入失敗，則會拒絕 (請參閱 did-fail-load)。
與 webContents.loadURL(url[, options]) 相同。
url 可以是遠端位址 (例如 http://) 或使用 file:// 協定的本機 HTML 檔案路徑。
為了確保檔案網址的格式正確，建議使用 Node 的 url.format 方法
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const url = require('url').format({
protocol: 'file',
slashes: true,
pathname: require('node:path').join(__dirname, 'index.html')
})
win.loadURL(url)
您可以使用 POST 請求和 URL 編碼的資料來載入 URL，方法如下
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('http://localhost:8000/post', {
postData: [{
type: 'rawData',
bytes: Buffer.from('hello=world')
}],
extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})
win.loadFile(filePath[, options])
filePathstring
回傳 Promise<void> - 當頁面完成載入時，promise 將會解析 (請參閱 did-finish-load)，如果頁面載入失敗，則會拒絕 (請參閱 did-fail-load)。
與 webContents.loadFile 相同，filePath 應該是相對於應用程式根目錄的 HTML 檔案路徑。請參閱 webContents 文件以取得更多資訊。
win.reload()
與 webContents.reload 相同。
win.setMenu(menu) Linux Windows
menuMenu | null
將 menu 設定為視窗的選單列。
win.removeMenu() Linux Windows
移除視窗的選單列。
win.setProgressBar(progress[, options])
progressDouble
設定進度列中的進度值。有效範圍為 [0, 1.0]。
當進度 < 0 時移除進度列；當進度 > 1 時變更為不確定模式。
在 Linux 平台上，僅支援 Unity 桌面環境，您需要在 package.json 的 desktopName 欄位中指定 *.desktop 檔案名稱。預設情況下，它會假設為 {app.name}.desktop。
在 Windows 上，可以傳遞模式。接受的值為 none、normal、indeterminate、error 和 paused。如果您在未設定模式的情況下呼叫 setProgressBar (但值在有效範圍內)，則會假設為 normal。
win.setOverlayIcon(overlay, description) Windows
overlayNativeImage | null - 要顯示在工作列圖示右下角的圖示。如果此參數為null，則會清除覆蓋圖示descriptionstring - 將提供給輔助功能螢幕閱讀器的描述
在目前的工作列圖示上設定 16 x 16 像素的覆蓋圖示，通常用於傳達某種應用程式狀態或被動地通知使用者。
win.invalidateShadow() macOS
使視窗陰影失效，以便根據目前的視窗形狀重新計算。
透明的 BrowserWindows 有時會在 macOS 上留下視覺瑕疵。例如，在執行動畫時，可以使用此方法來清除這些瑕疵。
win.setHasShadow(hasShadow)
hasShadowboolean
設定視窗是否應具有陰影。
win.hasShadow()
回傳 boolean - 視窗是否具有陰影。
win.setOpacity(opacity) Windows macOS
opacitynumber - 介於 0.0 (完全透明) 和 1.0 (完全不透明) 之間
設定視窗的不透明度。在 Linux 上，不會執行任何動作。超出範圍的數字值會箝制在 [0, 1] 範圍內。
win.getOpacity()
回傳 number - 介於 0.0 (完全透明) 和 1.0 (完全不透明) 之間。在 Linux 上，永遠回傳 1。
win.setShape(rects) Windows Linux Experimental
rectsRectangle[] - 在視窗上設定形狀。傳遞空列表會將視窗還原為矩形。
設定視窗形狀會決定系統允許在視窗內繪圖和使用者互動的區域。在給定區域之外，不會繪製任何像素，也不會註冊任何滑鼠事件。區域外的滑鼠事件不會被該視窗接收，而是會穿透到視窗後面的任何內容。
win.setThumbarButtons(buttons) Windows
buttonsThumbarButton[]
回傳 boolean - 按鈕是否已成功新增
將具有指定按鈕集成的縮圖工具列新增到工作列按鈕版面配置中視窗的縮圖影像。回傳一個 boolean 物件，指示是否已成功新增縮圖。
由於空間有限，縮圖工具列中的按鈕數量不應超過 7 個。設定縮圖工具列後，由於平台的限制，工具列無法移除。但是您可以呼叫具有空陣列的 API 來清除按鈕。
buttons 是 Button 物件的陣列
Button物件iconNativeImage - 縮圖工具列中顯示的圖示。clickFunctiontooltipstring (選用) - 按鈕工具提示的文字。flagsstring[] (選用) - 控制按鈕的特定狀態和行為。預設情況下，它是['enabled']。
flags 是一個陣列，可以包含以下 string
enabled- 按鈕處於活動狀態，使用者可以使用。disabled- 按鈕已停用。它存在，但具有視覺狀態，表示它不會回應使用者動作。dismissonclick- 當按鈕被點擊時，縮圖視窗會立即關閉。nobackground- 不繪製按鈕邊框，僅使用影像。hidden- 按鈕未向使用者顯示。noninteractive- 按鈕已啟用但不具互動性；不會繪製按下按鈕的狀態。此值適用於按鈕用於通知的情況。
win.setThumbnailClip(region) Windows
regionRectangle - 視窗區域
設定當滑鼠懸停在工作列中的視窗上時，要顯示為縮圖影像的視窗區域。您可以指定空區域來將縮圖重設為整個視窗：{ x: 0, y: 0, width: 0, height: 0 }。
win.setThumbnailToolTip(toolTip) Windows
toolTipstring
設定當滑鼠懸停在工作列中的視窗縮圖上時顯示的工具提示。
win.setAppDetails(options) Windows
設定視窗工作列按鈕的屬性。
注意： relaunchCommand 和 relaunchDisplayName 必須始終一起設定。如果未設定其中一個屬性，則兩者都不會使用。
win.showDefinitionForSelection() macOS
與 webContents.showDefinitionForSelection() 相同。
win.setIcon(icon) Windows Linux
iconNativeImage | string
變更視窗圖示。
win.setWindowButtonVisibility(visible) macOS
visibleboolean
設定視窗交通號誌按鈕是否應可見。
win.setAutoHideMenuBar(hide) Windows Linux
hideboolean
設定視窗選單列是否應自動隱藏。設定後，選單列只會在使用者按下單個 Alt 鍵時顯示。
如果選單列已可見，則呼叫 setAutoHideMenuBar(true) 不會立即隱藏它。
win.isMenuBarAutoHide() Windows Linux
回傳 boolean - 選單列是否自動隱藏。
win.setMenuBarVisibility(visible) Windows Linux
visibleboolean
設定選單列是否應可見。如果選單列是自動隱藏的，使用者仍然可以透過按下單個 Alt 鍵來顯示選單列。
win.isMenuBarVisible() Windows Linux
回傳 boolean - 選單列是否可見。
win.setVisibleOnAllWorkspaces(visible[, options]) macOS Linux
visibleboolean
設定視窗是否應在所有工作區中可見。
注意： 此 API 在 Windows 上不會執行任何動作。
win.isVisibleOnAllWorkspaces() macOS Linux
回傳 boolean - 視窗是否在所有工作區中可見。
注意： 此 API 在 Windows 上永遠回傳 false。
win.setIgnoreMouseEvents(ignore[, options])
ignoreboolean
使視窗忽略所有滑鼠事件。
在此視窗中發生的所有滑鼠事件都將傳遞到此視窗下方的視窗，但是如果此視窗具有焦點，它仍然會接收鍵盤事件。
win.setContentProtection(enable) macOS Windows
enable布林值
防止其他應用程式擷取視窗內容。
在 macOS 上，它將 NSWindow 的 sharingType 設定為 NSWindowSharingNone。在 Windows 上，它使用 WDA_EXCLUDEFROMCAPTURE 呼叫 SetWindowDisplayAffinity。對於 Windows 10 2004 版及更高版本，視窗將完全從擷取中移除，較舊的 Windows 版本行為如同套用了 WDA_MONITOR，擷取黑色視窗。
win.setFocusable(focusable) macOS Windows
focusableboolean
變更視窗是否可以被聚焦。
在 macOS 上，它不會從視窗中移除焦點。
win.isFocusable() macOS Windows
回傳 boolean - 視窗是否可以被聚焦。
win.setParentWindow(parent)
parentBrowserWindow | null
將 parent 設定為目前視窗的父視窗，傳遞 null 會將目前視窗變成最上層視窗。
win.getParentWindow()
回傳 BrowserWindow | null - 父視窗，如果沒有父視窗則為 null。
win.getChildWindows()
傳回 BrowserWindow[] - 所有子視窗。
win.setAutoHideCursor(autoHide) macOS
autoHide布林值
控制當輸入時是否隱藏游標。
win.selectPreviousTab() macOS
當啟用原生分頁且視窗中還有其他分頁時，選取上一個分頁。
win.selectNextTab() macOS
當啟用原生分頁且視窗中還有其他分頁時，選取下一個分頁。
win.showAllTabs() macOS
當啟用原生分頁時，顯示或隱藏分頁概覽。
win.mergeAllWindows() macOS
當啟用原生分頁且有多個開啟的視窗時，將所有視窗合併為一個具有多個分頁的視窗。
win.moveTabToNewWindow() macOS
如果啟用原生分頁且目前視窗中有多個分頁，則將目前分頁移動到新視窗。
win.toggleTabBar() macOS
如果啟用原生分頁且目前視窗中只有一個分頁，則切換分頁列的顯示狀態。
win.addTabbedWindow(browserWindow) macOS
browserWindowBrowserWindow
在此視窗上新增一個視窗作為分頁，在視窗實例的分頁之後。
win.setVibrancy(type[, options]) macOS
type字串 | null - 可以是titlebar、selection、menu、popover、sidebar、header、sheet、window、hud、fullscreen-ui、tooltip、content、under-window或under-page。 有關詳細資訊，請參閱 macOS 文件。
為瀏覽器視窗新增鮮豔效果。傳遞 null 或空字串將移除視窗上的鮮豔效果。 animationDuration 參數僅對鮮豔效果的淡入或淡出進行動畫處理。 不支援在不同類型的鮮豔度之間進行動畫處理。
win.setBackgroundMaterial(material) Windows
material字串auto- 讓桌面視窗管理員 (DWM) 自動決定此視窗的系統繪製背景素材。這是預設值。none- 不繪製任何系統背景。mica- 繪製對應於長期存在的視窗的背景素材效果。acrylic- 繪製對應於暫時性視窗的背景素材效果。tabbed- 繪製對應於具有分頁標題列的視窗的背景素材效果。
此方法設定瀏覽器視窗的系統繪製背景素材，包括非用戶端區域的後面。
有關詳細資訊，請參閱 Windows 文件。
注意： 此方法僅在 Windows 11 22H2 及更高版本上受支援。
win.setWindowButtonPosition(position) macOS
positionPoint | null
為無邊框視窗中的交通號誌按鈕設定自訂位置。 傳遞 null 將重置位置為預設值。
win.getWindowButtonPosition() macOS
傳回 Point | null - 無邊框視窗中交通號誌按鈕的自訂位置，當沒有自訂位置時，將傳回 null。
win.setTouchBar(touchBar) macOS
touchBarTouchBar | null
為目前視窗設定 TouchBar 佈局。 指定 null 或 undefined 會清除 Touch Bar。 此方法僅在機器具有 Touch Bar 時有效。
注意： TouchBar API 目前為實驗性功能，可能會在未來的 Electron 版本中變更或移除。
win.setBrowserView(browserView) 實驗性 已棄用
browserViewBrowserView | null - 將browserView附加到win。 如果有其他附加的BrowserView，它們將會從此視窗中移除。
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.getBrowserView() 實驗性 已棄用
傳回 BrowserView | null - 附加到 win 的 BrowserView。 如果沒有附加，則傳回 null。 如果附加了多個 BrowserView，則會拋出錯誤。
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.addBrowserView(browserView) 實驗性 已棄用
browserViewBrowserView
用於支援使用多個瀏覽器視圖的 setBrowserView 替代 API。
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.removeBrowserView(browserView) 實驗性 已棄用
browserViewBrowserView
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.setTopBrowserView(browserView) 實驗性 已棄用
browserViewBrowserView
將 browserView 提升到附加到 win 的其他 BrowserView 之上。 如果 browserView 未附加到 win，則會拋出錯誤。
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.getBrowserViews() 實驗性 已棄用
傳回 BrowserView[] - 依 z 索引排序的所有 BrowserView 陣列，這些 BrowserView 已使用 addBrowserView 或 setBrowserView 附加。 最頂層的 BrowserView 是陣列的最後一個元素。
注意
BrowserView類別已棄用，並被新的WebContentsView類別取代。
win.setTitleBarOverlay(options) Windows Linux
在已啟用視窗控制項覆疊的視窗上，此方法會更新標題列覆疊的樣式。
在 Linux 上，如果未明確設定 symbolColor，則會自動計算 symbolColor 以使其與 color 具有最小的可訪問對比度。