BrowserWindow

BrowserWindow

创建和控制浏览器窗口。

// 在主进程中.
const { BrowserWindow } = require('electron')
// 或者从渲染进程中使用 `remote`.
// const { BrowserWindow } = require('electron').remote
let win = new BrowserWindow({ width: 800, height: 600 })
win.on('closed', () => {
  win = null
})
// 加载远程URL
win.loadURL('https://github.com')
// 或加载本地HTML文件
win.loadURL(`file://${__dirname}/app/index.html`)

无边框窗口

如果想创建一个无边框或者任意形状的视图，可以使用Frameless Window 的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. 在其他平台上，可见性状态只有在使用 win.hide()使窗口最小化或者隐藏时才为 hidden
如果创建BrowserWindow 时带有 show: false的参数, 最初的可见性状态将为visible 尽管窗口实际上是隐藏的。
如果backgroundThrottling被禁用，可见性状态将保持为visible 即使窗户被最小化、遮挡或隐藏。
推荐您在可见性状态为 hidden 时暂停消耗资源的操作以便减少电力消耗。

平台相关的提示

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

Class: BrowserWindow

创建和控制浏览器窗口。

进程：主进程

BrowserWindow 是一个EventEmitter.

通过 options 可以创建一个具有原生属性的 BrowserWindow 。

new BrowserWindow([options])

选项 Object (可选)
- width Integer (可选) - 窗口的宽度，单位为像素。默认为800.
- height Integer(可选) - 窗口的高度，单位为像素。默认为600.
- x Integer (可选) (如果 y 存在时必填) - 窗口相对于屏幕左侧的偏移位置. 默认居中.
- y Integer (可选) (如果 x 存在时必填) - 窗口相对于屏幕顶部的偏移位置. 默认居中.
- useContentSize Boolean (可选) - width 和 height 将设置为 web 页面的尺寸(译注: 不包含边框), 这意味着窗口的实际尺寸将包括窗口边框的大小，稍微会大一点。默认值为 false.
- center Boolean (可选) - 窗口在屏幕居中.
- minWidth Integer (可选) - 窗口的最小宽度, 默认值为 0.
- minHeight Integer (可选) - 窗口的最小高度. 默认值为 0.
- maxWidth Integer (可选) - 窗口的最大宽度, 默认无限制.
- maxHeight Integer (可选) - 窗口的最大高度, 默认无限制.
- resizable Boolean (可选) - 窗口是否可以改变尺寸. 默认值为true.
- movable Boolean (可选) - 窗口是否可以移动. 在 Linux 中无效. 默认值为 true.
- minimizable Boolean (可选) - 窗口是否可以最小化. 在 Linux 中无效. 默认值为 true.
- maximizable Boolean (可选) - 窗口是否可以最大化动. 在 Linux 中无效. 默认值为 true.
- closable Boolean (可选) - 窗口是否可以关闭. 在 Linux 中无效. 默认值为 true.
- focusable Boolean (可选) - 窗口是否可以聚焦. 默认值为 true。在 Windows 中设置 focusable: false 也意味着设置了skipTaskbar: true. 在 Linux 中设置 focusable: false 时窗口停止与 wm 交互, 并且窗口将始终置顶。
- alwaysOnTop Boolean (可选) -窗口是否永远在别的窗口的上面. 默认值为false.
- fullscreen Boolean (可选) - 窗口是否全屏. 当明确设置为 false 时，在 macOS 上全屏的按钮将被隐藏或禁用. 默认值为 false.
- fullscreenable Boolean (可选) - 窗口是否可以进入全屏状态. 在 macOS上, 最大化/缩放按钮是否可用默认值为 true。
- simpleFullscreen Boolean (可选) - 在 macOS 上使用 pre-Lion 全屏. 默认为false.
- skipTaskbar Boolean (可选) - 是否在任务栏中显示窗口. 默认值为false.
- kiosk Boolean (可选) - kiosk 模式. 默认值为 false.
- title String (可选) - 窗口的默认标题. 默认值为 "Electron".
- icon (NativeImage | String) (可选) - 窗口的图标. 在 Windows 上推荐使用 ICO 图标来获得最佳的视觉效果, 默认使用可执行文件的图标.
- show Boolean (可选) - 窗口创建的时候是否显示. 默认值为true.
- frame Boolean (可选) - 设置为 false 时可以创建一个Frameless Window. 默认值为 true.
- parent BrowserWindow (可选) - 指定父窗口. 默认值为 null.
- modal Boolean (可选) -是否为模态窗. 仅供子窗口使用. 默认值为false.
- acceptFirstMouse Boolean (可选) - 是否允许单击页面来激活窗口. 默认值为 false.
- disableAutoHideCursor Boolean (可选) - 是否在输入时隐藏鼠标. 默认值为false.
- autoHideMenuBar Boolean (可选) - 自动隐藏菜单栏, 除非按了Alt键. 默认值为false.
- enableLargerThanScreen Boolean (可选) - 是否允许改变窗口的大小时, 大于屏幕的尺寸. 默认值为false.
- backgroundColor String（可选）- 窗口的背景颜色为十六进制值，例如 #66CD00 或 #FFF 或 #80FFFFFF（如果支持 alpha， transparent 设置为 true）。默认值为 #FFF（白色）。
- hasShadow Boolean (可选) - 窗口是否有阴影. 仅在 macOS 上支持. 默认值为 true.
- opacity Number (可选)-设置窗口初始的不透明度, 介于 0.0 (完全透明) 和 1.0 (完全不透明) 之间。仅支持 Windows 和 macOS 。
- darkTheme Boolean (可选) - 强制窗口使用 dark 主题, 只在一些拥有 GTK+3 桌面环境上有效. 默认值为 false.
- transparent Boolean (可选) - 使窗口透明. 默认值为 false.
- type String (可选) - 窗口的类型, 默认为普通窗口. 下面可以查看更多.
- titleBarStyle String (可选) - 窗口标题栏的样式. 默认值为 default. 可能的值有：
  - default - 标准灰色不透明的Mac标题栏
  - hidden - 隐藏标题栏, 内容充满整个窗口, 但它依然在左上角, 仍然受标准窗口控制.
  - hiddenInset - 隐藏标题栏, 显示小的控制按钮在窗口边缘
  - customButtonsOnHover Boolean (可选) - 在macOS的无框窗口上绘制自定义的关闭与最小化按钮. 除非鼠标悬停到窗口的左上角, 否则这些按钮不会显示出来. 这些自定义的按钮能防止, 与发生于标准的窗口工具栏按钮处的鼠标事件相关的问题. 注意: 此选项目前是实验性的。
- fullscreenWindowTitle Boolean (可选) - 在 macOS 全屏模式时，为所有带 titleBarStyle 选项的标题栏显示标题。默认值为 false。
- thickFrame Boolean(可选)-对 Windows 上的无框窗口使用WS_THICKFRAME 样式，会增加标准窗口框架。设置为 false 时将移除窗口的阴影和动画. 默认值为 true。
- vibrancy String (可选) - 窗口是否使用 vibrancy 动态效果, 仅 macOS 中有效. 可以为 appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light 或 ultra-dark. 请注意，结合一个 vibrancy 值使用 frame: false ，需要确保titleBarStyle为一个非默认值。
- zoomToPageWidth Boolean (可选) - 单击工具栏上的绿色信号灯按钮或单击窗口>缩放菜单项时的行为, 仅macOS中有效. 如果为 true, 窗口将放大到网页的本身宽度, false 将使其缩放到屏幕的宽度。这也会影响直接调用 maximize() 时的行为。默认值为 false.
- tabbingIdentifier String (可选) - 选项组卡的名称，在macOS 10.12+上可使窗口在原生选项卡中打开. 具有相同标识符的窗口将被组合在一起。这还会在窗口的标签栏中添加一个原生的新选项卡按钮, 并允许 app 和窗口接收 new-window-for-tab 事件。
- webPreferences Object (可选) - 网页功能的设置
  - devTools Boolean (可选) - 是否开启 DevTools. 如果设置为 false, 则无法使用 BrowserWindow.webContents.openDevTools () 打开 DevTools。默认值为 true。
  - nodeIntegration Boolean (可选) - 是否完整的支持 node. 默认值为true.
  - nodeIntegrationInWorker Boolean (可选) - 是否在Web工作器中启用了Node集成. 默认值为 false. 更多内容参见多线程.
  - preload String (可选) -在页面运行其他脚本之前预先加载指定的脚本无论页面是否集成Node, 此脚本都可以访问所有Node API 脚本路径为文件的绝对路径。当 node integration 关闭时, 预加载的脚本将从全局范围重新引入node的全局引用标志参考示例.
  - sandbox Boolean (可选)-如果设置该参数, 沙箱的渲染器将与窗口关联, 使它与Chromium OS-level 的沙箱兼容, 并禁用 Node. js 引擎。它与 nodeIntegration 的选项不同，且预加载脚本的 API 也有限制. 更多详情. 注意:改选项目前是为实验性质，可能会在 Electron 未来的版本中移除。
  - enableRemoteModule Boolean（可选）- 是否启用 Remote 模块。默认值为 true。
  - session Session (可选) - 设置页面的 session 而不是直接忽略 Session 对象, 也可用 partition 选项来代替，它接受一个 partition 字符串. 同时设置了session 和 partition时, session 的优先级更高. 默认使用默认的 session.
  - partition String (optional) - 通过 session 的 partition 字符串来设置界面session. 如果 partition 以 persist:开头, 该页面将使用持续的 session，并在所有页面生效，且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 通过分配相同的 partition, 多个页可以共享同一会话。默认使用默认的 session.
  - affinity String (可选) - 当指定，具有相同affinity 的 web页面将在相同的渲染进程运行。需要注意的是，由于渲染过程中会有代码重用，如 webPreferences的preload, sandbox 和 nodeIntegration等选项会在不同页面之间共用，即使你已经在不同页面中为同一选项设置过不同的值，它们仍会被共用。因此，建议为affinity相同的页面，使用相同的 webPreferences 这一选项当前是实验性的
  - zoomFactor Number (可选) - 页面的默认缩放系数, 3.0 表示 300%. 默认值为 1.0.
  - javascript Boolean (可选) - 是否启用 JavaScript 支持. 默认值为 true.
  - webSecurity Boolean (可选) - 当设置为 false, 它将禁用同源策略 (通常用来测试网站), 如果此选项不是由开发者设置的，还会把 allowRunningInsecureContent设置为 true. 默认值为 true。
  - allowRunningInsecureContent Boolean (可选) -允许一个 https 页面运行 http url 里的资源，包括 JavaScript, CSS 或 plugins. 默认值为 false.
  - images Boolean (可选) - 启动图像支持. 默认值为 true.
  - textAreasAreResizable Boolean (可选) - 让 TextArea 元素可以调整大小. 默认值为 true.
  - webgl Boolean (可选) - 启用 WebGL 支持. 默认值为 true.
  - webaudio Boolean (可选) - 启用 WebAudio 支持. 默认值为 true.
  - plugins Boolean (可选) - 是否支持插件. 默认值为 false.
  - experimentalFeatures Boolean (optional) - 启用 Chromium 的实验功能. 默认值为 false.
  - scrollBounce Boolean (可选) - 在 macOS 启用弹力动画 (橡皮筋) 效果. 默认值为 false.
  - enableBlinkFeaturesString(可选) - 以逗号分隔的需要启用的特性列表，譬如CSSVariables,KeyboardEventKey 在 RuntimeEnabledFeatures.json5文件中查看被支持的所有特性.
  - disableBlinkFeatures String (可选) - 以 ,分隔的禁用特性列表, 如 CSSVariables,KeyboardEventKey. 在RuntimeEnabledFeatures.json5 文件中查看被支持的所有特性.
  - defaultFontFamily Object (可选) - 设置 font-family 的默认字体.
    - standard String (可选) - 默认值为 Times New Roman.
    - serif String (可选) - 默认值为 Times New Roman.
    - sansSerif String (可选) - 默认值为 Arial.
    - monospace String (可选) - 默认值为 Courier New.
    - cursive String (可选) - 默认值为 Script.
    - fantasy String (可选) - 默认值为 Impact.
  - defaultFontSize Integer (可选) - 默认值为 16.
  - defaultMonospaceFontSize Integer (可选) - 默认值为 13.
  - minimumFontSize Integer (可选) - 默认值为 0.
  - defaultEncoding String (可选) - 默认值为 ISO-8859-1.
  - backgroundThrottlingBoolean (可选)-是否在页面成为背景时限制动画和计时器。这也会影响到 Page Visibility API. 默认值为 true。
  - offscreen Boolean (optional) - 是否绘制和渲染可视区域外的窗口. 默认值为 false. 更多详情, 请参见 offscreen rendering tutorial 。
  - contextIsolation Boolean (可选) - 是否在独立 JavaScript 环境中运行 Electron API和指定的preload 脚本. 默认值为 false. preload脚本的运行环境仍然可以访问document 和 window全局变量，但它将使用自己内置的函数 (如Array, Object, JSON等)，并且将被加载的页面与对全局环境所做的任何更改隔离开来. Electron API 仅在 preload 脚本中有效，而不是加载的页面。在加载可能不受信任的远程内容时, 应使用此选项, 以确保加载的内容不能篡改 preload 脚本和使用的 Electron APIs。此选项使用 Chrome Content Scripts 使用的相同技术。通过在控制台选项卡顶部的组合框中选择 "Electron Isolated Context" 条目, 可以在开发工具中访问此上下文。
  - nativeWindowOpen Boolean (可选) - 是否使用原生的window.open(). 如果设置为 true, 那么子窗口的 webPreferences将永远与父窗口的相同, 不论什么参数被传至window.open(). 默认值为 false. 注意: 这一选项当前是实验性的.
  - webviewTag Boolean (可选) - 是否启用 <webview> tag标签. 默认为 nodeIntegration 选项的值。 注意: 为 < webview> 配置的 preload 脚本在执行时将启用节点集成, 因此应确保远程或不受信任的内容无法创建恶意的 preload 脚本。可以使用 webContents 上的 will-attach-webview 事件对 preload 脚本进行剥离, 并验证或更改 <webview> 的初始设置。
  - additionalArguments String[] (可选) - 一系列将会被附加至此app的渲染进程的process.argv的字符串. 对于将少量数据向下传至渲染进程的预加载脚本而言是十分实用的.
  - safeDialogs Boolean (可选) - 是否启用浏览器样式的持续对话框保护。缺省为false。
  - safeDialogsMessage String (可选) - 当持续对话框保护被触发时显示的消息。如果没有定义，那么将使用缺省的消息。注意：当前缺省消息是英文，并没有本地化。
  - navigateOnDragDrop Boolean (可选) - 将文件或链接拖放到页面上时是否触发页面跳转. 默认为false.
    当使用 minWidth/maxWidth/minHeight/maxHeight 设置最小或最大窗口大小时, 它只限制用户。它不会阻止您将不符合大小限制的值传递给 setBounds/setSize 或 BrowserWindow 的构造函数。

type 选项的可能值和行为与平台相关。可能的值为:

在 Linux 上, 可能的类型有 desktop、dock、toolbar、splash、notification。
在 macOS, 可能的类型是 desktop, textured.
- textured 类型增加金属色泽的外观 (NSTexturedBackgroundWindowMask).
- desktop 类型将窗口置于桌面背景级别 (kCGDesktopWindowLevel - 1). 注意，桌面窗口不会接收焦点、键盘或鼠标事件，但您可以使用< 0> globalShortcut < /0 >接收快捷键的消息
在 Windows 上, 可能的类型为 toolbar.

实例事件

使用 new BrowserWindow 创建的对象具有以下属性:

注意: 某些事件仅在特定的操作系统上可用, 这些方法会被标记出来。

事件： 'page-title-updated'

event Event
title String
文档更改标题时触发，调用event.preventDefault()将阻止更改标题

事件： 'close'

event Event
在窗口要关闭的时候触发。它在DOM 的beforeunload 和 unload 事件之前触发. 调用event.preventDefault()将阻止这个操作。

通常你想通过 beforeunload处理器来决定是否关闭窗口，但是它也会在窗口重载的时候触发. 在 Electron 里，返回除 undefined之外的任何值都将取消关闭. 例如：

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed')
  // 与通常的浏览器不同,会提示给用户一个消息框,
  //返回非空值将默认取消关闭
  //建议使用对话框 API 让用户确认关闭应用程序.
  e.returnValue = false // 相当于 `return false` ，但是不推荐使用
}

*注意: window.onbeforeunload = handler 和 window.addEventListener('beforeunload', handler) 的行为有细微的区别。推荐总是显式地设置 event.returnValue, 而不是仅仅返回一个值, 因为前者在Electron中作用得更为一致.*

事件： 'closed'

窗口已经关闭时触发。当你接收到这个事件的时候, 你应当删除对已经关闭的窗口的引用对象和避免再次使用它.

事件: 'session-end' Windows

因为强制关机或机器重启或会话注销而导致窗口会话结束时触发

事件: 'unresponsive'

网页变得未响应时触发

事件: 'responsive'

未响应的页面变成响应时触发

事件: 'blur'

当窗口失去焦点时触发

事件: 'focus'

当窗口获得焦点时触发

事件: 'show'

当窗口显示时触发

事件: 'hide'

当窗口隐藏时触发

事件: 'ready-to-show'

当页面已经渲染完成(但是还没有显示) 并且窗口可以被显示时触发

事件: 'maximize'

窗口最大化时触发

事件: 'unmaximize'

当窗口从最大化状态退出时触发

事件: 'minimize'

窗口最小化时触发

事件: 'restore'

当窗口从最小化状态恢复时触发

事件: 'will-resize' macOS Windows

event Event
newBounds Rectangle - 将要调整到的窗口尺寸。
在调整窗口大小之前发出。调用event.preventDefault()会阻止窗口大小被调整。

请注意，仅在手动调整窗口大小时才会发出此信息。使用setBounds 或 setSize调整窗口大小时不会发出此事件。

事件: 'resize'

调整窗口大小后触发。

事件: 'will-move' Windows

event Event
newBounds Rectangle - 将要移动的新的窗口位置。
在移动窗口之前发出。调用event.preventDefault()会阻止窗口被移动。

请注意，仅在手动调整窗口大小时才会发出此信息。使用setBounds 或 setSize调整窗口大小时不会发出此事件。

事件: 'move'

窗口移动到新位置时触发

注意: 在 macOS 上，此事件是moved的别名.

事件: 'moved' macOS

当窗口移动到新位置时触发一次

事件: 'enter-full-screen'

窗口进入全屏状态时触发

事件: 'leave-full-screen'

窗口离开全屏状态时触发

事件: 'enter-html-full-screen'

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

事件: 'leave-html-full-screen'

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

事件: 'always-on-top-changed' macOS

event Event
isAlwaysOnTop Boolean
设置或取消设置窗口总是在其他窗口的顶部显示时触发。

事件: 'app-command' Windows

event Event
command String
请求一个应用程序命令.aspx)时触发. 典型的是键盘上的媒体键或浏览器命令, 以及在Windows上的一些鼠标中内置的“后退”按钮。

命令是小写的，下划线替换为连字符，以及APPCOMMAND_ 前缀将被删除。例如 APPCOMMAND_BROWSER_BACKWARD将被browser-backward触发.

const { BrowserWindow } = require('electron')
let win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
  // 当用户点击鼠标返回按钮时，导航窗口会后退
  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 Event
direction String
三指拖移时触发，可选的方向为 up, right, down, left.

事件: 'sheet-begin' macOS

窗口打开sheet(工作表) 时触发

事件: 'sheet-end' macOS

窗口关闭sheet(工作表) 时触发

事件: 'new-window-for-tab' macOS

当点击了系统的新标签按钮时触发

静态方法

BrowserWindow 类有以下方法:

BrowserWindow.getAllWindows()

返回 BrowserWindow[] - 所有打开的窗口的数组

BrowserWindow.getFocusedWindow()

返回 BrowserWindow | null - 此应用程序中当前获得焦点的窗口，如果无就返回 null.

BrowserWindow.fromWebContents(webContents)

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

BrowserWindow.fromBrowserView(browserView)

browserView BrowserView
返回 BrowserWindow | null-拥有给定 browserView 的窗口。如果给定视图未附加到任何窗口, 则返回 null。

BrowserWindow.fromId(id)

id Integer
返回 BrowserWindow -拥有给定 id 的窗口.