Electron参考手册

浏览器窗口 | BrowserWindow

BrowserWindow

创建并控制浏览器窗口。

过程：Main

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

// Or use `remote` from the renderer process.
// const {BrowserWindow} = require('electron').remote

let win = new BrowserWindow({width: 800, height: 600})
win.on('closed', () => {
  win = null
})

// Load a remote URL
win.loadURL('https://github.com')

// Or load a local HTML file
win.loadURL(`file://${__dirname}/app/index.html`)

无框窗口

要创建没有镶边的窗口或任意形状的透明窗口，可以使用无框窗口API。

优雅地显示窗口

当直接在窗口中加载页面时，用户可能会逐渐看到页面加载，这对于本机应用程序来说不是一个好的体验。为了使窗口显示没有视觉闪光，对于不同的情况有两种解决方案。

使用`ready-to-show`事件

加载页面时，ready-to-show如果窗口尚未显示，则渲染器进程首次渲染页面时会发出事件。在此事件之后显示窗口将没有可视闪光灯：

const {BrowserWindow} = require('electron')
let win = new BrowserWindow({show: false})
win.once('ready-to-show', () => {
  win.show()
})

此事件通常在did-finish-load事件发生后发出，但对于具有许多远程资源的页面，它可能在did-finish-load事件发生之前发出。

设置 `backgroundColor`

对于复杂的应用程序，该ready-to-show事件可能会发射得太晚，使应用程序感觉缓慢。在这种情况下，建议立即显示窗口，并使用backgroundColor接近您的应用程序的背景：

const {BrowserWindow} = require('electron')

let win = new BrowserWindow({backgroundColor: '#2e2c29'})
win.loadURL('https://github.com')

请注意，即使对于使用ready-to-show事件的应用程序，仍然建议设置backgroundColor为使应用程序感觉更加本地化。

父窗口和子窗口

通过使用parent选项，您可以创建子窗口：

const {BrowserWindow} = require('electron')

let top = new BrowserWindow()
let child = new BrowserWindow({parent: top})
child.show()
top.show()

该child窗口将始终显示在top窗口顶部。

模态窗口

模态窗口是禁用父窗口的子窗口，要创建模态窗口，必须设置两者parent和modal选项：

const {BrowserWindow} = require('electron')

let child = new BrowserWindow({parent: top, modal: true, show: false})
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

页面可见性

在网页浏览权限API的工作原理如下：

在所有平台上，可见性状态都会跟踪窗口是否隐藏/最小化。
另外，在macOS上，可见性状态还跟踪窗口遮挡状态。如果窗口被另一个窗口遮挡（即完全覆盖），则可见性状态将为hidden。在其他平台上，hidden仅当窗口最小化或显式隐藏时才会显示状态win.hide()。
如果使用a BrowserWindow创建a show: false，则visible尽管窗口实际上处于隐藏状态，但仍会显示初始可见性状态。
如果backgroundThrottling被禁用，visible即使窗口被最小化，遮挡或隐藏，可见性状态仍会保留。

建议您在可见性状态hidden为了最小化功耗时暂停昂贵的操作。

平台通知

在macOS模态窗口将显示为附加到父窗口的图纸。
在macOS上，当父窗口移动时，子窗口将保持与父窗口的相对位置，而在Windows和Linux子窗口上不会移动。
在Windows上不支持动态更改父窗口。
在Linux上，模式窗口的类型将更改为dialog。
在Linux上，许多桌面环境不支持隐藏模式窗口。

类：BrowserWindow

创建并控制浏览器窗口。

过程：Main

BrowserWindow是一个EventEmitter。

它创建一个新的BrowserWindow具有原生属性的设置options。

`new BrowserWindow([options])`

options 对象（可选）
- width整数（可选） - 窗口的宽度（以像素为单位）。默认是800。
- height整数（可选） - 窗口的高度（以像素为单位）。默认是600。
- x整数（可选）（如果使用y，则为必需） - 窗口的左偏移屏幕。默认是将窗口居中。
- y整数（可选）（如果使用x，则为必需） - 窗口与屏幕的偏移量。默认是将窗口居中。
- useContentSize布尔（可选） - width和height将用作网页的大小，这意味着实际窗口的大小将包括窗口框架的大小并略大。默认是false。
- center 布尔（可选） - 在屏幕中心显示窗口。
- minWidth整数（可选） - 窗口的最小宽度。默认是0。
- minHeight整数（可选） - 窗口的最小高度。默认是0。
- maxWidth整数（可选） - 窗口的最大宽度。默认是没有限制的。
- maxHeight整数（可选） - 窗口的最大高度。默认是没有限制的。
- resizable布尔（可选） - 窗口是否可调整大小。默认是true。
- movable布尔（可选） - 窗口是否可移动。这在Linux上没有实现。默认是true。
- minimizable布尔（可选） - 窗口是否可以最小化。这在Linux上没有实现。默认是true。
- maximizable布尔（可选） - 窗口是否可以最大化。这在Linux上没有实现。默认是true。
- closable布尔（可选） - 窗口是否可关闭。这在Linux上没有实现。默认是true。
- focusable布尔（可选） - 窗口是否可以聚焦。默认是true。在Windows上设置focusable: false也意味着设置skipTaskbar: true。在Linux设置下focusable: false，窗口停止与wm进行交互，所以窗口将始终保持在所有工作区的顶部。
- alwaysOnTop布尔（可选） - 窗口是否应始终保持在其他窗口之上。默认是false。
- fullscreen布尔（可选） - 窗口是否应以全屏显示。当明确设置为false全屏按钮时，将在macOS上隐藏或禁用。默认是false。
- fullscreenable布尔（可选） - 窗口是否可以进入全屏模式。在macOS上，最大化/缩放按钮是否应该切换全屏模式或最大化窗口。默认是true。
- skipTaskbar布尔（可选） - 是否在任务栏中显示窗口。默认是false。
- kiosk布尔（可选） - 自助服务终端模式。默认是false。
- title字符串（可选） - 默认窗口标题。默认是"Electron"。
- icon（NativeImage |字符串）（可选） - 窗口图标。在Windows上，建议使用ICO图标来获得最佳的视觉效果，您也可以将其保留为未定义的，以便使用可执行文件的图标。
- show布尔（可选） - 创建时是否显示窗口。默认是true。
- frame布尔（可选） - 指定false创建一个无框窗口。默认是true。
- parentBrowserWindow（可选） - 指定父窗口。默认是null。
- modal布尔（可选） - 是否是模态窗口。这只适用于窗口是子窗口的情况。默认是false。
- acceptFirstMouseBoolean（可选） - Web视图是否接受同时激活窗口的单个鼠标按下事件。默认是false。
- disableAutoHideCursor布尔（可选） - 是否在键入时隐藏光标。默认是false。
- autoHideMenuBar布尔（可选） - 除非Alt按下键，否则自动隐藏菜单栏。默认是false。
- enableLargerThanScreen布尔（可选） - 使窗口的调整大小大于屏幕。默认是false。
- backgroundColor字符串（可选） - 窗口的背景颜色为十六进制值，如#66CD00or #FFF或#80FFFFFF（支持alpha）。默认是#FFF（白色）。
- hasShadow布尔（可选） - 窗口是否应该有阴影。这只在macOS上实现。默认是true。
- darkTheme布尔（可选） - 强制使用黑暗主题作为窗口，仅适用于某些GTK + 3桌面环境。默认是false。
- transparent布尔（可选） - 使窗口透明。默认是false。
- type字符串（可选） - 窗口的类型，默认为正常窗口。请参阅下面的更多信息。
- titleBarStyle字符串（可选） - 窗口标题栏的样式。默认是default。可能的值是：
  - default - 导致标准灰色不透明的Mac标题栏。
  - hidden - 导致隐藏标题栏和全尺寸内容窗口，但标题栏仍然在左上角具有标准窗口控件（“交通信号灯”）。
  - hidden-inset- 弃用，hiddenInset改为使用。
  - hiddenInset - 在隐藏的标题栏中显示交通灯按钮稍微偏离窗口边缘的替代外观。
  - customButtonsOnHover布尔（可选） - 在macOS无框窗口上绘制自定义关闭，最小化和全屏按钮。这些按钮不会显示，除非在窗口的左上角悬停。这些自定义按钮可防止与标准窗口工具栏按钮发生的鼠标事件相关的问题。注意：此选项目前是实验性的。

-  `fullscreenWindowTitle` Boolean (optional) - Shows the title in the tile bar in full screen mode on macOS for all `titleBarStyle` options. Default is `false`.
-  `thickFrame` Boolean (optional) - Use `WS_THICKFRAME` style for frameless windows on Windows, which adds standard window frame. Setting it to `false` will remove window shadow and window animations. Default is `true`.
-  `vibrancy` String (optional) - Add a type of vibrancy effect to the window, only on macOS. Can be `appearance-based`, `light`, `dark`, `titlebar`, `selection`, `menu`, `popover`, `sidebar`, `medium-light` or `ultra-dark`.
-  `zoomToPageWidth` Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. If `true`, the window will grow to the preferred width of the web page when zoomed, `false` will cause it to zoom to the width of the screen. This will also affect the behavior when calling `maximize()` directly. Default is `false`.
-  `tabbingIdentifier` String (optional) - Tab group name, allows opening the window as a native tab on macOS 10.12+. Windows with the same tabbing identifier will be grouped together. This also adds a native new tab button to your window’s tab bar and allows your `app` and window to receive the `new-window-for-tab` event.
-  `webPreferences` Object (optional) - Settings of web page’s features. 
    -  `devTools` Boolean (optional) - Whether to enable DevTools. If it is set to `false`, can not use `BrowserWindow.webContents.openDevTools()` to open DevTools. Default is `true`.
    -  `nodeIntegration` Boolean (optional) - Whether node integration is enabled. Default is `true`.
    -  `nodeIntegrationInWorker` Boolean (optional) - Whether node integration is enabled in web workers. Default is `false`. More about this can be found in [Multithreading](../../tutorial/multithreading/index).
    -  `preload` String (optional) - Specifies a script that will be loaded before other scripts run in the page. This script will always have access to node APIs no matter whether node integration is turned on or off. The value should be the absolute file path to the script. When node integration is turned off, the preload script can reintroduce Node global symbols back to the global scope. See example [here](../process/index#event-loaded).
    -  `sandbox` Boolean (optional) - If set, this will sandbox the renderer associated with the window, making it compatible with the Chromium OS-level sandbox and disabling the Node.js engine. This is not the same as the `nodeIntegration` option and the APIs available to the preload script are more limited. Read more about the option [here](../sandbox-option/index). **Note:** This option is currently experimental and may change or be removed in future Electron releases.
    -  `session` [Session](../session/index#class-session) (optional) - Sets the session used by the page. Instead of passing the Session object directly, you can also choose to use the `partition` option instead, which accepts a partition string. When both `session` and `partition` are provided, `session` will be preferred. Default is the default session.
    -  `partition` String (optional) - Sets the session used by the page according to the session’s partition string. If `partition` starts with `persist:`, the page will use a persistent session available to all pages in the app with the same `partition`. If there is no `persist:` prefix, the page will use an in-memory session. By assigning the same `partition`, multiple pages can share the same session. Default is the default session.
    -  `zoomFactor` Number (optional) - The default zoom factor of the page, `3.0` represents `300%`. Default is `1.0`.
    -  `javascript` Boolean (optional) - Enables JavaScript support. Default is `true`.
    -  `webSecurity` Boolean (optional) - When `false`, it will disable the same-origin policy (usually using testing websites by people), and set `allowRunningInsecureContent` to `true` if this options has not been set by user. Default is `true`.
    -  `allowRunningInsecureContent` Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Default is `false`.
    -  `images` Boolean (optional) - Enables image support. Default is `true`.
    -  `textAreasAreResizable` Boolean (optional) - Make TextArea elements resizable. Default is `true`.
    -  `webgl` Boolean (optional) - Enables WebGL support. Default is `true`.
    -  `webaudio` Boolean (optional) - Enables WebAudio support. Default is `true`.
    -  `plugins` Boolean (optional) - Whether plugins should be enabled. Default is `false`.
    -  `experimentalFeatures` Boolean (optional) - Enables Chromium’s experimental features. Default is `false`.
    -  `experimentalCanvasFeatures` Boolean (optional) - Enables Chromium’s experimental canvas features. Default is `false`.
    -  `scrollBounce` Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Default is `false`.
    -  `blinkFeatures` String (optional) - A list of feature strings separated by `,`, like `CSSVariables,KeyboardEventKey` to enable. The full list of supported feature strings can be found in the [RuntimeEnabledFeatures.json5](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62) file.
    -  `disableBlinkFeatures` String (optional) - A list of feature strings separated by `,`, like `CSSVariables,KeyboardEventKey` to disable. The full list of supported feature strings can be found in the [RuntimeEnabledFeatures.json5](https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/RuntimeEnabledFeatures.json5?l=62) file.
    -  `defaultFontFamily` Object (optional) - Sets the default font for the font-family. 
        -  `standard` String (optional) - Defaults to `Times New Roman`.
        -  `serif` String (optional) - Defaults to `Times New Roman`.
        -  `sansSerif` String (optional) - Defaults to `Arial`.
        -  `monospace` String (optional) - Defaults to `Courier New`.
        -  `cursive` String (optional) - Defaults to `Script`.
        -  `fantasy` String (optional) - Defaults to `Impact`.

    -  `defaultFontSize` Integer (optional) - Defaults to `16`.
    -  `defaultMonospaceFontSize` Integer (optional) - Defaults to `13`.
    -  `minimumFontSize` Integer (optional) - Defaults to `0`.
    -  `defaultEncoding` String (optional) - Defaults to `ISO-8859-1`.
    -  `backgroundThrottling` Boolean (optional) - Whether to throttle animations and timers when the page becomes background. This also affects the [Page Visibility API][#page-visibility]. Defaults to `true`.
    -  `offscreen` Boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to `false`. See the [offscreen rendering tutorial](../../tutorial/offscreen-rendering/index) for more details.
    -  `contextIsolation` Boolean (optional) - Whether to run Electron APIs and the specified `preload` script in a separate JavaScript context. Defaults to `false`. The context that the `preload` script runs in will still have full access to the `document` and `window` globals but it will use its own set of JavaScript builtins (`Array`, `Object`, `JSON`, etc.) and will be isolated from any changes made to the global environment by the loaded page. The Electron API will only be available in the `preload` script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the `preload` script and any Electron APIs being used. This option uses the same technique used by [Chrome Content Scripts](https://developer.chrome.com/extensions/content_scripts#execution-environment). You can access this context in the dev tools by selecting the ‘Electron Isolated Context’ entry in the combo box at the top of the Console tab. **Note:** This option is currently experimental and may change or be removed in future Electron releases.
    -  `nativeWindowOpen` Boolean (optional) - Whether to use native `window.open()`. Defaults to `false`. **Note:** This option is currently experimental.
    -  `webviewTag` Boolean (optional) - Whether to enable the [`<webview>` tag](../webview-tag/index). Defaults to the value of the `nodeIntegration` option. **Note:** The `preload` script configured for the `<webview>` will have node integration enabled when it is executed so you should ensure remote/untrusted content is not able to create a `<webview>` tag with a possibly malicious `preload` script. You can use the `will-attach-webview` event on [webContents](../web-contents/index) to strip away the `preload` script and to validate or alter the `<webview>`’s initial settings.

使用minWidth/ maxWidth/ minHeight/ 设置最小或最大窗口大小时maxHeight，它仅限制用户。它不会阻止你传递的大小不符合尺寸约束setBounds/ setSize或的构造BrowserWindow。

该type选项的可能值和行为取决于平台。可能的值是：

在Linux上，可能的类型有desktop，dock，toolbar，splash，notification。
在macOS上，可能的类型是desktop，textured。
- 该textured类型添加了金属渐变外观（NSTexturedBackgroundWindowMask）。
- 该desktop类型将窗口置于桌面背景窗口级别（kCGDesktopWindowLevel - 1）。请注意，桌面窗口不会收到焦点，键盘或鼠标事件，但您可以使用它globalShortcut来节省输入。
在Windows上，可能的类型是toolbar。

实例事件

创建的对象new BrowserWindow会发出以下事件：

注意：某些事件仅在特定的操作系统上可用，并且被标记为这样。

事件：'page-title-updated'

event 事件
title 串

文档更改标题时发出，调用event.preventDefault()将阻止本地窗口的标题更改。

事件：'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
}

事件：'关闭'

窗户关闭时发射。收到此事件后，您应该删除对该窗口的引用并避免再使用它。

事件：'会话结束' Windows

窗口会话由于强制关机或机器重启或会话注销而结束时发出。

事件：'无响应'

当网页无响应时发出。

事件：'响应'

当无响应的网页再次变得响应时发出。

事件：'blur'

当窗口失去焦点时发射。

事件：'focus'

当窗口获得焦点时发射。

事件: ‘show’

显示窗口时发出。

事件: ‘hide’

隐藏窗口时发射。

事件: ‘ready-to-show’

当网页被渲染时（当没有被显示时）被发射，窗口可以在没有可视闪光的情况下被显示。

事件: ‘maximize’

窗口最大化时发射。

事件：'unmaximize'

窗口退出最大化状态时发出。

事件：'最小化'

当窗口最小化时发射。

事件: ‘restore’

窗口从最小化状态恢复时发出。

事件: ‘resize’

窗口大小调整时发射。

事件: ‘move’

窗口移动到新位置时发射。

注意：在macOS上，这个事件只是一个别名moved。

事件: ‘moved’ macOS

窗口移动到新位置时发射一次。

事件: ‘enter-full-screen’

窗口进入全屏状态时发射。

事件: ‘leave-full-screen’

窗口离开全屏状态时发射。

事件: ‘enter-html-full-screen’

窗口进入由HTML API触发的全屏状态时发出。

事件: ‘leave-html-full-screen’

当窗口离开由HTML API触发的全屏状态时发出。

事件: ‘app-command’ Windows

event 事件
command 串

当应用程序命令（https://msdn.microsoft.com/en-us/library/windows/desktop/ms646275（v = vs.85％29.aspx））被调用时发出。这些通常与键盘媒体键或浏览器命令，以及内置于Windows上某些鼠标的“返回”按钮。

命令是小写的，下划线用连字符代替，并且APPCOMMAND_前缀被剥离。例如APPCOMMAND_BROWSER_BACKWARD被排出browser-backward。

const {BrowserWindow} = require('electron')
let 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()
  }
})

事件: ‘scroll-touch-begin’ macOS

滚轮事件阶段开始时发出。

事件: ‘scroll-touch-end’ macOS

滚轮事件阶段结束时发出。

事件: ‘scroll-touch-edge’ macOS

当滚动轮事件相位到达元素的边缘时发出。

事件: ‘swipe’ macOS

event 事件
direction 串

用3指轻扫发射。可能的方向有up，right，down，left。

事件: ‘sheet-begin’ macOS

窗口打开表单时发出。

事件: ‘sheet-end’ macOS

窗口关闭表单时发出。

事件: ‘new-window-for-tab’ macOS

点击原生新标签按钮时发出。

静态方法

该BrowserWindow班有下列静态方法：

`BrowserWindow.getAllWindows()`

返回BrowserWindow[]- 所有打开的浏览器窗口的数组。

`BrowserWindow.getFocusedWindow()`

返回BrowserWindow- 在此应用程序中关注的窗口，否则返回null。

`BrowserWindow.fromWebContents(webContents)`

webContents WebContents

返回BrowserWindow- 拥有给定的窗口webContents。

`BrowserWindow.fromId(id)`

id 整数

返回BrowserWindow- 给定的窗口id。