Electron BrowserWindow 模塊

BrowserWindow 類讓你有創(chuàng)建一個瀏覽器窗口的權力。例如:

// In the main process.
const BrowserWindow = require('electron').BrowserWindow;

// Or in the renderer process.
const BrowserWindow = require('electron').remote.BrowserWindow;

var win = new BrowserWindow({ width: 800, height: 600, show: false });
win.on('closed', function() {
  win = null;
});

win.loadURL('https://github.com');
win.show();

你也可以不通過chrome創(chuàng)建窗口，使用 Frameless Window API.

Class: BrowserWindow

BrowserWindow 是一個 EventEmitter.

通過 options 可以創(chuàng)建一個具有本質(zhì)屬性的 BrowserWindow 。

new BrowserWindow([options])

• options Object
  • width Integer - 窗口寬度,單位像素. 默認是 800。
  • height Integer - 窗口高度,單位像素. 默認是 600。
  • x Integer - 窗口相對于屏幕的左偏移位置.默認居中。
  • y Integer - 窗口相對于屏幕的頂部偏移位置.默認居中。
  • useContentSize Boolean - width 和 height 使用web網(wǎng)頁size, 這意味著實際窗口的size應該包括窗口框架的size，稍微會大一點，默認為 false。
  • center Boolean - 窗口屏幕居中。
  • minWidth Integer - 窗口最小寬度，默認為 0。
  • minHeight Integer - 窗口最小高度，默認為 0。
  • maxWidth Integer - 窗口最大寬度，默認無限制。
  • maxHeight Integer - 窗口最大高度，默認無限制。
  • resizable Boolean - 是否可以改變窗口size，默認為 true。
  • movable Boolean - 窗口是否可以拖動. 在 Linux 上無效. 默認為 true。
  • minimizable Boolean - 窗口是否可以最小化. 在 Linux 上無效. 默認為 true。
  • maximizable Boolean - 窗口是否可以最大化. 在 Linux 上無效. 默認為 true。
  • closable Boolean - 窗口是否可以關閉. 在 Linux 上無效. 默認為 true。
  • alwaysOnTop Boolean - 窗口是否總是顯示在其他窗口之前. 在 Linux 上無效. 默認為 false。
  • fullscreen Boolean - 窗口是否可以全屏幕. 當明確設置值為When false ，全屏化按鈕將會隱藏，在 OS X 將禁用. 默認 false。
  • fullscreenable Boolean - 在 OS X 上，全屏化按鈕是否可用，默認為 true。
  • skipTaskbar Boolean - 是否在任務欄中顯示窗口. 默認是false。
  • kiosk Boolean - kiosk 方式. 默認為 false。
  • title String - 窗口默認title. 默認 "Electron"。
  • icon NativeImage - 窗口圖標, 如果不設置，窗口將使用可用的默認圖標。
  • show Boolean - 窗口創(chuàng)建的時候是否顯示. 默認為 true。
  • frame Boolean - 指定 false 來創(chuàng)建一個 Frameless Window. 默認為 true。
  • acceptFirstMouse Boolean - 是否允許單擊web view來激活窗口。默認為 false。
  • disableAutoHideCursor Boolean - 當 typing 時是否隱藏鼠標.默認 false。
  • autoHideMenuBar Boolean - 除非點擊 Alt，否則隱藏菜單欄.默認為 false。
  • enableLargerThanScreen Boolean - 是否允許允許改變窗口大小大于屏幕. 默認是 false。
  • backgroundColor String -窗口的 background color 值為十六進制，如 #66CD00 或 #FFF 或 #80FFFFFF (支持透明度)。默認為在 Linux 和 Windows 上為 #000 (黑色)，Mac上為 #FFF(或透明)。
  • hasShadow Boolean - 窗口是否有陰影。只在 OS X 上有效. 默認為 true。
  • darkTheme Boolean - 為窗口使用 dark 主題，只在一些擁有 GTK+3 桌面環(huán)境上有效. 默認為 false。
  • transparent Boolean - 窗口透明。默認為 false。
  • type String - 窗口type，默認普通窗口，下面查看更多。
  • titleBarStyle String - 窗口標題欄樣式，下面查看更多。
  • webPreferences Object - 設置界面特性，下面查看更多。

type 的值和效果不同平臺展示效果不同，具體:

• Linux，可用值為 desktop， dock， toolbar， splash， notification。
• OS X，可用值為 desktop， textured。
  • textured type 添加金屬梯度效果 (NSTexturedBackgroundWindowMask)。
  • desktop 設置窗口在桌面背景窗口水平 (kCGDesktopWindowLevel - 1)。注意桌面窗口不可聚焦，不可不支持鍵盤和鼠標事件，但是可以使用 globalShortcut 來解決輸入問題。

titleBarStyle 只在 OS X 10.10 Yosemite 或更新版本上支持，可用值：

• default 以及無值, 顯示在 Mac 標題欄上為不透明的標準灰色。
• hidden 隱藏標題欄，內(nèi)容充滿整個窗口, 然后它依然在左上角，仍然受標準窗口控制。
• hidden-inset主體隱藏，顯示小的控制按鈕在窗口邊緣。

webPreferences 參數(shù)是個對象，它的屬性：

• nodeIntegration Boolean - 是否完整支持node。默認為 true。
• preload String - 界面的其它腳本運行之前預先加載一個指定腳本。這個腳本將一直可以使用 node APIs 無論 node integration 是否開啟。腳本路徑為絕對路徑。當 node integration 關閉，預加載的腳本將從全局范圍重新引入node的全局引用標志。查看例子 here。
• session Session - 設置界面session。而不是直接忽略session對象，也可用 partition 來代替，它接受一個 partition 字符串。當同時使用 session 和 partition， session 優(yōu)先級更高. 默認使用默認 session。
• partition String - 通過session的partition字符串來設置界面session. 如果 partition 以 persist:開頭, 這個界面將會為所有界面使用相同的 partition. 如果沒有 persist: 前綴, 界面使用歷史session. 通過分享同一個 partition，所有界面使用相同的session. 默認使用默認 session.
• zoomFactor Number - 界面默認縮放值，3.0 表示 300%. 默認 1.0.
• javascript Boolean - 開啟javascript支持. 默認為true.
• webSecurity Boolean - 當設置為 false，它將禁用相同地方的規(guī)則 (通常測試服), 并且如果有2個非用戶設置的參數(shù)，就設置 allowDisplayingInsecureContent 和 allowRunningInsecureContent 的值為true. 默認為 true.
• allowDisplayingInsecureContent Boolean -允許一個使用 https的界面來展示由 http URLs 傳過來的資源. 默認false.
• allowRunningInsecureContent Boolean - Boolean -允許一個使用 https的界面來渲染由 http URLs 提交的html,css,javascript. 默認為 false。
• images Boolean - 開啟圖片使用支持. 默認 true.
• textAreasAreResizable Boolean - textArea 可以編輯. 默認為 true.
• webgl Boolean - 開啟 WebGL 支持. 默認為 true.
• webaudio Boolean - 開啟 WebAudio 支持. 默認為 true.
• plugins Boolean - 是否開啟插件支持. 默認為 false.
• experimentalFeatures Boolean - 開啟 Chromium 的 可測試 特性. 默認為 false.
• experimentalCanvasFeatures Boolean - 開啟 Chromium 的 canvas 可測試特性. 默認為 false.
• directWrite Boolean - 開啟窗口的 DirectWrite font 渲染系統(tǒng). 默認為 true.
• blinkFeatures String - 以 , 分隔的特性列表, 如 CSSVariables,KeyboardEventKey. 被支持的所有特性可在 setFeatureEnabledFromString 中找到.
• defaultFontFamily Object - 設置 font-family 默認字體.
  • standard String - 默認為 Times New Roman.
  • serif String - 默認為 Times New Roman.
  • sansSerif String - 默認為 Arial.
  • monospace String - 默認為 Courier New.
• defaultFontSize Integer - 默認為 16.
• defaultMonospaceFontSize Integer - 默認為 13.
• minimumFontSize Integer - 默認為 0.
• defaultEncoding String - 默認為 ISO-8859-1.

事件

BrowserWindow 對象可觸發(fā)下列事件:

注意: 一些事件只能在特定os環(huán)境中觸發(fā)，已經(jīng)盡可能地標出.

Event: 'page-title-updated'

返回:

• event Event

當文檔改變標題時觸發(fā),使用 event.preventDefault() 可以阻止原窗口的標題改變.

Event: 'close'

返回:

• event Event

在窗口要關閉的時候觸發(fā). 它在DOM的 beforeunload and unload 事件之前觸發(fā).使用 event.preventDefault() 可以取消這個操作

通常你想通過 beforeunload 處理器來決定是否關閉窗口，但是它也會在窗口重載的時候被觸發(fā)。在 Electron 中，返回一個空的字符串或 false 可以取消關閉.例如:

window.onbeforeunload = function(e) {
  console.log('I do not want to be closed');

  // Unlike usual browsers, in which a string should be returned and the user is
  // prompted to confirm the page unload, Electron gives developers more options.
  // Returning empty string or false would prevent the unloading now.
  // You can also use the dialog API to let the user confirm closing the application.
  e.returnValue = false;
};

Event: 'closed'

當窗口已經(jīng)關閉的時候觸發(fā).當你接收到這個事件的時候，你應當刪除對已經(jīng)關閉的窗口的引用對象和避免再次使用它.

Event: 'unresponsive'

在界面卡死的時候觸發(fā)事件.

Event: 'responsive'

在界面恢復卡死的時候觸發(fā).

Event: 'blur'

在窗口失去焦點的時候觸發(fā).

Event: 'focus'

在窗口獲得焦點的時候觸發(fā).

Event: 'maximize'

在窗口最大化的時候觸發(fā).

Event: 'unmaximize'

在窗口退出最大化的時候觸發(fā).

Event: 'minimize'

在窗口最小化的時候觸發(fā).

Event: 'restore'

在窗口從最小化恢復的時候觸發(fā).

Event: 'resize'

在窗口size改變的時候觸發(fā).

Event: 'move'

在窗口移動的時候觸發(fā).

注意：在 OS X 中別名為 moved.

Event: 'moved' OS X

在窗口移動的時候觸發(fā).

Event: 'enter-full-screen'

在的窗口進入全屏狀態(tài)時候觸發(fā).

Event: 'leave-full-screen'

在的窗口退出全屏狀態(tài)時候觸發(fā).

Event: 'enter-html-full-screen'

在的窗口通過 html api 進入全屏狀態(tài)時候觸發(fā).

Event: 'leave-html-full-screen'

在的窗口通過 html api 退出全屏狀態(tài)時候觸發(fā).

Event: 'app-command' Windows

在請求一個App Command.aspx)的時候觸發(fā). 典型的是鍵盤媒體或瀏覽器命令, Windows上的 "Back" 按鈕用作鼠標也會觸發(fā).

someWindow.on('app-command', function(e, cmd) {
  // Navigate the window back when the user hits their mouse back button
  if (cmd === 'browser-backward' && someWindow.webContents.canGoBack()) {
    someWindow.webContents.goBack();
  }
});

Event: 'scroll-touch-begin' OS X

在滾動條事件開始的時候觸發(fā).

Event: 'scroll-touch-end' OS X

在滾動條事件結束的時候觸發(fā).

方法

BrowserWindow 對象有如下方法:

BrowserWindow.getAllWindows()

返回一個所有已經(jīng)打開了窗口的對象數(shù)組.

BrowserWindow.getFocusedWindow()

返回應用當前獲得焦點窗口,如果沒有就返回 null.

BrowserWindow.fromWebContents(webContents)

• webContents WebContents

根據(jù) webContents 查找窗口.

BrowserWindow.fromId(id)

• id Integer

根據(jù) id 查找窗口.

BrowserWindow.addDevToolsExtension(path)

• path String

添加位于 path 的開發(fā)者工具欄擴展,并且返回擴展項的名字.

這個擴展會被添加到歷史，所以只需要使用這個API一次，這個api不可用作編程使用.

BrowserWindow.removeDevToolsExtension(name)

• name String

刪除開發(fā)者工具欄名為 name 的擴展.

實例屬性

使用 new BrowserWindow 創(chuàng)建的實例對象，有如下屬性:

// In this example `win` is our instance
var win = new BrowserWindow({ width: 800, height: 600 });

win.webContents

這個窗口的 WebContents 對象，所有與界面相關的事件和方法都通過它完成的.

查看 webContents documentation 的方法和事件.

win.id

窗口的唯一id.

實例方法

使用 new BrowserWindow 創(chuàng)建的實例對象，有如下方法:

注意: 一些方法只能在特定os環(huán)境中調(diào)用，已經(jīng)盡可能地標出.

win.destroy()

強制關閉窗口, unload and beforeunload 不會觸發(fā)，并且 close 也不會觸發(fā), 但是它保證了 closed 觸發(fā).

win.close()

嘗試關閉窗口，這與用戶點擊關閉按鈕的效果一樣. 雖然網(wǎng)頁可能會取消關閉，查看 close event.

win.focus()

窗口獲得焦點.

win.isFocused()

返回 boolean, 窗口是否獲得焦點.

win.show()

展示并且使窗口獲得焦點.

win.showInactive()

展示窗口但是不獲得焦點.

win.hide()

隱藏窗口.

win.isVisible()

返回 boolean, 窗口是否可見.

win.maximize()

窗口最大化.

win.unmaximize()

取消窗口最大化.

win.isMaximized()

返回 boolean, 窗口是否最大化.

win.minimize()

窗口最小化. 在一些os中，它將在dock中顯示.

win.restore()

將最小化的窗口恢復為之前的狀態(tài).

win.isMinimized()

返回 boolean, 窗口是否最小化.

win.setFullScreen(flag)

• flag Boolean

設置是否全屏.

win.isFullScreen()

返回 boolean, 窗口是否全屏化.

win.setAspectRatio(aspectRatio[, extraSize]) OS X

• aspectRatio 維持部分視圖內(nèi)容窗口的高寬比值.
• extraSize Object (可選) - 維持高寬比值時不包含的額外size.
  • width Integer
  • height Integer

由一個窗口來維持高寬比值. extraSize 允許開發(fā)者使用它，它的單位為像素，不包含在 aspectRatio 中.這個 API 可用來區(qū)分窗口的size和內(nèi)容的size .

想象一個普通可控的HD video 播放器窗口. 假如左邊緣有15控制像素，右邊緣有25控制像素，在播放器下面有50控制像素.為了在播放器內(nèi)保持一個 16:9 的高寬比例，我們可以調(diào)用這個api傳入?yún)?shù)16/9 and [ 40, 50 ].第二個參數(shù)不管網(wǎng)頁中的額外的寬度和高度在什么位置，只要它們存在就行.只需要把網(wǎng)頁中的所有額外的高度和寬度加起來就行.

win.setBounds(options[, animate])

• options Object
  • x Integer
  • y Integer
  • width Integer
  • height Integer
• animate Boolean (可選) OS X

重新設置窗口的寬高值，并且移動到指定的 x, y 位置.

win.getBounds()

返回一個對象，它包含了窗口的寬，高，x坐標，y坐標.

win.setSize(width, height[, animate])

• width Integer
• height Integer
• animate Boolean (可選) OS X

重新設置窗口的寬高值.

win.getSize()

返回一個數(shù)組，它包含了窗口的寬，高.

win.setContentSize(width, height[, animate])

• width Integer
• height Integer
• animate Boolean (可選) OS X

重新設置窗口客戶端的寬高值（例如網(wǎng)頁界面）.

win.getContentSize()

返回一個數(shù)組，它包含了窗口客戶端的寬，高.

win.setMinimumSize(width, height)

• width Integer
• height Integer

設置窗口最小化的寬高值.

win.getMinimumSize()

返回一個數(shù)組，它包含了窗口最小化的寬，高.

win.setMaximumSize(width, height)

• width Integer
• height Integer

設置窗口最大化的寬高值.

win.getMaximumSize()

返回一個數(shù)組，它包含了窗口最大化的寬，高.

win.setResizable(resizable)

• resizable Boolean

設置窗口是否可以被用戶改變size.

win.isResizable()

返回 boolean,窗口是否可以被用戶改變size.

win.setMovable(movable) OS X Windows

• movable Boolean

設置窗口是否可以被用戶拖動. Linux 無效.

win.isMovable() OS X Windows

返回 boolean,窗口是否可以被用戶拖動. Linux 總是返回 true.

win.setMinimizable(minimizable) OS X Windows

• minimizable Boolean

設置窗口是否可以最小化. Linux 無效.

win.isMinimizable() OS X Windows

返回 boolean,窗口是否可以最小化. Linux 總是返回 true.

win.setMaximizable(maximizable) OS X Windows

• maximizable Boolean

設置窗口是否可以最大化. Linux 無效.

win.isMaximizable() OS X Windows

返回 boolean,窗口是否可以最大化. Linux 總是返回 true.

win.setFullScreenable(fullscreenable)

• fullscreenable Boolean

設置點擊最大化按鈕是否可以全屏或最大化窗口.

win.isFullScreenable()

返回 boolean,點擊最大化按鈕是否可以全屏或最大化窗口.

win.setClosable(closable) OS X Windows

• closable Boolean

設置窗口是否可以人為關閉. Linux 無效.

win.isClosable() OS X Windows

返回 boolean,窗口是否可以人為關閉. Linux 總是返回 true.

win.setAlwaysOnTop(flag)

• flag Boolean

是否設置這個窗口始終在其他窗口之上.設置之后，這個窗口仍然是一個普通的窗口，不是一個不可以獲得焦點的工具箱窗口.

win.isAlwaysOnTop()

返回 boolean,當前窗口是否始終在其它窗口之前.

win.center()

窗口居中.

win.setPosition(x, y[, animate])

• x Integer
• y Integer
• animate Boolean (可選) OS X

移動窗口到對應的 x and y 坐標.

win.getPosition()

返回一個包含當前窗口位置的數(shù)組.

win.setTitle(title)

• title String

改變原窗口的title.

win.getTitle()

返回原窗口的title.

注意: 界面title可能和窗口title不相同.

win.flashFrame(flag)

• flag Boolean

開始或停止顯示窗口來獲得用戶的關注.

win.setSkipTaskbar(skip)

• skip Boolean

讓窗口不在任務欄中顯示.

win.setKiosk(flag)

• flag Boolean

進入或離開 kiosk 模式.

win.isKiosk()

返回 boolean,是否進入或離開 kiosk 模式.

win.getNativeWindowHandle()

以 Buffer 形式返回這個具體平臺的窗口的句柄.

windows上句柄類型為 HWND ，OS X NSView* ， Linux Window.

win.hookWindowMessage(message, callback) Windows

• message Integer
• callback Function

攔截windows 消息，在 WndProc 接收到消息時觸發(fā) callback函數(shù).

win.isWindowMessageHooked(message) Windows

• message Integer

返回 true or false 來代表是否攔截到消息.

win.unhookWindowMessage(message) Windows

• message Integer

不攔截窗口消息.

win.unhookAllWindowMessages() Windows

窗口消息全部不攔截.

win.setRepresentedFilename(filename) OS X

• filename String

設置窗口當前文件路徑，并且將這個文件的圖標放在窗口標題欄上.

win.getRepresentedFilename() OS X

獲取窗口當前文件路徑.

win.setDocumentEdited(edited) OS X

• edited Boolean

明確指出窗口文檔是否可以編輯，如果可以編輯則將標題欄的圖標變成灰色.

win.isDocumentEdited() OS X

返回 boolean,當前窗口文檔是否可編輯.

win.focusOnWebView()

win.blurWebView()

win.capturePage([rect, ]callback)

• rect Object (可選) - 捕獲Page位置
  • x Integer
  • y Integer
  • width Integer
  • height Integer
• callback Function

捕獲 rect 中的page 的快照.完成后將調(diào)用回調(diào)函數(shù) callback 并返回 image . image 是存儲了快照信息的NativeImage實例.如果不設置 rect 則將捕獲所有可見page.

win.print([options])

類似 webContents.print([options])

win.printToPDF(options, callback)

類似 webContents.printToPDF(options, callback)

win.loadURL(url[, options])

類似 webContents.loadURL(url[, options]).

win.reload()

類似 webContents.reload.

win.setMenu(menu) Linux Windows

• menu Menu

設置菜單欄的 menu ，設置它為 null 則表示不設置菜單欄.

win.setProgressBar(progress)

• progress Double

在進度條中設置進度值，有效范圍 [0, 1.0].

當進度小于0時則不顯示進度; 當進度大于0時顯示結果不確定.

在libux上，只支持Unity桌面環(huán)境，需要指明 *.desktop 文件并且在 package.json 中添加文件名字.默認它為 app.getName().desktop.

win.setOverlayIcon(overlay, description) Windows 7+

• overlay NativeImage - 在底部任務欄右邊顯示圖標.
• description String - 描述.

向當前任務欄添加一個 16 x 16 像素的圖標，通常用來覆蓋一些應用的狀態(tài)，或者直接來提示用戶.

win.setHasShadow(hasShadow) OS X

• hasShadow (Boolean)

設置窗口是否應該有陰影.在Windows和Linux系統(tǒng)無效.

win.hasShadow() OS X

返回 boolean,設置窗口是否有陰影.在Windows和Linux系統(tǒng)始終返回 true.

win.setThumbarButtons(buttons) Windows 7+

• buttons Array

在窗口的任務欄button布局出為縮略圖添加一個有特殊button的縮略圖工具欄. 返回一個 Boolean 對象來指示是否成功添加這個縮略圖工具欄.

因為空間有限，縮略圖工具欄上的 button 數(shù)量不應該超過7個.一旦設置了，由于平臺限制，就不能移動它了.但是你可使用一個空數(shù)組來調(diào)用api來清除 buttons .

所有 buttons 是一個 Button 對象數(shù)組:

• Button Object
  • icon NativeImage - 在工具欄上顯示的圖標.
  • click Function
  • tooltip String (可選) - tooltip 文字.
  • flags Array (可選) - 控制button的狀態(tài)和行為. 默認它是 ['enabled'].

flags 是一個數(shù)組，它包含下面這些 Strings：

• enabled - button 為激活狀態(tài)并且開放給用戶.
• disabled -button 不可用. 目前它有一個可見的狀態(tài)來表示它不會響應你的行為.
• dismissonclick - 點擊button，這個縮略窗口直接關閉.
• nobackground - 不繪制邊框，僅僅使用圖像.
• hidden - button 對用戶不可見.
• noninteractive - button 可用但是不可響應; 也不顯示按下的狀態(tài). 它的值意味著這是一個在通知單使用 button 的實例.

win.showDefinitionForSelection() OS X

在界面查找選中文字時顯示彈出字典.

win.setAutoHideMenuBar(hide)

• hide Boolean

設置窗口的菜單欄是否可以自動隱藏. 一旦設置了，只有當用戶按下 Alt 鍵時則顯示.

如果菜單欄已經(jīng)可見，調(diào)用 setAutoHideMenuBar(true) 則不會立刻隱藏.

win.isMenuBarAutoHide()

返回 boolean,窗口的菜單欄是否可以自動隱藏.

win.setMenuBarVisibility(visible)

• visible Boolean

設置菜單欄是否可見.如果菜單欄自動隱藏，用戶仍然可以按下 Alt 鍵來顯示.

win.isMenuBarVisible()

返回 boolean,菜單欄是否可見.

win.setVisibleOnAllWorkspaces(visible)

• visible Boolean

設置窗口是否在所有地方都可見.

注意: 這個api 在windows無效.

win.isVisibleOnAllWorkspaces()

返回 boolean,窗口是否在所有地方都可見.

注意: 在 windows上始終返回 false.

win.setIgnoreMouseEvents(ignore) OS X

• ignore Boolean

忽略窗口的所有鼠標事件.