BrowserWindow
创建并控制浏览器窗口。
进程:主进程
在 app
模块 emitted ready
事件之前,您不能使用此模块。
// 在主进程中.
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
- 如果创建
BrowserWindow
时带有show: false
的参数, 最初的可见性状态将为visible
尽管窗口实际上是隐藏的。 - 如果
backgroundThrottling
被禁用,可见性状态将保持为visible
即使窗口被最小 化、遮挡或隐藏。
推荐您在可见性状态为 hidden
时暂停消耗资源的操作以便减少电力消耗。
平台相关的提示
- 在 macOS 上,modal 窗口将显示为附加到父窗口的工作表。
- 在 macOS 上,子窗口将保持与父窗口的相对位置。而在 Windows 和 Linux 中,当父窗口移动时子窗口不会移动。
- 在Linux上,模态窗口的类型将更改为
dialog
. - 在Linux上,许多桌面环境不支持隐藏模态窗口。
Class: BrowserWindow extends BaseWindow
创建并控制浏览器窗口。
进程:主进程
BrowserWindow
是一个 EventEmitter。
通过 options
可以创建一个具有原生属性的 BrowserWindow
。
new BrowserWindow([options])
实例事件
使用 new BrowserWindow
创建的对象具有以下属性:
** 注意: **某些事件仅在特定的操作系统上可用, 这些方法会被标记出来。
事件: 'page-title-updated'
返回:
event
Eventtitle
stringexplicitSet
boolean
文档更改标题时触发,调用event.preventDefault()
将阻止更改标题 当标题合成自文件 URL 中时, explicitSet
的值为false。
事件: '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
}
注意:在 window.onbeforeunload = handler
和 window.addEventListener('beforeunload', handler)
之间有着细微的差别。 推荐总是显式地设置 event.returnValue
, 而不是仅仅返回一个值, 因为前者在Electron中作用得更为一致.
事件: 'closed'
在窗口关闭时触发 当你接收到这个事件的时候, 你应当移除相应窗口的引用对象,避免再次使用它.
事件: 'session-end' Windows
因为强制关机或机器重启或会话注销而导致窗口会话结束时触发
事件: 'unresponsive'
网页变得未响应时触发
事件: 'responsive'
未响应的页面变成响应时触发
事件: 'blur'
当窗口失去焦点时触发
事件: 'focus'
当窗口获得焦点时触发
事件: 'show'
当窗口显示时触发
事件: 'hide'
当窗口隐藏时触发
事件: 'ready-to-show'
当页面已经渲染完成(但是还没有显示) 并且窗口可以被显示时触发
请注意,使用此事件意味着渲染器会被认为是"可见的"并绘制,即使 show
是false。 如果您使用 paintWhenInitiallyHidden: false
,此事件将永远不会被触发。
事件: 'maximize'
窗口最大化时触发
事件: 'unmaximize'
当窗口从最大化状态退出时触发
事件: 'minimize'
窗口最小化时触发
事件: 'restore'
当窗口从最小化状态恢复时触发
事件: 'will-resize' macOS Windows
返回:
event
EventnewBounds
Rectangle - 将要调整到的窗口尺寸。details
Objectedge
(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
EventnewBounds
Rectangle - 窗口将要被移动到的位置。
窗口移动前触发。 在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
EventisAlwaysOnTop
boolean
设置或取消设置窗口总是在其他窗口的顶部显示时触发。
事件: 'app-command' Windows__Linux
返回:
event
Eventcommand
string
请求一个应用程序命令时触发. 典型的是键盘上的媒体键或浏览器命令, 以及在Windows上的一些鼠标中内置的“后退”按钮。
命令是小写的,下划线替换为连字符,以及APPCOMMAND_
前缀将被删除。 例如 APPCOMMAND_BROWSER_BACKWARD
将被browser-backward
触发.
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
// 当用户鼠标单击返回按钮时将自动返回上一个窗口
if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
win.webContents.goBack()
}
})
以下应用命令在 Linux 上有明确地支持:
browser-backward
browser-forward
事件: 'swipe' macOS
返回:
event
Eventdirection
string
三指滑动时触发。 可能的方向是 up
, right
, down
, left
。
此事件的基本方法是用来处理旧的macOS风格的触摸板滑动,屏幕内容不会随着滑动而移动。 大多数macOS触摸板都不再允许配置这样的滑动,因此为了正确地触发该事件,需将System Preferences > Trackpad > More Gestures
中'Swipe between pages'首选项设置为'Swipe with two or three fingers'。
事件: 'rotate-gesture' macOS
返回:
event
Eventrotation
Float
在触控板旋转手势上触发。 持续触发直到旋转手势结束。 每次触发的 rotation
值是自上次触发以来旋转的角度。 旋转手势最后一次触发的事件值永远是0
。 逆时针旋转值为正值,顺时针旋转值为负值。
事件: 'sheet-begin' macOS
窗口打开sheet(工作表) 时触发
事件: 'sheet-end' macOS
窗口关闭sheet(工作表) 时触发
事件: 'new-window-for-tab' macOS
当点击了系统的新标签按钮时触发
事件: 'system-context-menu' Windows
返回:
event
Eventpoint
Point - 上下文菜单触发时的屏幕坐标。
当系统上下文菜单在窗口上触发时发出, 通常只在用户右键点击你窗口的非客户端区域时触发。 非客户端区域指的是窗口标题栏或无边框窗口中被你声明为 -webkit-app-region: drag
的任意区域。
调用 event.preventDefault()
将阻止菜单显示。
静态方法
BrowserWindow
类有以下方法:
BrowserWindow.getAllWindows()
返回 BrowserWindow[]
- 所有打开的窗口的数组
BrowserWindow.getFocusedWindow()
返回 BrowserWindow | null
- 此应用程序中当前获得焦点的窗口,如果无就返回 null
.
BrowserWindow.fromWebContents(webContents)
webContents
WebContents
返回 BrowserWindow | null
- 返回拥有给定 webContents
的窗口,否则如果内容不属于一个窗口,返回null
。
BrowserWindow.fromBrowserView(browserView)
Deprecated
browserView
BrowserView
Note The
BrowserView
class is deprecated, and replaced by the newWebContentsView
class.
返回 BrowserWindow | null
- 拥有给定 browserView
的窗口。 如果给定的视图没有附加到任何窗口,返回 null
。
BrowserWindow.fromId(id)
id
Integer
返回 BrowserWindow | null
- 带有给定 id
的窗口。
实例属性
使用 new BrowserWindow
创建的对象具有以下属性:
const { BrowserWindow } = require('electron')
// 本例中 `win` 是我 们的实例
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')
win.webContents
只读
此窗口拥有的 WebContents
对象。 所有与网页相关的事件和操作都将通过它完成。
有关它的方法和事件, 请参见 webContents
documentation
win.id
只读
一个 Integer
属性代表了窗口的唯一ID。 每个ID在整个Electron应用程序的所有 BrowserWindow
实例中都是唯一的。
win.tabbingIdentifier
macOS 只读
A string
(optional) property that is equal to the tabbingIdentifier
passed to the BrowserWindow
constructor or undefined
if none was set.
win.autoHideMenuBar
一个 boolean
属性决定窗口菜单栏是否自动隐藏。 一旦设置,菜单栏将只在用户单击 Alt
键时显示。
如果菜单栏已经可见,将该属性设置为 true
将不会使其立刻隐藏。
win.simpleFullScreen
一个 boolean
属性,用于决定窗口是否处于简单(pre-Lion) 全屏模式。
win.fullScreen
一个 boolean
属性,用于决定窗口是否处于全屏模式。
win.focusable
Windows macOS
确定窗口是否可作为焦点被选中的 boolean
属性。
win.visibleOnAllWorkspaces
macOS Linux
一个 boolean
属性,用于决定窗口是否在所有工作区中可见。
注意: 在 Windows 上始终返回 false。
win.shadow
一个 boolean
属性,用于决定窗口是否显示阴影。
win.menuBarVisible
Windows Linux
一个 boolean
属性,用于决定菜单栏是否可见。
注意: 如果菜单栏自动隐藏,用户仍然可以通过单击 Alt
键来唤出菜单栏。
win.kiosk
一个 boolean
属性,用于决定窗口是否处于kiosk模式。
win.documentEdited
macOS
一个 boolean
属性指明窗口文档是否已被编辑。
当设置为 true
时,标题栏的图标将变灰。
win.representedFilename
macOS
一个 string
属性,用于确定窗口代表的文件的路径名,文件的图标将显示在窗口的标题栏中。
win.title
一个 string
属性,用于确定原生窗口的标题。
注意: 网页的标题可以与原生窗口的标题不同。
win.minimizable
macOS Windows
一个 boolean
属性,用于决定窗口是否可被用户手动最小化。
在 Linux 上,setter 不会进行任何操作,尽管 getter 返回的是 true
。
win.maximizable
macOS Windows
一个 boolean
属性,用于决定窗口是否可被用户手动最大化。
在 Linux 上,setter 不会进行任何操作,尽管 getter 返回的是 true
。
win.fullScreenable
一个 boolean
属性,决定最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
win.resizable
一个 boolean
属性,用于决定窗口是否可被用户手动调整大小。
win.closable
macOS Windows
一个 boolean
属性,用于决定窗口是否可被用户手动关闭。
在 Linux 上,setter 不会进行任何操作,尽管 getter 返回的是 true
。
win.movable
macOS Windows
一个 boolean
属性,用于决定窗口是否可被用户移动。
在 Linux 上,setter 不会进行任何操作,尽管 getter 返回的是 true
。
win.excludedFromShownWindowsMenu
macOS
一个 boolean
属性,用于决定窗口是否从应用程序的 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)