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
。 - 如果
BrowserWindow
是使用show: false
创建的,则尽管窗口实际上是隐藏的,初始可见性状态仍将是visible
。 - 如果
backgroundThrottling
被禁用,即使窗口被最小化、遮挡或隐藏,可见性状态仍将保持为visible
。
建议在可见性状态为 hidden
时暂停昂贵的运算,以最大限度地减少功耗。
平台通知
- 在 macOS 上,模态窗口将显示为附加到父窗口的表单(sheets)。
- 在 macOS 上,当父窗口移动时,子窗口将保持相对于父窗口的位置;而在 Windows 和 Linux 上,子窗口将不会移动。
- 在 Linux 上,模态窗口的类型将被更改为
dialog
。 - 在 Linux 上,许多桌面环境不支持隐藏模态窗口。
类:BrowserWindow 扩展自 BaseWindow
创建和控制浏览器窗口。
进程:主进程
BrowserWindow
是一个 EventEmitter。
使用 options
创建一个具有原生属性的新 BrowserWindow
。
Electron 的内置类不能被用户代码继承。更多信息,请参阅常见问题解答。
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')
// 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
返回
event
WindowSessionEndEvent
当由于关机、计算机重启或用户注销而即将结束会话时发出。调用 event.preventDefault()
可以延迟系统关机,尽管通常最好尊重用户结束会话的决定。但是,如果结束会话可能导致用户丢失数据,您可以选择使用它。
事件:'session-end' Windows
返回
event
WindowSessionEndEvent
当由于关机、计算机重启或用户注销而即将结束会话时发出。一旦此事件触发,就无法阻止会话结束。
事件:'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
调用 App 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-backward
browser-forward
事件:'swipe' macOS
返回
event
Eventdirection
string
在 3 指滑动时发出。可能的方向为 up
、right
、down
、left
。
此事件的底层方法旨在处理较旧的 macOS 风格触控板滑动,在这种滑动中,屏幕上的内容不会随滑动而移动。大多数 macOS 触控板不再配置为允许这种滑动,因此为了使其正常发出,必须在 系统偏好设置 > 触控板 > 更多手势
中将“在页面之间滑动”选项设置为“使用两指或三指滑动”。
事件:'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 Linux
返回
event
Eventpoint
Point - 触发上下文菜单的屏幕坐标。
当系统上下文菜单在窗口上触发时发出,这通常只在用户右键单击窗口的非客户端区域时发生。这是窗口标题栏或在无边框窗口中声明为 -webkit-app-region: drag
的任何区域。
调用 event.preventDefault()
将阻止显示菜单。
要将 point
转换为 DIP,请使用 screen.screenToDipPoint(point)
。
静态方法
BrowserWindow
类具有以下静态方法:
BrowserWindow.getAllWindows()
返回 BrowserWindow[]
- 所有已打开的浏览器窗口的数组。
BrowserWindow.getFocusedWindow()
返回 BrowserWindow | null
- 此应用程序中获得焦点的窗口,否则返回 null
。
BrowserWindow.fromWebContents(webContents)
webContents
WebContents
返回 BrowserWindow | null
- 拥有给定 webContents
的窗口,如果内容不属于任何窗口,则返回 null
。
BrowserWindow.fromBrowserView(browserView)
已弃用
browserView
BrowserView
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
返回 BrowserWindow | null
- 拥有给定 browserView
的窗口。如果给定的视图未附加到任何窗口,则返回 null
。
BrowserWindow.fromId(id)
id
Integer
返回 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
只读
一个 Integer
属性,表示窗口的唯一 ID。每个 ID 在整个 Electron 应用程序的所有 BrowserWindow
实例中都是唯一的。
win.tabbingIdentifier
macOS 只读
一个 string
(可选) 属性,等于传递给 BrowserWindow
构造函数的 tabbingIdentifier
,或者如果未设置则为 undefined
。
win.autoHideMenuBar
Linux Windows
一个 boolean
属性,用于确定窗口菜单栏是否应自动隐藏。设置后,菜单栏仅在用户按下单个 Alt
键时显示。
如果菜单栏已可见,将此属性设置为 true
不会立即隐藏它。
win.simpleFullScreen
一个 boolean
属性,用于确定窗口是否处于简单的(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
属性,用于确定窗口是否从应用程序的“窗口”菜单中排除。默认为 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
一个 string
属性,用于定义提供给辅助功能工具(如屏幕阅读器)的替代标题。此字符串对用户不可见。
win.snapped
Windows 只读
一个 boolean
属性,指示窗口是否通过 Snap 进行了排列。
实例方法
使用 new BrowserWindow
创建的对象具有以下实例方法:
某些方法仅在特定操作系统上可用,并已如此标记。
win.destroy()
强制关闭窗口,不会为网页发出 unload
和 beforeunload
事件,也不会为此窗口发出 close
事件,但它保证会发出 closed
事件。
win.close()
尝试关闭窗口。这与用户手动单击窗口关闭按钮的效果相同。网页可能会取消关闭。请参阅 close 事件。
win.focus()
聚焦到窗口。
win.blur()
从窗口中移除焦点。
win.isFocused()
返回 boolean
- 窗口是否获得焦点。
win.isDestroyed()
返回 boolean
- 窗口是否已被销毁。
win.show()
显示窗口并聚焦到它。
win.showInactive()
显示窗口但不对其聚焦。
win.hide()
隐藏窗口。
win.isVisible()
返回 boolean
- 窗口是否对用户在前台可见。
win.isModal()
返回 boolean
- 当前窗口是否为模态窗口。
win.maximize()
最大化窗口。如果窗口尚未显示,这将也会显示(但不聚焦)它。
win.unmaximize()
取消最大化窗口。
win.isMaximized()
返回 boolean
- 窗口是否已最大化。
win.minimize()
最小化窗口。在某些平台上,最小化的窗口将显示在 Dock 中。
win.restore()
从最小化状态恢复窗口到其先前状态。
win.isMinimized()
返回 boolean
- 窗口是否已最小化。
win.setFullScreen(flag)
flag
boolean
设置窗口是否应处于全屏模式。
在 macOS 上,全屏过渡是异步发生的。如果后续操作依赖于全屏状态,请使用 'enter-full-screen' 或 'leave-full-screen' 事件。
win.isFullScreen()
返回 boolean
- 窗口是否处于全屏模式。
在 macOS 上,全屏过渡是异步发生的。查询 BrowserWindow 的全屏状态时,应确保已发出 'enter-full-screen' 或 'leave-full-screen' 事件。
win.setSimpleFullScreen(flag)
macOS
flag
boolean
进入或退出简单全屏模式。
简单全屏模式模拟了 Lion (10.7) 之前的 macOS 版本中的原生全屏行为。
win.isSimpleFullScreen()
macOS
返回 boolean
- 窗口是否处于简单的(Lion 之前)全屏模式。
win.isNormal()
返回 boolean
- 窗口是否处于正常状态(未最大化、未最小化、未全屏)。
win.setAspectRatio(aspectRatio[, extraSize])
aspectRatio
Float - 要为内容视图的某个部分维持的纵横比。extraSize
Size (可选) macOS - 在维持纵横比时不应包含的额外大小。
这将使窗口保持纵横比。额外的大小允许开发者在不影响纵横比计算的情况下,在像素中指定空间。此 API 已考虑到窗口大小与其内容大小之间的差异。
考虑一个带有高清视频播放器和相关控件的普通窗口。也许左侧有 15 像素的控件,右侧有 25 像素的控件,下方有 50 像素的控件。为了在播放器本身内保持 16:9 的纵横比(高清 @1920x1080 的标准纵横比),我们将使用 16/9 和 { width: 40, height: 50 } 作为参数调用此函数。第二个参数不关心额外宽度和高度在内容视图内的位置,只关心它们的存在。将所有额外的宽度和高度区域加起来。
当使用 win.setSize
等 API 以编程方式调整窗口大小时,不遵循纵横比。
要重置纵横比,请将 0 作为 aspectRatio
值传递:win.setAspectRatio(0)
。
win.setBackgroundColor(backgroundColor)
backgroundColor
string - 十六进制、RGB、RGBA、HSL、HSLA 或命名的 CSS 颜色格式。十六进制类型的 alpha 通道是可选的。
backgroundColor
值示例:
- Hex
- #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
string - 要使用 QuickLook 预览的文件的绝对路径。这一点很重要,因为 Quick Look 使用路径中的文件名和文件扩展名来确定要打开的文件的内容类型。displayName
string (可选) - 在 Quick Look 模态视图中显示的文件的名称。这纯粹是视觉上的,不影响文件的内容类型。默认为path
。
使用 Quick Look 预览给定路径下的文件。
win.closeFilePreview()
macOS
关闭当前打开的 Quick Look 面板。
win.setBounds(bounds[, animate])
bounds
Partial<Rectangle>animate
boolean (可选) 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()
返回 string
- 以十六进制(#RRGGBB
)格式获取窗口的背景颜色。
请参阅 设置 backgroundColor
。
alpha 值不会与红色、绿色和蓝色值一起返回。
win.setContentBounds(bounds[, animate])
bounds
Rectangleanimate
boolean (可选) macOS
将窗口的客户端区域(例如网页)大小调整并移动到指定的边界。
win.getContentBounds()
返回 Rectangle - 窗口客户端区域的 bounds
,以 Object
的形式。
win.getNormalBounds()
返回 Rectangle - 包含窗口正常状态下的边界。
无论窗口当前处于何种状态(最大化、最小化或全屏),此函数始终返回窗口在正常状态下的位置和大小。在正常状态下,getBounds
和 getNormalBounds
返回相同的 Rectangle。
win.setEnabled(enable)
enable
boolean
禁用或启用窗口。
win.isEnabled()
返回 boolean
- 窗口是否已启用。
win.setSize(width, height[, animate])
width
Integerheight
Integeranimate
boolean (可选) macOS
将窗口大小调整为 width
和 height
。如果 width
或 height
低于任何设置的最小尺寸约束,窗口将自动调整到其最小尺寸。
win.getSize()
返回 Integer[]
- 包含窗口的宽度和高度。
win.setContentSize(width, height[, animate])
width
Integerheight
Integeranimate
boolean (可选) macOS
将窗口的客户端区域(例如网页)大小调整为 width
和 height
。
win.getContentSize()
返回 Integer[]
- 包含窗口客户端区域的宽度和高度。
win.setMinimumSize(width, height)
width
Integerheight
Integer
将窗口的最小尺寸设置为 width
和 height
。
win.getMinimumSize()
返回 Integer[]
- 包含窗口的最小宽度和高度。
win.setMaximumSize(width, height)
width
Integerheight
Integer
将窗口的最大尺寸设置为 width
和 height
。
win.getMaximumSize()
返回 Integer[]
- 包含窗口的最大宽度和高度。
win.setResizable(resizable)
resizable
boolean
设置用户是否可以手动调整窗口大小。
win.isResizable()
返回 boolean
- 用户是否可以手动调整窗口大小。
win.setMovable(movable)
macOS Windows
movable
boolean
设置用户是否可以移动窗口。在 Linux 上无操作。
win.isMovable()
macOS Windows
返回 boolean
- 用户是否可以移动窗口。
在 Linux 上始终返回 true
。
win.setMinimizable(minimizable)
macOS Windows
minimizable
boolean
设置用户是否可以手动最小化窗口。在 Linux 上无操作。
win.isMinimizable()
macOS Windows
返回 boolean
- 用户是否可以手动最小化窗口。
在 Linux 上始终返回 true
。
win.setMaximizable(maximizable)
macOS Windows
maximizable
boolean
设置用户是否可以手动最大化窗口。在 Linux 上无操作。
win.isMaximizable()
macOS Windows
返回 boolean
- 用户是否可以手动最大化窗口。
在 Linux 上始终返回 true
。
win.setFullScreenable(fullscreenable)
fullscreenable
boolean
设置最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
win.isFullScreenable()
返回 boolean
- 最大化/缩放窗口按钮是切换全屏模式还是最大化窗口。
win.setClosable(closable)
macOS Windows
closable
boolean
设置用户是否可以手动关闭窗口。在 Linux 上无操作。
win.isClosable()
macOS Windows
返回 boolean
- 用户是否可以手动关闭窗口。
在 Linux 上始终返回 true
。
win.setHiddenInMissionControl(hidden)
macOS
hidden
boolean
设置用户在切换到 Mission Control 时窗口是否被隐藏。
win.isHiddenInMissionControl()
macOS
返回 boolean
- 用户在切换到 Mission Control 时窗口是否被隐藏。
win.setAlwaysOnTop(flag[, level][, relativeLevel])
flag
booleanlevel
string (可选) macOS Windows - 值包括normal
,floating
,torn-off-menu
,modal-panel
,main-menu
,status
,pop-up-menu
,screen-saver
, 和(已弃用)。当dock
flag
为 true 时,默认为floating
。当 flag 为 false 时,level
会重置为normal
。请注意,从floating
到status
(含)的窗口显示在 macOS 上的 Dock 和 Windows 上的任务栏之下。从pop-up-menu
开始的窗口显示在 macOS 上的 Dock 和 Windows 上的任务栏之上。有关更多详细信息,请参阅 macOS 文档。relativeLevel
Integer (可选) macOS - 相对于给定level
设置此窗口的层数。默认为0
。请注意,Apple 不建议将层数设置到screen-saver
以上 1 层。
设置窗口是否应始终显示在其他窗口之上。设置此项后,窗口仍然是一个普通窗口,而不是一个不可聚焦的工具箱窗口。
win.isAlwaysOnTop()
返回 boolean
- 窗口是否始终位于其他窗口之上。
win.moveAbove(mediaSourceId)
mediaSourceId
string - 格式为 DesktopCapturerSource ID 的窗口 ID。例如 "window:1869:0"。
将窗口移到源窗口之上(按 z 轴顺序)。如果 mediaSourceId
不是窗口类型,或者窗口不存在,则此方法会抛出错误。
win.moveTop()
将窗口移动到顶部(z 轴顺序),无论是否获得焦点。
win.center()
将窗口移动到屏幕中心。
win.setPosition(x, y[, animate])
x
Integery
Integeranimate
boolean (可选) macOS
将窗口移动到 x
和 y
位置。
win.getPosition()
返回 Integer[]
- 包含窗口当前位置。
win.setTitle(title)
title
string
将原生窗口的标题更改为 title
。
win.getTitle()
返回 string
- 原生窗口的标题。
网页的标题可能与原生窗口的标题不同。
win.setSheetOffset(offsetY[, offsetX])
macOS
offsetY
FloatoffsetX
Float (可选)
更改 macOS 上表单(sheet)的附加点。默认情况下,表单附加在窗口框架的正下方,但您可能希望将其显示在 HTML 渲染的工具栏下方。例如:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)
win.flashFrame(flag)
flag
boolean
开始或停止闪烁窗口以吸引用户注意。
win.setSkipTaskbar(skip)
macOS Windows
skip
boolean
使窗口不显示在任务栏中。
win.setKiosk(flag)
flag
boolean
进入或退出 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
message
Integercallback
FunctionwParam
Buffer - 传递给 WndProc 的wParam
lParam
Buffer - 传递给 WndProc 的lParam
挂钩一个窗口消息。当在 WndProc 中接收到消息时,会调用 callback
。
win.isWindowMessageHooked(message)
Windows
message
Integer
返回 boolean
- 根据消息是否被挂钩返回 true
或 false
。
win.unhookWindowMessage(message)
Windows
message
Integer
取消挂钩窗口消息。
win.unhookAllWindowMessages()
Windows
取消挂钩所有窗口消息。
win.setRepresentedFilename(filename)
macOS
filename
string
设置窗口所代表的文件的路径名,文件的图标将显示在窗口的标题栏中。
win.getRepresentedFilename()
macOS
返回 string
- 窗口所代表的文件的路径名。
win.setDocumentEdited(edited)
macOS
edited
boolean
指定窗口的文档是否已编辑,设置为 true
时,标题栏中的图标将变为灰色。
win.isDocumentEdited()
macOS
返回 boolean
- 窗口的文档是否已编辑。
win.focusOnWebView()
win.blurWebView()
win.capturePage([rect, opts])
rect
Rectangle (optional) - 要捕获的边界opts
Object (optional)stayHidden
boolean (optional) - 保持页面隐藏而不是可见。默认为false
。stayAwake
boolean (optional) - 保持系统唤醒,而不是允许其休眠。默认为false
。
返回 Promise<NativeImage>
- 解析为 NativeImage
捕获 rect
内页面的快照。省略 rect
将捕获整个可见页面。如果页面不可见,rect
可以为空。当浏览器窗口隐藏且捕获器计数非零时,页面被认为是可见的。如果您希望页面保持隐藏,请确保将 stayHidden
设置为 true。
win.loadURL(url[, options])
url
string
返回 Promise<void>
- 当页面完成加载时(参见 did-finish-load
)Promise 将解析,如果页面加载失败(参见 did-fail-load
)Promise 将拒绝。
与 webContents.loadURL(url[, options])
相同。
url
可以是远程地址 (例如 http://
) 或使用 file://
协议指向本地 HTML 文件的路径。
为确保文件 URL 格式正确,建议使用 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('https://:8000/post', {
postData: [{
type: 'rawData',
bytes: Buffer.from('hello=world')
}],
extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})
win.loadFile(filePath[, options])
filePath
string
返回 Promise<void>
- 当页面完成加载时(参见 did-finish-load
)Promise 将解析,如果页面加载失败(参见 did-fail-load
)Promise 将拒绝。
与 webContents.loadFile
相同,filePath
应为相对于应用程序根目录的 HTML 文件路径。有关更多信息,请参阅 webContents
文档。
win.reload()
与 webContents.reload
相同。
win.setMenu(menu)
Linux Windows
menu
Menu | null
将 menu
设置为窗口的菜单栏。
win.removeMenu()
Linux Windows
移除窗口的菜单栏。
win.setProgressBar(progress[, options])
progress
Double
设置进度条的进度值。有效范围是 [0, 1.0]。
当 progress < 0 时移除进度条;当 progress > 1 时切换到不确定模式。
在 Linux 平台上,仅支持 Unity 桌面环境,您需要在 package.json
的 desktopName
字段中指定 *.desktop
文件名。默认情况下,它会假设为 {app.name}.desktop
。
在 Windows 上,可以传递一个模式。可接受的值为 none
、normal
、indeterminate
、error
和 paused
。如果您调用 setProgressBar
而未设置模式(但值在有效范围内),则会假定为 normal
。
win.setOverlayIcon(overlay, description)
Windows
overlay
NativeImage | null - 要显示在任务栏图标右下角的图标。如果此参数为null
,则会清除叠加层。description
string - 将提供给辅助功能屏幕阅读器的描述。
在当前任务栏图标上设置一个 16 x 16 像素的叠加层,通常用于传达某种应用程序状态或被动通知用户。
win.invalidateShadow()
macOS
使窗口阴影失效,以便根据当前窗口形状重新计算。
BrowserWindows
窗口(尤其是透明窗口)有时会在 macOS 上留下视觉瑕疵。此方法可用于清除这些瑕疵,例如在执行动画时。
win.setHasShadow(hasShadow)
hasShadow
boolean
设置窗口是否应具有阴影。
win.hasShadow()
返回 boolean
- 窗口是否有阴影。
win.setOpacity(opacity)
Windows macOS
opacity
number - 介于 0.0(完全透明)和 1.0(完全不透明)之间。
设置窗口的透明度。在 Linux 上无效。超出范围的数字值将被限制在 [0, 1] 范围内。
win.getOpacity()
返回 number
- 介于 0.0(完全透明)和 1.0(完全不透明)之间。在 Linux 上,始终返回 1。
win.setShape(rects)
Windows Linux Experimental
rects
Rectangle[] - 为窗口设置形状。传递空列表会将窗口恢复为矩形。
设置窗口形状决定了系统允许绘图和用户交互的窗口区域。在该区域之外,不会绘制任何像素,也不会注册任何鼠标事件。该区域之外的鼠标事件将不会被该窗口接收,而是会穿透到窗口后面的内容。
win.setThumbarButtons(buttons)
Windows
buttons
ThumbarButton[]
返回 boolean
- 按钮是否已成功添加。
在任务栏按钮布局中,为窗口的缩略图添加一个带有指定按钮的缩略图工具栏。返回一个 boolean
值,指示缩略图是否已成功添加。
由于空间有限,缩略图工具栏中的按钮数量应不超过 7 个。设置缩略图工具栏后,由于平台限制,该工具栏无法移除。但您可以传递一个空数组来调用该 API 以清除按钮。
buttons
是一个 Button
对象的数组。
Button
Objecticon
NativeImage - 显示在缩略图工具栏中的图标。click
Functiontooltip
string (optional) - 按钮工具提示的文本。flags
string[] (optional) - 控制按钮的特定状态和行为。默认值为['enabled']
。
flags
是一个可以包含以下 string
的数组
enabled
- 按钮处于活动状态,可供用户使用。disabled
- 按钮已禁用。它存在,但具有视觉状态,表明它不会响应用户操作。dismissonclick
- 单击按钮时,缩略图窗口将立即关闭。nobackground
- 不绘制按钮边框,仅使用图像。hidden
- 按钮不会显示给用户。noninteractive
- 按钮已启用但不可交互;不绘制按下按钮状态。此值用于按钮用作通知的情况。
win.setThumbnailClip(region)
Windows
region
Rectangle - 窗口区域。
设置窗口中要显示为任务栏缩略图的区域。您可以通过指定一个空区域来将缩略图重置为整个窗口:{ x: 0, y: 0, width: 0, height: 0 }
。
win.setThumbnailToolTip(toolTip)
Windows
toolTip
string
设置鼠标悬停在任务栏窗口缩略图上时显示的工具提示。
win.setAppDetails(options)
Windows
设置窗口任务栏按钮的属性。
relaunchCommand
和 relaunchDisplayName
必须同时设置。如果其中一个属性未设置,则两者都将不会被使用。
win.setAccentColor(accentColor)
Windows
accentColor
boolean | string - 窗口的强调色。默认情况下,遵循系统设置中的用户偏好。
设置系统强调色和活动窗口边框的突出显示。
accentColor
参数接受以下值:
- 颜色字符串 - 使用标准的 CSS 颜色格式(Hex、RGB、RGBA、HSL、HSLA 或命名颜色)设置自定义强调色。RGBA/HSLA 格式中的 Alpha 值将被忽略,颜色将被视为完全不透明。
true
- 使用系统设置中的系统默认强调色。false
- 明确禁用窗口的强调色突出显示。
示例
const win = new BrowserWindow({ frame: false })
// Set red accent color.
win.setAccentColor('#ff0000')
// RGB format (alpha ignored if present).
win.setAccentColor('rgba(255,0,0,0.5)')
// Use system accent color.
win.setAccentColor(true)
// Disable accent color.
win.setAccentColor(false)
win.getAccentColor()
Windows
返回 string | boolean
- 系统强调色和活动窗口边框的突出显示,以 Hex RGB 格式表示。
如果为窗口设置的颜色与系统强调色不同,则会返回窗口强调色。否则,将返回一个布尔值,其中 true
表示窗口使用全局系统强调色,false
表示此窗口的强调色突出显示被禁用。
win.showDefinitionForSelection()
macOS
与 webContents.showDefinitionForSelection()
相同。
win.setIcon(icon)
Windows Linux
icon
NativeImage | string
更改窗口图标。
win.setWindowButtonVisibility(visible)
macOS
visible
boolean
设置窗口交通灯按钮的可见性。
win.setAutoHideMenuBar(hide)
Windows Linux
hide
boolean
设置窗口菜单栏是否自动隐藏。一旦设置,菜单栏仅在用户按下单个 Alt
键时显示。
如果菜单栏已可见,调用 setAutoHideMenuBar(true)
不会立即隐藏它。
win.isMenuBarAutoHide()
Windows Linux
返回 boolean
- 菜单栏是否自动隐藏。
win.setMenuBarVisibility(visible)
Windows Linux
visible
boolean
设置菜单栏是否可见。如果菜单栏是自动隐藏的,用户仍然可以通过按下单个 Alt
键来显示菜单栏。
win.isMenuBarVisible()
Windows Linux
返回 boolean
- 菜单栏是否可见。
win.isSnapped()
Windows
返回 boolean
- 窗口是否通过 Snap 排列。
窗口通过鼠标悬停在窗口最大化按钮上显示的按钮,或通过将其拖到屏幕边缘来进行 Snap。
win.setVisibleOnAllWorkspaces(visible[, options])
macOS Linux
visible
boolean
设置窗口是否应在所有工作区可见。
此 API 在 Windows 上无效。
win.isVisibleOnAllWorkspaces()
macOS Linux
返回 boolean
- 窗口是否在所有工作区可见。
此 API 在 Windows 上始终返回 false。
win.setIgnoreMouseEvents(ignore[, options])
ignore
boolean
使窗口忽略所有鼠标事件。
此窗口中发生的所有鼠标事件都将传递给此窗口下方的窗口,但如果此窗口具有焦点,它仍会接收键盘事件。
win.setContentProtection(enable)
macOS Windows
enable
boolean
防止窗口内容被其他应用程序捕获。
在 macOS 上,它将 NSWindow 的 sharingType
设置为 NSWindowSharingNone
。在 Windows 上,它会调用 SetWindowDisplayAffinity
并使用 WDA_EXCLUDEFROMCAPTURE
。对于 Windows 10 版本 2004 及更高版本,窗口将完全从捕获中移除,旧版 Windows 的行为如同应用了 WDA_MONITOR
,捕获一个黑色窗口。
win.isContentProtected()
macOS Windows
返回 boolean
- 内容保护当前是否已启用。
win.setFocusable(focusable)
macOS Windows
focusable
boolean
更改窗口是否可以获得焦点。
在 macOS 上,它不会从窗口移除焦点。
win.isFocusable()
macOS Windows
返回 boolean
- 窗口是否可以获得焦点。
win.setParentWindow(parent)
parent
BrowserWindow | null
将 parent
设置为当前窗口的父窗口,传递 null
将使当前窗口成为顶级窗口。
win.getParentWindow()
返回 BrowserWindow | null
- 父窗口,如果没有父窗口则返回 null
。
win.getChildWindows()
返回 BrowserWindow[]
- 所有子窗口。
win.setAutoHideCursor(autoHide)
macOS
autoHide
boolean
控制在键入时是否隐藏光标。
win.selectPreviousTab()
macOS
当启用原生标签页且窗口中有其他标签页时,选择上一个标签页。
win.selectNextTab()
macOS
当启用原生标签页且窗口中有其他标签页时,选择下一个标签页。
win.showAllTabs()
macOS
当启用原生标签页时,显示或隐藏标签页概览。
win.mergeAllWindows()
macOS
当启用原生标签页且有多个打开的窗口时,将所有窗口合并到一个窗口中,包含多个标签页。
win.moveTabToNewWindow()
macOS
当启用原生标签页且当前窗口中有多个标签页时,将当前标签页移动到新窗口。
win.toggleTabBar()
macOS
当启用原生标签页且当前窗口中只有一个标签页时,切换标签栏的可见性。
win.addTabbedWindow(browserWindow)
macOS
browserWindow
BrowserWindow
将一个窗口作为标签页添加到此窗口中,位于该窗口实例的标签页之后。
win.setVibrancy(type[, options])
macOS
type
string | 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
stringauto
- 让桌面窗口管理器 (DWM) 自动决定此窗口的系统绘制的背景材质。这是默认值。none
- 不绘制任何系统背景。mica
- 绘制对应于长期存在的窗口的背景材质效果。acrylic
- 绘制对应于瞬态窗口的背景材质效果。tabbed
- 绘制对应于具有标签栏标题的窗口的背景材质效果。
此方法设置浏览器窗口的系统绘制背景材质,包括非客户端区域后面的内容。
有关更多详细信息,请参阅 Windows 文档。
此方法仅在 Windows 11 22H2 及更高版本中受支持。
win.setWindowButtonPosition(position)
macOS
position
Point | null
在无边框窗口中为交通灯按钮设置自定义位置。传递 null
会将位置重置为默认值。
win.getWindowButtonPosition()
macOS
返回 Point | null
- 无边框窗口中交通灯按钮的自定义位置,如果没有自定义位置则返回 null
。
win.setTouchBar(touchBar)
macOS
touchBar
TouchBar | null
设置当前窗口的 touchBar 布局。指定 null
或 undefined
会清除 touch bar。此方法仅在机器具有 touch bar 时才有效。
TouchBar API 目前仍处于实验阶段,在未来的 Electron 版本中可能会发生更改或被移除。
win.setBrowserView(browserView)
Experimental Deprecated
browserView
BrowserView | null - 将browserView
附加到win
。如果已附加其他BrowserView
,它们将从该窗口中移除。
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.getBrowserView()
Experimental Deprecated
返回 BrowserView | null
- 附加到 win
的 BrowserView
。如果未附加,则返回 null
。如果附加了多个 BrowserView
,则会引发错误。
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.addBrowserView(browserView)
Experimental Deprecated
browserView
BrowserView
用于 setBrowserView 的替换 API,支持处理多个 browser views。
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.removeBrowserView(browserView)
Experimental Deprecated
browserView
BrowserView
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.setTopBrowserView(browserView)
Experimental Deprecated
browserView
BrowserView
将 browserView
提升到 win
上附加的其他 BrowserView
之上。如果 browserView
未附加到 win
,则会引发错误。
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.getBrowserViews()
Experimental Deprecated
返回 BrowserView[]
- 一个按 z-index 排序的已通过 addBrowserView
或 setBrowserView
附加的所有 BrowserView 的数组。最顶层的 BrowserView 是数组的最后一个元素。
BrowserView
类已弃用,并被新的 WebContentsView
类取代。
win.setTitleBarOverlay(options)
Windows Linux
在已启用窗口控件叠加层的窗口上,此方法会更新标题栏叠加层的样式。
在 Linux 上,如果未显式设置 symbolColor
,它将自动计算以具有与 color
最小的可访问对比度。