BaseWindow
创建和控制窗口。
进程:主进程
BaseWindow
提供了一种灵活的方式来在单个窗口中组合多个 Web 视图。对于只有一个全尺寸 Web 视图的窗口,BrowserWindow
类可能是一个更简单的选择。
此模块在 app
模块的 ready
事件发出之前无法使用。
// In the main process.
const { BaseWindow, WebContentsView } = require('electron')
const win = new BaseWindow({ width: 800, height: 600 })
const leftView = new WebContentsView()
leftView.webContents.loadURL('https://electron.js.cn')
win.contentView.addChildView(leftView)
const rightView = new WebContentsView()
rightView.webContents.loadURL('https://github.com/electron/electron')
win.contentView.addChildView(rightView)
leftView.setBounds({ x: 0, y: 0, width: 400, height: 600 })
rightView.setBounds({ x: 400, y: 0, width: 400, height: 600 })
父窗口和子窗口
通过使用 parent
选项,您可以创建子窗口
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent })
子
窗口将始终显示在父
窗口的顶部。
模态窗口
模态窗口是禁用父窗口的子窗口。要创建模态窗口,您必须同时设置 parent
和 modal
选项
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent, modal: true })
平台注意事项
- 在 macOS 上,模态窗口将作为附加到父窗口的工作表显示。
- 在 macOS 上,当父窗口移动时,子窗口将保持相对于父窗口的位置,而在 Windows 和 Linux 上,子窗口不会移动。
- 在 Linux 上,模态窗口的类型将更改为
dialog
。 - 在 Linux 上,许多桌面环境不支持隐藏模态窗口。
资源管理
当您将 WebContentsView
添加到 BaseWindow
且 BaseWindow
关闭时,WebContentsView
的 webContents
不会自动销毁。
当您不再需要 webContents
时,例如当 BaseWindow
关闭时,关闭它们是您的责任
const { BaseWindow, WebContentsView } = require('electron')
const win = new BaseWindow({ width: 800, height: 600 })
const view = new WebContentsView()
win.contentView.addChildView(view)
win.on('closed', () => {
view.webContents.close()
})
与 BrowserWindow
不同,如果您不显式关闭 webContents
,将会发生内存泄漏。
类:BaseWindow
创建和控制窗口。
进程:主进程
BaseWindow
是一个 EventEmitter。
它会创建一个新的 BaseWindow
,其原生属性由 options
设置。
Electron 的内置类不能在用户代码中进行子类化。有关更多信息,请参阅常见问题。
new BaseWindow([options])
实例事件
使用 new BaseWindow
创建的对象会发出以下事件
某些事件仅在特定操作系统上可用,并已相应标记。
事件:'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
当会话因关机、机器重启或用户注销而即将结束时发出。一旦此事件触发,就无法阻止会话结束。
事件:'blur'
返回值
event
Event
当窗口失去焦点时发出。
事件:'focus'
返回值
event
Event
当窗口获得焦点时发出。
事件:'show'
当窗口显示时发出。
事件:'hide'
当窗口隐藏时发出。
事件:'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'
当窗口离开全屏状态时发出。
事件:'always-on-top-changed'
返回值
event
EventisAlwaysOnTop
boolean
当窗口设置为或取消设置为始终显示在其他窗口之上时发出。
事件:'app-command' Windows Linux
返回值
event
Eventcommand
string
当应用命令被调用时发出。这些通常与键盘媒体键或浏览器命令以及 Windows 上某些鼠标内置的“后退”按钮有关。
命令是小写字母,下划线替换为连字符,并去除 APPCOMMAND_
前缀。例如,APPCOMMAND_BROWSER_BACKWARD
将作为 browser-backward
发出。
const { BaseWindow } = require('electron')
const win = new BaseWindow()
win.on('app-command', (e, cmd) => {
// Navigate the window back when the user hits their mouse back button
if (cmd === 'browser-backward') {
// Find the appropriate WebContents to navigate.
}
})
Linux 上明确支持以下应用命令
browser-backward
browser-forward
事件:'swipe' macOS
返回值
event
Eventdirection
string
在三指轻扫时发出。可能的方向有 up
、right
、down
、left
。
此事件的基础方法旨在处理旧版 macOS 风格的触控板滑动,其中屏幕上的内容不会随滑动而移动。大多数 macOS 触控板现在已不再配置为允许此类滑动,因此为了使其正常发出,必须将“系统偏好设置”>“触控板”>“更多手势”中的“在页面之间轻扫”偏好设置为“用两指或三指轻扫”。
事件:'rotate-gesture' macOS
返回值
event
Eventrotation
Float
在触控板旋转手势时发出。持续发出,直到旋转手势结束。每次发出时的 rotation
值是自上次发出以来的旋转角度(以度为单位)。旋转手势的最后一次发出事件的值始终为 0
。逆时针旋转值为正,顺时针旋转值为负。
事件:'sheet-begin' macOS
当窗口打开工作表时发出。
事件:'sheet-end' macOS
当窗口关闭工作表时发出。
事件:'new-window-for-tab' macOS
当点击原生新标签页按钮时发出。
事件:'system-context-menu' Windows Linux
返回值
event
Eventpoint
Point - 触发上下文菜单的屏幕坐标。
当在窗口上触发系统上下文菜单时发出,这通常仅在用户右键点击窗口的非客户端区域时触发。这包括窗口标题栏或您在无边框窗口中声明为 -webkit-app-region: drag
的任何区域。
调用 event.preventDefault()
将阻止菜单显示。
要将 point
转换为 DIP,请使用 screen.screenToDipPoint(point)
。
静态方法
BaseWindow
类具有以下静态方法
BaseWindow.getAllWindows()
返回值 BaseWindow[]
- 所有已打开的浏览器窗口的数组。
BaseWindow.getFocusedWindow()
返回值 BaseWindow | null
- 此应用程序中获得焦点的窗口,否则返回 null
。
BaseWindow.fromId(id)
id
Integer
返回值 BaseWindow | null
- 具有给定 id
的窗口。
实例属性
使用 new BaseWindow
创建的对象具有以下实例属性
const { BaseWindow } = require('electron')
// In this example `win` is our instance
const win = new BaseWindow({ width: 800, height: 600 })
win.id
只读
一个 Integer
属性,表示窗口的唯一 ID。每个 ID 在整个 Electron 应用程序的所有 BaseWindow
实例中都是唯一的。
win.contentView
窗口内容视图的 View
属性。
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
属性,决定窗口是否处于信息亭模式。
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 { Menu, BaseWindow } = require('electron')
const win = new BaseWindow({ 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
属性,指示窗口是否通过贴靠进行排列。
实例方法
使用 new BaseWindow
创建的对象具有以下实例方法
某些方法仅在特定操作系统上可用,并已相应标记。
win.setContentView(view)
view
View
设置窗口的内容视图。
win.getContentView()
返回值 View
- 窗口的内容视图。
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
- 窗口是否处于全屏模式。
win.setSimpleFullScreen(flag)
macOS
flag
boolean
进入或退出简单全屏模式。
简单全屏模式模拟了 macOS Lion (10.7) 之前版本中发现的原生全屏行为。
win.isSimpleFullScreen()
macOS
返回值 boolean
- 窗口是否处于简单 (Lion 之前) 全屏模式。
win.isNormal()
返回值 boolean
- 窗口是否处于正常状态(未最大化、未最小化、未处于全屏模式)。
win.setAspectRatio(aspectRatio[, extraSize])
aspectRatio
Float - 内容视图部分要保持的宽高比。extraSize
Size (可选) macOS - 在保持宽高比时,不包含在内的额外尺寸。
这将使窗口保持一个宽高比。额外尺寸允许开发者拥有以像素为单位的空间,不包括在宽高比计算中。此 API 已考虑窗口大小及其内容大小之间的差异。
考虑一个带有高清视频播放器和相关控件的普通窗口。可能左边缘有 15 像素的控件,右边缘有 25 像素的控件,播放器下方有 50 像素的控件。为了在播放器本身内保持 16:9 的宽高比(HD @1920x1080 的标准宽高比),我们将使用 16/9 和 { width: 40, height: 50 }
作为参数调用此函数。第二个参数不关心额外宽度和高度在内容视图中的位置——只关心它们的存在。将您在整个内容视图中的任何额外宽度和高度区域相加。
当使用 win.setSize
等 API 以编程方式调整窗口大小时,不遵守宽高比。
要重置宽高比,请将 0
作为 aspectRatio
值传入:win.setAspectRatio(0)
。
win.setBackgroundColor(backgroundColor)
backgroundColor
string - 颜色格式为 Hex、RGB、RGBA、HSL、HSLA 或命名 CSS 颜色格式。对于 Hex 类型,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 颜色模块级别 3 关键字,但区分大小写。
- 例如
blueviolet
或red
- 例如
设置窗口的背景颜色。请参阅设置 backgroundColor
。
win.previewFile(path[, displayName])
macOS
path
string - 要使用 QuickLook 预览的文件的绝对路径。这很重要,因为 Quick Look 使用路径上的文件名和文件扩展名来确定要打开的文件内容类型。displayName
string (可选) - 要在 Quick Look 模态视图上显示的文件名。这纯粹是视觉效果,不影响文件内容类型。默认为path
。
使用快速查看预览给定路径的文件。
win.closeFilePreview()
macOS
关闭当前打开的快速查看面板。
win.setBounds(bounds[, animate])
bounds
Partial<Rectangle>animate
boolean (可选) macOS
将窗口调整大小并移动到提供的边界。任何未提供的属性将默认为其当前值。
const { BaseWindow } = require('electron')
const win = new BaseWindow()
// 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 坐标值不能小于任务栏高度。任务栏高度随时间变化并取决于操作系统,但介于 20-40 像素之间。传递小于任务栏高度的值将导致窗口与任务栏齐平。
win.getBounds()
返回值 Rectangle - 窗口的 bounds
作为 Object
。
在 macOS 上,返回的 y 坐标值最小为任务栏高度。例如,在任务栏高度为 38 的情况下调用 win.setBounds({ x: 25, y: 20, width: 800, height: 600 })
意味着 win.getBounds()
将返回 { x: 25, y: 38, width: 800, height: 600 }
。
win.getBackgroundColor()
返回值 string
- 获取窗口的背景颜色,格式为 Hex (#RRGGBB
)。
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 - 窗口 ID,格式为 DesktopCapturerSource 的 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 { BaseWindow } = require('electron')
const win = new BaseWindow()
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 用户可以 将他们的电脑用作平板,在这种模式下,应用程序可以选择为平板优化其 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
挂钩一个 Windows 消息。当 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.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
中将 *.desktop
文件名指定到 desktopName
字段。默认情况下,它将假定为 {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
使窗口阴影失效,以便根据当前窗口形状重新计算。
透明的 BaseWindow
在 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
对象icon
NativeImage - 显示在缩略图工具栏中的图标。click
Functiontooltip
string (可选) - 按钮工具提示的文本。flags
string[] (可选) - 控制按钮的特定状态和行为。默认情况下,为['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.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
- 窗口是否通过 贴靠 方式排列。
窗口通过鼠标悬停在窗口最大化按钮上时显示的按钮,或通过将其拖动到屏幕边缘来贴靠。
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 上,它使用 WDA_EXCLUDEFROMCAPTURE
调用 SetWindowDisplayAffinity。对于 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
BaseWindow | null
将 parent
设置为当前窗口的父窗口,传入 null
将把当前窗口转换为顶级窗口。
win.getParentWindow()
返回 BaseWindow | null
- 父窗口,如果没有父窗口则返回 null
。
win.getChildWindows()
返回 BaseWindow[]
- 所有子窗口。
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(baseWindow)
macOS
baseWindow
BaseWindow
将一个窗口作为标签页添加到此窗口,位于该窗口实例的标签页之后。
win.setVibrancy(type)
macOS
type
string | null - 可为titlebar
,selection
,menu
,popover
,sidebar
,header
,sheet
,window
,hud
,fullscreen-ui
,tooltip
,content
,under-window
, 或under-page
。更多详细信息请参阅 macOS 文档。
为窗口添加振动效果。传入 null
或空字符串将移除窗口上的振动效果。
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
将清除 TouchBar。此方法仅在机器具有 TouchBar 时才生效。
TouchBar API 目前是实验性的,未来 Electron 版本中可能会更改或移除。
win.setTitleBarOverlay(options)
Windows Linux
在已启用窗口控件叠加的窗口上,此方法更新标题栏叠加的样式。
在 Linux 上,如果未明确设置 symbolColor
,则会自动计算其与 color
的最小可访问对比度。