跳转到主内容

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 窗口的顶部.

模态窗口

模态窗口是禁用父窗口的子窗口,创建模态窗口必须设置 parentmodal 选项:

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

创建并控制浏览器窗口。

进程:主进程

BrowserWindow 是一个 EventEmitter

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

new BrowserWindow([options])

  • options BrowserWindowConstructorOptions (optional)
    • width 整数型 (可选) - 窗口的宽度(以像素为单位)。 默认值为 800
    • height 整数型 (可选) - 窗口的高度(以像素为单位)。 默认值为 600
    • x Interger (可选) - (必选 如果使用了y) 窗口相对于屏幕左侧的偏移量。 默认值为将窗口居中。
    • y Integer (可选) - (必选 如果使用了x) 窗口相对于屏幕顶端的偏移量。 默认值为将窗口居中。
    • useContentSize boolean (可选) - widthheight 将设置为 web 页面的尺寸(译注: 不包含边框), 这意味着窗口的实际尺寸将包括窗口边框的大小,稍微会大一点。 默认值为 false.
    • center boolean (可选) - 窗口是否在屏幕居中. 默认值为 false.
    • 整型(可选)-窗口的最小宽度。默认为0 默认值为 0.
    • minHeight Integer(可选) - 窗口的最小高度。 默认值为 0.
    • maxWidth Integer(可选)-窗口的最大宽度。 默认值不限
    • maxHeight Integer (可选) - 窗口的最大高度。 默认值不限
    • resizable boolean (可选) - 窗口大小是否可调整。 默认值为 true
    • movable boolean (可选) macOS Windows - 窗口是否可移动。 在 Linux 上未实现。 默认值为 true
    • minimizable boolean (可选) macOS Windows - 窗口是否可最小化。 在 Linux 上未实现。 默认值为 true
    • maximizable boolean (可选) macOS Windows - 窗口是否最大化。 在 Linux 上未实现。 默认值为 true
    • closable boolean (可选) macOS Windows - 窗口是否可关闭。 在 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 - 在 macOS 上使用 pre-Lion 全屏。 默认值为 false.
    • skipTaskbar boolean (可选) macOS Windows - 是否在任务栏中显示窗口。 默认值为 false.
    • hiddenInMissionControl boolean (optional) macOS - Whether window should be hidden when the user toggles into mission control.
    • kiosk boolean (可选) - 窗口是否进入kiosk模式。 默认值为 false.
    • titlestring(可选) - 默认窗口标题 默认为"Electron"。 如果由loadURL()加载的HTML文件中含有标签<title>,此属性将被忽略。
    • icon (NativeImage | string) (可选) - 窗口图标。 在 Windows 上推荐使用 ICO 图标来获得最佳的视觉效果, 默认使用可执行文件的图标.
    • show boolean (可选) - 窗口是否在创建时显示。 默认值为 true
    • paintWhenInitiallyHiddenboolean(可选) - 当showfalse并且渲染器刚刚被创建时,它是否应激活。 为了让document.visibilityStateshow: false的情况下第一次加载时正确地工作,你应该把这个设置成false. 设置为 false 将会导致ready-to-show 事件不触发。 默认值为 true
    • frame boolean (可选) - 设置为 false 时可以创建一个无边框窗口 默认值为 true
    • parent BrowserWindow (可选) - 指定父窗口 默认值为 null.
    • modal boolean (可选) - 当前是否为模态窗口。 只有当窗口是子窗口时才起作用。 默认值为 false.
    • acceptFirstMouse boolean (可选) macOS - 点击 非活动窗口是否会穿透到 web contents。 在 macOS 中默认为 false。 此选项在其他平台上不可配置。
    • disableAutoHideCursor boolean (可选) - 是否在打字时隐藏光标。 默认值为 false.
    • autoHideMenuBar boolean (可选) - 自动隐藏菜单栏,除非按了Alt键。 默认值为 false.
    • enableLargerThanScreen boolean (可选) macOS - 使窗口尺寸可大于屏幕的大小。 仅与 macOS 相关,其他操作系统默认允许大于屏幕的窗口。 默认值为 false.
    • backgroundColor string (可选) - 窗口背景色,格式为 Hex, RGB, RGBA, HSL, HSLA 或 CSS 命名颜色。 如果 transparent 设置为 true,则支持#AARRGGBB格式的透明。 默认值为 #FFF(白色)。 更多详细信息,请参阅 win.setBackgroundColor
    • hasShadow boolean (可选) - 窗口是否有阴影. 默认值为 true
    • opacity number (可选) macOS Windows - 设置窗口的初始透明度,在 0.0(全透明)和 1.0(完全不透明)之间 。 目前仅在 Windows 和 macOS上实现。
    • darkTheme boolean (optional) - 强制窗口使用深色主题,只在部分GTK+3桌面环境下有效。 默认值为 false.
    • transparent boolean (可选) - 使窗口 透明。 默认值为 false. 在Windows上,仅在无边框窗口下起作用。
    • type string (可选) - 窗口的类型, 默认为普通窗口. 更多信息见下文
    • visualEffectState string (可选) macOS - 在 macOS 上指定外观应如何响应窗口活动状态。 必须与 vibrancy 属性一起使用。 可能的值有
      • followWindow - 当窗口处于激活状态时,后台应自动显示为激活状态,当窗口处于非激活状态时,后台应自动显示为非激活状态。 默认为该值。
      • active - 后台应一直显示为激活状态。
      • inactive - 后台应一直显示为非激活状态。
    • titleBarStyle string (可选) macOS Windows - 窗口标题栏样式。 默认值为 default. 可能的值有
      • default - 分别返回 macOS 或者 Windows 的标准标题栏
      • hidden - 在一个隐藏的标题栏和一个全尺寸大小的内容窗口中取得结果。 在 macOS 内, 窗口将一直拥有位于左上的标准窗口控制器 (“traffic lights”)。 在 Windows上,当与 titleBarOverlay: true 合并时,它将激活窗口控件叠加(详情请参阅 titleBarOverlay),否则将不会显示窗口控件。
      • hiddenInset macOS - 仅 macOS,隐藏标题栏,使用窗口边缘稍微小的红绿灯按钮替代。
      • customButtonsOnHover macOS - 仅 macOS,隐藏的标题栏的全尺寸的内容窗口, 红绿灯按钮在鼠标悬停在窗口左上方时显示。 注意: 此选项目前是实验性的。
    • trafficLightPosition Point (可选) macOS - 在无边框窗口中设置灯绿灯按钮位置。
    • roundedCorners boolean (可选) macOS - 无边框窗口在 macOS 上,是否应该有圆角。 默认值为 true。 属性设置为 false ,将阻止窗口是可全屏的。
    • fullscreenWindowTitle boolean (可选) macOS 已弃用 - titleBarStyle 设置为 hiddenInset 时,在 macOS 全屏模式下标题栏显示标题。 默认值为 false.
    • thickFrame boolean(可选)-对 Windows 上的无框窗口使用WS_THICKFRAME 样式,会增加标准窗口框架。 设置为 false 时将移除窗口的阴影和动画. 默认值为 true
    • vibrancy string (可选) macOS - 为窗口添加一种类型的动态效果,仅 macOS。 可以是 appearance-basedlightdarktitlebarselectionmenupopoversidebarmedium-lightultra-darkheadersheetwindowhudfullscreen-uitooltipcontentunder-windowunder-page。 请注意 appearance-basedlightdarkmedium-lightultra-dark 已弃用,在 macOS Catalina (10.15) 中已经移除。
    • backgroundMaterial string (optional) Windows - Set the window's system-drawn background material, including behind the non-client area. 可以是 auto, none, mica, acrylictabbed. 更多详细信息,请参阅 win.setBackgroundMaterial
    • zoomToPageWidth boolean (可选) macOS - 在 macOS 上控制,当按住 option 点击工具栏绿色红绿灯按钮或点击窗口 > 放大菜单项的行为。 如果为 true,窗口为将会缩放到适合宽度,若为 false 将会放大到屏幕宽度。 这也会影响,直接调用 maximize() 的行为。 默认值为 false.
    • tabbingIdentifier string (optional) macOS - Tab group name, allows opening the window as a native tab. Windows 中,有相同选项卡标识的将会组合在一起。 这会添加一个原生新增选项卡按钮到你窗口的选项卡栏,同时 app 和窗口允许接收 new-window-for-tab 事件。
    • webPreferences WebPreferences (optional) - Settings of web page's features.
      • devTools boolean (可选) - 是否开启 DevTools. 如果设置为 false, 则无法使用 BrowserWindow.webContents.openDevTools () 打开 DevTools。 默认值为 true
      • nodeIntegration boolean (可选) - 是否启用Node integration. 默认值为 false.
      • nodeIntegrationInWorker boolean (可选) - 是否在Web工作器中启用了Node集成. 默认值为 false. 更多内容参见 多线程.
      • nodeIntegrationInSubFrames boolean (可选项)(实验性),是否允许在子页面(iframe)或子窗口(child window)中集成Node.js; 预先加载的脚本会被注入到每一个iframe,你可以用 process.isMainFrame 来判断当前是否处于主框架(main frame)中。
      • preload string (可选) -在页面运行其他脚本之前预先加载指定的脚本 无论页面是否集成Node, 此脚本都可以访问所有Node API 脚本路径为文件的绝对路径。 当 node integration 关闭时, 预加载的脚本将从全局范围重新引入node的全局引用标志 参考示例.
      • sandbox boolean (可选)-如果设置该参数, 沙箱的渲染器将与窗口关联, 使它与Chromium OS-level 的沙箱兼容, 并禁用 Node. js 引擎。 它与 nodeIntegration 的选项不同,且预加载脚本的 API 也有限制. 更多详情.
      • session Session (可选) - 设置页面的 session 而不是直接忽略 Session 对象, 也可用 partition 选项来代替,它接受一个 partition 字符串. 同时设置了sessionpartition时, session 的优先级更高. 默认使用默认的 session.
      • partition string (optional) - 通过 session 的 partition 字符串来设置界面session. 如果 partitionpersist:开头, 该页面将使用持续的 session,并在所有页面生效,且使用同一个partition. 如果没有 persist: 前缀, 页面将使用 in-memory session. 通过分配相同的 partition, 多个页可以共享同一会话。 默认使用默认的 session.
      • 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
      • imageAnimationPolicy string (可选) - 指定如何运行图像动画 (比如: GIF等). 可以是 animate, animateOncenoAnimation. 默认值为 animate.
      • textAreasAreResizable boolean (可选) - 允许调整 TextArea 元素大小。 默认值为 true
      • webgl boolean (可选) - 启用 WebGL 支持。 默认值为 true
      • plugins boolean (可选) - 是否应该启用插件。 默认值为 false.
      • experimentalFeatures boolean (可选) - 启用 Chromium 的实验功能。 默认值为 false.
      • scrollBounce boolean (可选) macOS - 启用滚动回弹(橡皮筋)效果。 默认值为 false.
      • enableBlinkFeaturesstring(可选) - 以逗号分隔的需要启用的特性列表,譬如CSSVariables,KeyboardEventKeyRuntimeEnabledFeatures.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 脚本. 默认为 true预加载脚本所运行的上下文环境只能访问其自身专用的文档和全局窗口,其自身一系列内置的JavaScript (Array, Object, JSON, 等等) 也是如此,这些对于已加载的内容都是不可见的。 Electron API 将只在预加载脚本中可用,在已加载页面中不可用。 这个选项应被用于加载可能不被信任的远程内容时来确保加载的内容无法篡改预加载脚本和任何正在使用的Electron api。 该选项使用的是与Chrome内容脚本相同的技术。 你可以在开发者工具Console选项卡内顶部组合框中选择 'Electron Isolated Context'条目来访问这个上下文。
      • webviewTag boolean (可选) - 是否启用 <webview> tag标签. 默认值为 false. 注意: < webview> 配置的 preload 脚本在执行时将启用节点集成, 因此应确保远程或不受信任的内容无法创建恶意的 preload 脚本 。 可以使用 webContents 上的 will-attach-webview 事件对 preload 脚本进行剥离, 并验证或更改 <webview> 的初始设置。
      • additionalArguments string[] (可选) - 一个将被附加到当前应用程序的渲染器进程中process.argv的字符串列表 。 可用于将少量的数据传递到渲染器进程预加载脚本中。
      • safeDialogs boolean (可选) - 是否启用浏览器样式的持续对话框保护。 默认值为 false.
      • safeDialogsMessage string (可选) - 当持续对话框保护被触发时显示的消息。 如果没有定义,那么将使用缺省的消息。注意:当前缺省消息是英文,并没有本地化。
      • disableDialogs boolean (可选) - 是否完全禁用对话框。 覆盖 safeDialogs。 默认值为 false.
      • navigateOnDragDrop boolean (可选) - 将文件或链接拖放到页面上时是否触发页面跳转。 默认值为 false.
      • autoplayPolicy string (可选) - 窗口中内容要使用的自动播放策略,值可以是 no-user-gesture-required, user-gesture-required, document-user-activation-required。 默认为 no-user-gesture-required
      • disableHtmlFullscreenWindowResize boolean (可选) - 是否阻止窗口在进入 HTML 全屏时调整大小。 默认值为 false.
      • accessibleTitle string (可选) - 仅提供给如屏幕读取器等辅助工具的替代标题字符串。 此字符串不直接对用户可见。
      • spellcheck boolean (可选) - 是否启用内置拼写检查器。 默认值为 true
      • enableWebSQL boolean (可选) - 是否启用 WebSQL api。 默认值为 true
      • v8CacheOptions string (可选) - 强制 blink 使用 v8 代码缓存策略。 可接受的值为:
        • none - 禁用代码缓存
        • code - 基于启发式代码缓存
        • bypassHeatCheck - 绕过启发式代码缓存,但使用懒编译。
        • bypassHeatCheckAndEagerCompile - 与上面相同,除了编译是及时的。 默认策略是 code
      • enablePreferredSizeMode boolean (可选) - 是否启用首选大小模式。 首选大小是包含文档布局所需的最小大小--无需滚动。 启用该属性将导致在首选大小发生变化时,在WebContents 上触发 preferred-size-changed 事件。 默认值为 false.
    • titleBarOverlay Object | Boolean (optional) - When using a frameless window in conjunction with win.setWindowButtonVisibility(true) on macOS or using a titleBarStyle so that the standard window controls ("traffic lights" on macOS) are visible, this property enables the Window Controls Overlay JavaScript APIs and CSS Environment Variables. 指定 true 将导致覆盖默认系统颜色。 默认值为 false.
      • color String (可选) Windows - 启用窗口控制时覆盖面的 CSS 颜色 默认是系统颜色。
      • symbolColor String (可选) Windows - 启用时窗口控制中符号的 CSS 颜色 默认是系统颜色。
      • height Integer (可选) macOS Windows - 标题栏和 Window Controls Overlay,以像素为单位。 默认值为系统高度。

当使用 minWidth/maxWidth/minHeight/maxHeight 设置最小或最大窗口大小时, 它只限制用户。 它不会阻止您将不符合大小限制的值传递给 setBounds/setSizeBrowserWindow 的构造函数。

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

  • 在 Linux 上, 可能的类型有 desktopdocktoolbarsplashnotification
    • The desktop type places the window at the desktop background window level (kCGDesktopWindowLevel - 1). However, note that a desktop window will not receive focus, keyboard, or mouse events. You can still use globalShortcut to receive input sparingly.
    • The dock type creates a dock-like window behavior.
    • The toolbar type creates a window with a toolbar appearance.
    • The splash type behaves in a specific way. It is not draggable, even if the CSS styling of the window's body contains -webkit-app-region: drag. This type is commonly used for splash screens.
    • The notification type creates a window that behaves like a system notification.
  • 在 macOS 上,可能的类型为 desktoptexturedpanel
    • textured 类型增加金属色泽的外观 (NSWindowStyleMaskTexturedBackground).
    • desktop 类型将窗口置于桌面背景级别 (kCGDesktopWindowLevel - 1). 注意,桌面窗口不会接收焦点、键盘或鼠标事件,但您可以使用 globalShortcut 接收快捷键的消息
    • panel 类型,窗口浮于全屏应用顶部,通过添加 NSWindowStyleMaskNonactivatingPanel 样式掩码,通常为NSPanel 保留,在运行时。 此外, 该窗口将出现在所有空间(桌面)上。
  • 在 Windows 上, 可能的类型为 toolbar.

实例事件

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

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

事件: 'page-title-updated'

返回:

  • event Event
  • title string
  • explicitSet boolean

文档更改标题时触发,调用event.preventDefault()将阻止更改标题 当标题合成自文件 URL 中时, explicitSet 的值为false。

事件: 'close'

返回:

  • event Event

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

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

window.onbeforeunload = (e) => {
console.log('I do not want to be closed')

// 与通常的浏览器不同,会提示给用户一个消息框,
//返回非空值将默认取消关闭
//建议使用对话框 API 让用户确认关闭应用程序.
e.returnValue = false
}

注意:在 window.onbeforeunload &equals; handlerwindow.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 Event
  • newBounds Rectangle - 将要调整到的窗口尺寸。
  • details Object
    • edge (string) - 窗口边缘被拖动以调整大小。 值可以是 bottom, left, right, top-left, top-right, bottom-leftbottom-right.

调整窗口大小前触发。 调用 event.preventDefault() 将阻止窗口大小调整。

请注意,该事件仅在手动调整窗口大小时触发。 通过 setBounds/setSize 调整窗口大小不会触发此事件。

edge 选项的可用值和行为选项与平台相关 可能的值有

  • 在 Windows 平台可用值有 bottom, top, left, right, top-left, top-right, bottom-left, bottom-right.
  • 在 macOS, 可用值有 bottomright.
    • bottom 值用于表示垂直调整大小。
    • right 值用于表示水平调整大小。

事件: 'resize'

调整窗口大小后触发。

事件:'resized' macOS Windows

当窗口完成调整大小后触发一次。

这通常在手动调整窗口大小后触发。 在 macOS 系统上,使用setBounds/setSize调整窗口大小并将animate参数设置为true也会在调整大小完成后触发此事件。

事件: 'will-move' macOS Windows

返回:

  • event Event
  • newBounds 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 Event
  • isAlwaysOnTop boolean

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

事件: 'app-command' Windows__Linux

返回:

  • event Event
  • command 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

Event: 'scroll-touch-begin' macOS 已废弃

滚轮事件阶段开始时触发

注意 该事件从 Electron 22.0.0 版本开始已废弃。 详细信息,请参考 中断性变更,如何迁移到 WebContents 的 input-event 事件。

Event: 'scroll-touch-end' macOS 已废弃

滚轮事件阶段结束时触发

注意 该事件从 Electron 22.0.0 版本开始已废弃。 详细信息,请参考 中断性变更,如何迁移到 WebContents 的 input-event 事件。

Event: 'scroll-touch-edge' macOS 已废弃

滚轮事件阶段到达元素边缘时触发

注意 该事件从 Electron 22.0.0 版本开始已废弃。 详细信息,请参考 中断性变更,如何迁移到 WebContents 的 input-event 事件。

事件: 'swipe' macOS

返回:

  • event Event
  • direction 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 Event
  • rotation Float

在触控板旋转手势上触发。 持续触发直到旋转手势结束。 每次触发的 rotation 值是自上次触发以来旋转的角度。 旋转手势最后一次触发的事件值永远是0。 逆时针旋转值为正值,顺时针旋转值为负值。

事件: 'sheet-begin' macOS

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

事件: 'sheet-end' macOS

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

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

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

事件: 'system-context-menu' Windows

返回:

  • event Event
  • point Point - 上下文菜单触发时的屏幕坐标。

当系统上下文菜单在窗口上触发时发出, 通常只在用户右键点击你窗口的非客户端区域时触发。 非客户端区域指的是窗口标题栏或无边框窗口中被你声明为 -webkit-app-region: drag 的任意区域。

调用 event.preventDefault() 将阻止菜单显示。

静态方法

BrowserWindow 类有以下方法:

BrowserWindow.getAllWindows()

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

BrowserWindow.getFocusedWindow()

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

BrowserWindow.fromWebContents(webContents)

返回 BrowserWindow | null - 返回拥有给定 webContents的窗口,否则如果内容不属于一个窗口,返回null

BrowserWindow.fromBrowserView(browserView)

返回 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.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)

win.accessibleTitle

一个 string 属性,定义一个仅为如屏幕阅读器等辅助工具提供的替代标题 。 此字符串不直接对用户可见。

实例方法

使用 new BrowserWindow 创建的对象具有以下实例方法:

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

win.destroy()

强制关闭窗口, 除了closed之外,closeunloadbeforeunload 都不会被触发

win.close()

尝试关闭窗口。 该方法与用户手动单击窗口的关闭按钮效果相同。 但网页可能会取消这个关闭操作。 查看 关闭事件

win.focus()

聚焦于窗口

win.blur()

取消窗口的聚焦

win.isFocused()

返回 boolean - 判断窗口是否聚焦

win.isDestroyed()

返回 boolean -判断窗口是否被销毁

win.show()

显示并聚焦于窗口

win.showInactive()

显示但不聚焦于窗口

win.hide()

隐藏窗口

win.isVisible()

Returns boolean - Whether the window is visible to the user in the foreground of the app.

win.isModal()

返回 boolean - 判断是否为模态窗口

win.maximize()

最大化窗口。 如果窗口尚未显示,该方法也会将其显示 (但不会聚焦)。

win.unmaximize()

取消窗口最大化

win.isMaximized()

返回 boolean - 判断窗口是否最大化

win.minimize()

最小化窗口。 在某些平台上, 最小化的窗口将显示在Dock中。

win.restore()

将窗口从最小化状态恢复到以前的状态。

win.isMinimized()

返回 boolean -判断窗口是否最小化

win.setFullScreen(flag)

  • flag boolean

设置窗口是否应处于全屏模式。

Note: On macOS, fullscreen transitions take place asynchronously. If further actions depend on the fullscreen state, use the 'enter-full-screen' or 'leave-full-screen' events.

win.isFullScreen()

返回 boolean - 窗口当前是否已全屏

win.setSimpleFullScreen(flag) macOS

  • flag boolean

进入或离开简单的全屏模式。

简单全屏模式模拟了 Lion (10.7) 之前的macOS版本中的原生全屏行为。

win.isSimpleFullScreen() macOS

返回 boolean - 窗口是否为简单全屏模式(pre-Lion)。

win.isNormal()

返回 boolean - 窗口是否处于正常状态(未最大化,未最小化,不在全屏模式下)。

win.setAspectRatio(aspectRatio[, extraSize])

  • aspectRatio Float- 为内容视图保持的宽高比.
  • extraSize Size (可选) macOS - 保持宽高比时不包括的额外大小。

这将使窗口保持长宽比。 额外的大小允许开发人员有空间 (以像素为单位), 不包括在纵横比计算中。 此 API 已经考虑了窗口大小和内容大小之间的差异。

想象一个使用高清视频播放器和相关控件的普通窗口。 假假如左边缘有15px, 右边缘有25px, 在播放器下面有50px. 为了保持播放器本身16:9 的长宽比 (标准的HD长宽比为1920x1080), 我们可以使用 16/9 和 { width: 40, height: 50 } 的参数调用这个函数。 第二个参数不管网页中的额外的宽度和高度在什么位置, 只要它们存在就行. 在全部内部窗口中,加上任何额外的宽度和高度 。

当窗口使用类似于 win.setSize 这样的 API 调整窗口时,宽高比不会被采用。

To reset an aspect ratio, pass 0 as the aspectRatio value: win.setAspectRatio(0).

win.setBackgroundColor(backgroundColor)

  • backgroundColor string - 颜色,格式为 Hex,RGB,RGBA,HSL,HSLA 或 CSS 命名颜色。 对于 Hex 类型,透明通道为可选的。

有效的 backgroundColor 值的例子:

  • Hex
    • #fff (shorthand RGB)
    • #ffff (shorthand ARGB)
    • #ffffff (RGB)
    • #ffffffff (ARGB)
  • RGB
    • rgb(([\d]+),\s([\d]+),\s([\d]+))
      • e.g. rgb(255, 255, 255)
  • RGBA
    • rgba(([\d]+),\s([\d]+),\s([\d]+),\s*([\d.]+))
      • e.g. rgba(255, 255, 255, 1.0)
  • HSL
    • hsl((-?[\d.]+),\s([\d.]+)%,\s([\d.]+)%)
      • e.g. hsl(200, 20%, 50%)
  • HSLA
    • hsla((-?[\d.]+),\s([\d.]+)%,\s([\d.]+)%,\s*([\d.]+))
      • e.g. hsla(200, 20%, 50%, 0.5)
  • Color name
    • 名称列表在 SkParseColor.cpp
    • 类似 CSS Color Module Level 3 关键字,但大小写敏感。
      • 例如 bluevioletred

设置窗口的背景颜色。 请参阅 设置 backgroundColor

win.previewFile(path[, displayName]) macOS

  • path string -要用 QuickLook 预览的文件的绝对路径。 这一点很重要,因为Quick Look 使用了路径上的文件名和文件扩展名 来决定要打开的文件的内容类型。
  • displayName string (可选) - 在Quick Look 模态视图中显示的文件的名称。 这完全是视觉的,不会影响文件的内容类型。 默认值为 path.

Uses Quick Look to preview a file at a given path.

win.closeFilePreview() macOS

Closes the currently open Quick Look panel.

win.setBounds(bounds[, animate])

  • bounds Partial<Rectangle>
  • animate boolean (可选) macOS

重置窗口,并且移动窗口到指定的位置. 任何未提供的属性将默认为其当前值。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

// 设置所有 bounds 边界属性
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// 设置单一 bounds 边界属性
win.setBounds({ width: 100 })

// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())

Note: On macOS, the y-coordinate value cannot be smaller than the Tray height. The tray height has changed over time and depends on the operating system, but is between 20-40px. Passing a value lower than the tray height will result in a window that is flush to the tray.

win.getBounds()

返回 Rectangle - 以 Object 表示窗口的 bounds

Note: On macOS, the y-coordinate value returned will be at minimum the Tray height. For example, calling win.setBounds({ x: 25, y: 20, width: 800, height: 600 }) with a tray height of 38 means that win.getBounds() will return { x: 25, y: 38, width: 800, height: 600 }.

win.getBackgroundColor()

返回 string - 格式获取窗口的背景色,格式为 Hex (#RRGGBB)。

请参阅 设置 backgroundColor

注意: 透明通道的值 不会 与红色、绿色和蓝色值一起返回。

win.setContentBounds(bounds[, animate])

  • bounds Rectangle
  • animate boolean (可选) macOS

调整窗口的工作区 (如网页) 的大小并将其移动到所提供的边界。

win.getContentBounds()

返回 Rectangle - 窗口客户端区域的 bounds 对象

win.getNormalBounds()

返回 Rectangle - 包含正常状态下的窗口大小。

注意:无论当前的窗口状态为:最大化、最小化或者全屏,这个方法都将得到窗口在正常显示状态下的位置信息以及大小信息。 在正常状态下,getBounds 与 getNormalBounds 得到的边界信息 Rectangle 是一致的。

win.setEnabled(enable)

  • enable boolean

禁用或者启用窗口。

win.isEnabled()

返回 boolean - 窗口是否启用。

win.setSize(width, height[, animate])

  • width Integer
  • height Integer
  • animate boolean (可选) macOS

调整窗口的widthheight. 如果 widthheight 低于任何设定的最小尺寸约束,窗口将对齐到约束的最小尺寸。

win.getSize()

返回 Integer []-包含窗口的宽度和高度。

win.setContentSize(width, height[, animate])

  • width Integer
  • height Integer
  • animate boolean (可选) macOS

将窗口的工作区 (如网页) 的大小调整为 widthheight

win.getContentSize()

返回 Integer []-包含窗口的宽度和高度。

win.setMinimumSize(width, height)

  • width Integer
  • height Integer

设置窗口最小化的 widthheight.

win.getMinimumSize()

返回 Integer []-包含窗口最小化的宽度和高度。

win.setMaximumSize(width, height)

  • width Integer
  • height Integer

设置窗口最大化的 widthheight.

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

Sets whether the window will be hidden when the user toggles into mission control.

win.isHiddenInMissionControl() macOS

Returns boolean - Whether the window will be hidden when the user toggles into mission control.

win.setAlwaysOnTop(flag[, level][, relativeLevel])

  • flag boolean
  • level string (可选) macOS Windows - 值包括 normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saverdock(已弃用)。 当 flag 属性为true时,默认值为 floating 。 当flag为false时,level 会重置为 normal。 请注意,包括从 floatingstatus ,窗口会被置于 macOS 上的 Dock 下方和 Windows 上的任务栏下方。 从 pop-up-menu 到更高级别,窗口显示在 macOS 上的Dock上方和 Windows 上的任务栏上方。 See the macOS docs for more details.
  • relativeLevel Integer (可选) macOS - 设置此窗口相对于给定 级别的层数。. 默认值为0. 请注意, Apple 不鼓励在 屏幕保护程序 之上设置高于1的级别。

设置窗口是否应始终显示在其他窗口的前面。 设置后,窗口仍然是一个正常窗口,而不是一个无法获取焦点的工具框窗口。

win.isAlwaysOnTop()

返回 boolean - 当前窗口是否始终在其它窗口之前.

win.moveAbove(mediaSourceId)

  • mediaSourceId string - DesktopCapturerSource格式的窗口 id 。 例如 "window:1869:0"。

将窗口按z轴顺序移动到源窗口前面。 如果 mediaSourceId 不是window类型,或者如果窗口不存在,则此方法会抛出一个错误。

win.moveTop()

无论焦点如何, 将窗口移至顶端(z轴上的顺序).

win.center()

将窗口移动到屏幕中央。

win.setPosition(x, y[, animate])

  • x Integer
  • y Integer
  • animate boolean (可选) macOS

将窗口移动到 xy

win.getPosition()

返回 Integer[] - 返回一个包含当前窗口位置的数组.

win.setTitle(title)

  • title string

将原生窗口的标题更改为 title

win.getTitle()

返回 string - 本地窗口标题。

注意: 网页的标题可以与原生窗口的标题不同。

win.setSheetOffset(offsetY[, offsetX]) macOS

  • offsetY Float
  • offsetX Float (可选)

改变macOS上sheet组件的附着点。 默认情况下,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 作为平板电脑来使用,在此模式下,应用可以选择为平板电脑的界面做出优化,如扩展标题栏和隐藏标题栏按钮。

此 API 返回 窗口是否在平板电脑模式下,并且 调整大小 事件可以用于监听对平板模式的更改。

win.getMediaSourceId()

返回 string - DesktopCapturerSource的id格式的窗口 id 。 例如 "window:1324:0"。

更确切地说,格式是 window:id:other_id。在Windows上 idHWND 类型;在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 Integer
  • callback Function
    • wParam Buffer - The wParam provided to the WndProc
    • lParam Buffer - The lParam provided to the WndProc

钩住窗口消息。 当消息到达 WndProc 时调用callback

win.isWindowMessageHooked(message) Windows

  • message Integer

返回 boolean - truefalse ,具体取决于是否钩挂了消息.

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 (可选) - 捕获的区域
  • opts Object (optional)
    • stayHidden boolean (可选) - 使页面保持隐藏而不是可见。 默认值为 false.
    • stayAwake boolean (可选) - 使系统保持唤醒状态,而不是让它处于睡眠状态。 默认值为 false.

返回 Promise<NativeImage> - 完成后返回一个NativeImage

rect内捕获页面的快照。 省略 rect 将捕获整个可见页面。 如果页面不可见, rect 可能是空的。 The page is considered visible when its browser window is hidden and the capturer count is non-zero. 如果你想要页面保持隐藏状态,则应确保 stayHidden 设置为 true。

win.loadURL(url[, options])

  • url string
  • options Object (可选)
    • httpReferrer (string | Referrer) (可选) - HTTP 引用 url。
    • userAgent string (可选) - 发起请求的 userAgent.
    • extraHeaders string (可选) - 用 "\n" 分割的额外标题
    • postData (UploadRawData | UploadFile)[] (可选)
    • baseURLForDataURL string (可选) - 要由数据URL加载的文件基本URL(末尾带有路径分隔符)。 仅当指定的url是数据url并且需要加载其他文件时,才需要此选项。

返回 Promise<void> - 当页面完成加载后 promise 将会resolve (见 did-finish-load),如果页面加载失败,则 reject (见 did-fail-load)。

webContents.loadURL(url[, options]) 相同。

url 可以是远程地址 (例如 http://),也可以是 file:// 协议的本地HTML文件的路径.

为了确保文件网址格式正确, 建议使用Node的 url.format 方法:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

const url = require('url').format({
protocol: 'file',
slashes: true,
pathname: require('path').join(__dirname, 'index.html')
})

win.loadURL(url)

您可以通过执行以下操作, 使用带有网址编码数据的 POST请求​​加载网址:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('http://localhost:8000/post', {
postData: [{
type: 'rawData',
bytes: Buffer.from('hello=world')
}],
extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})

win.loadFile(filePath[, options])

  • filePath string
  • options Object (可选)
    • query Record<string, string> (optional) - Passed to url.format().
    • search string (可选) - 传递给 url.format().
    • hash string (可选) - 传递给 url.format().

返回 Promise<void> - 当页面完成加载后 promise 将会resolve (见 did-finish-load),如果页面加载失败,则 reject (见 did-fail-load)。

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
  • options Object (可选)
    • mode string Windows - 进度条的状态。 可以是 nonenormalindeterminateerrorpaused

设置进度条的进度值。 Valid range is [0, 1.0].

当进度小于0时不显示进度; 当进度大于0时显示结果不确定.

在 Linux 平台上,只支持 Unity 桌面模式, 你需要在 package.json 中为 desktopName 指定 *.desktop 的文件名. 默认情况下,将取 {app.name}.desktop

在 Windows 上, 可以传递模式。 可以接受的值为none, normal, indeterminate, errorpaused. 如果没有设置模式 (但值在有效范围内) 的情况下调用 setProgressBar, 默认值为normal

win.setOverlayIcon(overlay, description) Windows

  • overlay NativeImage | null - 右下角任务栏的显示图标。 如果此参数是 null,覆盖层层会被清除。
  • description string -提供给屏幕阅读器的描述文字

在当前任务栏图标上设置一个 16 x 16 像素的图标, 通常用于传达某种应用程序状态或被动地通知用户。

win.invalidateShadow() macOS

Invalidates the window shadow so that it is recomputed based on the current window shape.

BrowserWindows that are transparent can sometimes leave behind visual artifacts on macOS. This method can be used to clear these artifacts when, for example, performing an animation.

win.setHasShadow(hasShadow)

  • hasShadow boolean

设置窗口是否有阴影。

win.hasShadow()

返回 boolean - 判断窗口是否有阴影.

win.setOpacity(opacity) Windows macOS

  • opacity number - 介于0.0 ( 完全透明 ) 和1.0 ( 完全不透明 ) 之间

设置窗口的不透明度。 在Linux上不起作用。 Out of bound number values are clamped to the [0, 1] range.

win.getOpacity()

返回 number - 介于0.0 (完全透明) 和1.0 (完全不透明) 之间。 在Linux上,始终返回1。

win.setShape(rects) Windows Linux 实验性

  • rects Rectangle[] - 在窗口上设置形状。 通过传入空列表将窗口恢复为矩形。

对窗口形状的设置决定了窗口内系统允许绘制与用户交互的区域. 在给定的区域外, 没有像素会被绘制, 且没有鼠标事件会被登记. 在该区域外的鼠标事件将不会被该窗口接收, 而是落至该窗口后方的任意窗口.

win.setThumbarButtons(buttons) Windows

返回 boolean - 按钮是否成功添加

将指定的一组按钮添加到菜单栏的缩图工具栏上。 返回一个 boolean 对象表示是否成功地添加了缩略图.

由于空间有限, 缩图工具栏中的按钮数量不要超过7个。 一旦设置了缩略图工具栏,则无法删除。 但你可以通过调用 API 传递一个空数组来清除按钮.

buttons 是一个 Button 对象的数组:

  • Button Object
    • icon NativeImage - 显示在缩略图工具栏中的图标.
    • click Function
    • tooltip string (可选) - 按钮的提示文本.
    • flags string[] (可选) - 控制按钮的特定状态和行为。 默认情况下,值为 ['enabled']

flags 属性是一个数组,包含以下string类型的值:

  • enabled - 该按钮处于活动状态并可供用户使用.
  • disabled - 按钮已禁用。 会以一种视觉状态表示它不会响应用户操作的形式显示。
  • dismissonclick - 当按钮被点击时,缩略图窗口立即关闭。
  • nobackground - 仅仅使用图像而不绘制边框。
  • hidden - 该按钮对用户不可见。
  • noninteractive - 按钮已启用,但不交互;不绘制按钮按下的状态。 此值用于在通知中使用按钮的实例。

win.setThumbnailClip(region) Windows

将窗口的区域设置为在任务栏中悬停在窗口上方时显示的缩略图图像。 通过指定空区域:{ x: 0, y: 0, width: 0, height: 0 },可以重置整个窗口的缩略图。

win.setThumbnailToolTip(toolTip) Windows

  • toolTip string

设置在任务栏中悬停在窗口缩略图上时显示的工具提示。

win.setAppDetails(options) Windows

  • 选项 对象
    • appId string (可选) - 窗口的 App User Model ID. 该项必须设置, 否则其他选项将没有效果.
    • appIconPath string (可选) -窗口的 Relaunch Icon.
    • appIconIndex Integer (可选) - appIconPath中的图标索引。 未设置 appIconPath 时忽略。 默认值为 0.
    • relaunchCommand string (可选) - 窗口的 重新启动命令.
    • relaunchDisplayName string (可选) - 窗口的重新启动显示名称.

设置窗口任务栏按钮的属性。

注意:必须始终同时设置 relaunchCommandrelaunchDisplayName。 如果其中一个属性没有设置,那么这两个属性都不会使用。

win.showDefinitionForSelection() macOS

webContents.showDefinitionForSelection() 相同.

win.setIcon(icon) Windows Linux

设置窗口图标

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.setVisibleOnAllWorkspaces(visible[, options]) macOS Linux

  • visible boolean
  • options Object (可选)
    • visibleOnFullScreen boolean (可选) macOS - 设置当前窗口是否可以在全屏窗口之上显示。
    • skipTransformProcessType boolean (可选) macOS - 调用 setVisibleOnAllWorkspaces ,默认转换流程类型于 UIElementApplication 和 ForegroundApplication 之间,用来保障正常响应。 然而,当方法被调用时将短暂的隐藏窗口和图标。 如果你的窗口已经是 UIElementApplication 类似,你可以绕过这次转换通过传递 true 参数给TransformProcessType。

设置窗口是否在所有工作空间上可见

注意: 该 API 在 Windows 上无效.

win.isVisibleOnAllWorkspaces() macOS Linux

返回 boolean - 判断窗口是否在所有工作空间上可见.

注意: 该 API 在 Windows 上始终返回 false.

win.setIgnoreMouseEvents(ignore[, options])

  • ignore boolean
  • options Object (可选)
    • forward boolean (可选) macOS Windows - 如果为 true, 传递鼠标移动消息给 Chromium,鼠标相关事件将可用,如 mouseleave。 仅当 ignore </ 0>为 true 时才被使用。 如果 <code>ignore 为 false, 转发始终是禁用的,不管这个值是什么。

忽略窗口内的所有鼠标事件

在此窗口中发生的所有鼠标事件将被传递到此窗口下面的窗口, 但如果此窗口具有焦点, 它仍然会接收键盘事件

win.setContentProtection(enable) macOS Windows

  • enable boolean

防止窗口内容被其他应用捕获

在 macOS 上,它将 NSWindow 的 sharingType 设置为 NSWindowSharingNone。 在 Windows 上,它以参数为 WDA_EXCLUDEFROMCAPTURE 调用 SetWindowDisplayAffinity 。 对于 Windows 10 2004以上版,本窗口将完全从抓取中移除,在低版本 Windows 上其行为就像是 WDA_MONITOR 捕捉了黑色窗口。

win.setFocusable(focusable) macOS Windows

  • focusable boolean

设置窗口是否可聚焦

在 macOS 上,该方法不会从窗口中移除焦点。

win.isFocusable() macOS Windows

Returns boolean - Whether the window can be focused.

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.mergeAllWindows() macOS

当启用本地选项卡并且存在多个打开窗口时,将所有窗口合并到一个带有多个选项卡的窗口中。

win.moveTabToNewWindow() macOS

如果启用了本机选项卡并且当前窗口中有多个选项卡,则将当前选项卡移动到新窗口中。

win.toggleTabBar() macOS

如果启用了本机选项卡并且当前窗口中只有一个选项卡,则切换选项卡栏是否可见。

win.addTabbedWindow(browserWindow) macOS

  • browserWindow BrowserWindow

在该窗口中添加一个窗口作为选项卡,位于窗口实例的选项卡之后。

win.setVibrancy(type) macOS

  • type string | null - 可以是 appearance-basedlightdarktitlebarselectionmenupopoversidebarmedium-lightultra-darkheadersheetwindowhudfullscreen-uitooltipcontentunder-windowunder-page。 See the macOS documentation for more details.

在浏览器窗口中添加一个动态特效。 传递 null 或空字符串将会移除窗口上的动态效果。

请注意, appearance-basedlightdarkmedium-lightultra-dark 已被弃用,并将在即将推出的 macOS 版本中被移除。

win.setBackgroundMaterial(material) Windows

  • material string
    • auto - Let the Desktop Window Manager (DWM) automatically decide the system-drawn backdrop material for this window. 默认为该值。
    • none - Don't draw any system backdrop.
    • mica - Draw the backdrop material effect corresponding to a long-lived window.
    • acrylic - Draw the backdrop material effect corresponding to a transient window.
    • tabbed - Draw the backdrop material effect corresponding to a window with a tabbed title bar.

This method sets the browser window's system-drawn background material, including behind the non-client area.

See the Windows documentation for more details.

Note: This method is only supported on Windows 11 22H2 and up.

win.setWindowButtonPosition(position) macOS

在无框窗口中设置自定义控制按钮的位置。 Passing null will reset the position to default.

win.getWindowButtonPosition() macOS

Returns Point | null - The custom position for the traffic light buttons in frameless window, null will be returned when there is no custom position.

win.setTrafficLightPosition(position) macOS 已弃用

在无框窗口中设置自定义控制按钮的位置。 Passing { x: 0, y: 0 } will reset the position to default.

Note This function is deprecated. Use setWindowButtonPosition instead.

win.getTrafficLightPosition() macOS 已弃用

Returns Point - The custom position for the traffic light buttons in frameless window, { x: 0, y: 0 } will be returned when there is no custom position.

Note This function is deprecated. Use getWindowButtonPosition instead.

win.setTouchBar(touchBar) macOS

  • touchBar TouchBar | null

设置窗口的触摸条布局 设置为 nullundefined将清除触摸条. This method only has an effect if the machine has a touch bar.

注意: TouchBar API目前为实验性质,可能会更改或删除。

win.setBrowserView(browserView) 实验

  • browserView BrowserView | null - 将 browserView 附加到 win。 如果已经附加了其他 BrowserView,那么它们将会被从此窗口中移除。

win.getBrowserView() 实验功能

返回 BrowserView | null - 附加到 winBrowserView 。 如果未附加,则返回 null。 如果附加了多个 BrowserView,则抛出错误。

win.addBrowserView(browserView) 实验

替代 setBrowserView 的API,支持多个browserView一起使用。

win.removeBrowserView(browserView) 实验

win.setTopBrowserView(browserView) 实验

提高 browserView 于其它附加到 winBrowserView 之上 。 如果 browserView 未附加到 win,则抛出错误。

win.getBrowserViews() 实验功能

返回 BrowserView[] - 所有通过 addBrowserViewsetBrowserView 附加的BrowserView数组。

注意: BrowserView 的 API目前为实验性质,可能会更改或删除。

win.setTitleBarOverlay(options) Windows

  • 选项 对象
    • color String (可选) Windows - 启用窗口控制时覆盖面的 CSS 颜色
    • symbolColor String (可选) Windows - 启用时窗口控制中符号的 CSS 颜色
    • height Integer (可选) Windows - 标题栏和 Window Controls Overlay,以像素为单位。

在已开启 Window Controls Overlay 的窗口上,此方法将更新标题栏叠加层的样式。