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()
})

页面可见性¶

Page Visibility API 的工作方式如下：

在所有平台上，可见性状态跟踪窗口是否隐藏/最小化。
此外，在 macOS 上，可见性状态还跟踪窗口的遮挡状态。如果窗口被另一个窗口遮挡（即完全覆盖），可见性状态将为 hidden。在其他平台上，只有当窗口被最小化或通过 win.hide() 显式隐藏时，可见性状态才会为 hidden。
如果使用 show: false 创建 BrowserWindow，即使窗口实际处于隐藏状态，初始可见性状态也将为 visible。
如果禁用了 backgroundThrottling，即使窗口被最小化、遮挡或隐藏，可见性状态也将保持为 visible。

建议当可见性状态为 hidden 时暂停高开销操作，以最大限度减少功耗。

平台注意事项¶

在 macOS 上，模态窗口将显示为附加到父窗口的窗格。
在 macOS 上，当父窗口移动时，子窗口将保持相对于父窗口的位置；而在 Windows 和 Linux 上，子窗口不会移动。
在 Linux 上，模态窗口的类型将更改为 dialog。
在 Linux 上，许多桌面环境不支持隐藏模态窗口。
在 Wayland（Linux）上，通常无法在创建窗口后通过编程方式调整窗口大小，也无法在用户输入的情况下定位、移动、聚焦或取消聚焦窗口。如果你的应用需要这些功能，请通过添加标志 --ozone-platform=x11 在 Xwayland 中运行它。

类：BrowserWindow 继承自 `BaseWindow`¶

创建并控制浏览器窗口。

进程：主进程

BrowserWindow 是一个 EventEmitter。

它根据 options 中设置的属性创建一个新的 BrowserWindow。

[!WARNING] Electron 的内置类无法在用户代码中被子类化。更多信息，请参阅常见问题解答。

`new BrowserWindow([options])`¶

options BrowserWindowConstructorOptions（可选）

实例事件¶

使用 new BrowserWindow 创建的对象会发出以下事件：

[!NOTE] 某些事件仅在特定操作系统上可用，并会相应标注。

事件：'page-title-updated'¶

返回值：

event 事件
title 字符串
explicitSet 布尔值

当文档更改其标题时发出。调用 event.preventDefault() 将阻止原生窗口标题更改。当标题由文件 URL 合成时，explicitSet 为 false。

事件：'close'¶

返回值：

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
}

[!NOTE] 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'¶

当窗口最小化时发出。

[!NOTE] 在 Wayland 上，“最小化”目前不是受支持的状态。最小化事件仅在由客户端装饰触发时才会触发（例如，点击无边框窗口的 Window Control Overlay 上的最小化按钮）。

事件：'restore'¶

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

事件：'will-resize' macOS Windows¶

返回值：

event 事件
newBounds Rectangle - 窗口正在调整到的大小。
details 对象
edge (字符串) - 正在拖动以调整大小的窗口边缘。可以是 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 事件
newBounds Rectangle - 窗口正在移动到的位置。

在窗口移动之前发出。在 Windows 上，调用 event.preventDefault() 将阻止窗口被移动。

请注意，这仅在窗口被手动移动时发出。使用 setPosition/setBounds/center 移动窗口不会发出此事件。

事件：'move'¶

当窗口正在移动到新位置时发出。

事件：'moved' macOS Windows¶

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

[!NOTE] 在 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 事件
isAlwaysOnTop 布尔值

当窗口被设置为始终显示在其他窗口之上或取消该设置时发出。

事件：'app-command' Windows Linux¶

返回值：

event Event
command 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 Event
direction string

在三指轻扫时触发。可能的方向有 up、right、down、left。

此事件所基于的方法旨在处理较旧的 macOS 风格触控板轻扫，即屏幕内容不随轻扫移动。大多数 macOS 触控板已不再配置为允许这种轻扫方式，因此为了使其正确触发，必须在 System Preferences > Trackpad > More Gestures 中将“在页面之间轻扫”偏好设置为“用两个或三个手指轻扫”。

事件：'rotate-gesture' macOS¶

返回：

event Event
rotation Float

在触控板旋转手势时触发。持续触发，直到旋转手势结束。每次触发时的 rotation 值是自上次触发以来旋转的角度（以度为单位）。旋转手势结束时触发的最后一个事件的 rotation 值始终为 0。逆时针旋转的值为正，顺时针旋转的值为负。

事件：'sheet-begin' macOS¶

当窗口打开 sheet 时触发。

事件：'sheet-end' macOS¶

当窗口关闭 sheet 时触发。

事件：'new-window-for-tab' macOS¶

当用户点击 macOS 原生的新建标签页按钮时触发。仅当当前 BrowserWindow 具有 tabbingIdentifier 时，新建标签页按钮才可见。

你必须在此处理程序中创建一个窗口，macOS 的标签页功能才能按预期工作。

返回：

event Event
point 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

[!NOTE] 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 文档。

[!NOTE] 窗口销毁后，读取此属性会抛出 Object has been destroyed；请参阅 win.isDestroyed()。

`win.id` 只读¶

一个 Integer 属性，表示窗口的唯一 ID。在整个 Electron 应用的所有 BrowserWindow 实例中，每个 ID 都是唯一的。

`win.tabbingIdentifier` macOS 只读¶

一个 string（可选）属性，等于传递给 BrowserWindow 构造函数的 tabbingIdentifier；如果未设置，则为 undefined。

`win.autoHideMenuBar` Linux Windows¶

一个 boolean 属性，决定窗口菜单栏是否应自动隐藏。设置后，菜单栏只会在用户按下单独的 Alt 键时显示。

如果菜单栏已经可见，将此属性设置为 true 不会立即隐藏它。

`win.simpleFullScreen`¶

一个 boolean 属性，决定窗口是否处于简单（pre-Lion）全屏模式。

`win.fullScreen`¶

一个 boolean 属性，决定窗口是否处于全屏模式。

`win.focusable` Windows macOS¶

一个 boolean 属性，决定窗口是否可获得焦点。

`win.visibleOnAllWorkspaces` macOS Linux¶

一个 boolean 属性，决定窗口是否在所有工作区中可见。

[!NOTE] 在 Windows 上始终返回 false。

`win.shadow`¶

一个 boolean 属性，决定窗口是否有阴影。

`win.menuBarVisible` Windows Linux¶

一个 boolean 属性，用于确定菜单栏是否应显示。

[!NOTE] 如果菜单栏设置为自动隐藏，用户仍可通过单独按下 Alt 键调出菜单栏。

`win.kiosk`¶

一个 boolean 属性，用于确定窗口是否处于 kiosk 模式。

`win.documentEdited` macOS¶

一个 boolean 属性，用于指定窗口的文档是否已被编辑。

当设置为 true 时，标题栏中的图标将变为灰色。

`win.representedFilename` macOS¶

一个 string 属性，用于确定窗口所表示文件的路径，并且该文件的图标将显示在窗口标题栏中。

`win.title`¶

一个 string 属性，用于确定原生窗口的标题。

[!NOTE] 网页的标题可能与原生窗口的标题不同。

`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。

```js @ts-expect-error=[11] 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` {#win-accessibletitle}

一个 `string` 属性，用于定义仅提供给辅助功能工具（例如屏幕阅读器）的替代标题。此字符串不会直接显示给用户。

#### `win.snapped` _Windows_ _Readonly_ {#win-snapped-windows-readonly}

一个 `boolean` 属性，用于指示窗口是否通过 [Snap.](https://support.microsoft.com/en-us/windows/snap-your-windows-885a9b1e-a983-a3b1-16cd-c531795e6241) 进行排列。

### 实例方法 {#instance-methods}

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

> [!NOTE]
> 某些方法仅在特定操作系统上可用，并会相应标注。

#### `win.destroy()` {#win-destroy}

强制关闭窗口。不会为网页触发 `unload` 和 `beforeunload` 事件，也不会为此窗口触发 `close` 事件，但保证会触发 `closed` 事件。

#### `win.close()` {#win-close}

尝试关闭窗口。其效果与用户手动点击窗口的关闭按钮相同。不过，网页可能会取消关闭操作。请参阅 [close 事件](#event-close)。

#### `win.focus()` {#win-focus}

聚焦窗口。

在 Wayland（Linux）上，如果窗口或应用尚未聚焦，桌面环境可能会显示通知或闪烁应用图标。

#### `win.blur()` {#win-blur}

移除窗口的焦点。

Wayland（Linux）不支持。

#### `win.isFocused()` {#win-isfocused}

返回 `boolean` - 窗口是否已聚焦。

#### `win.isDestroyed()` {#win-isdestroyed}

返回 `boolean` - 窗口是否已销毁。

#### `win.show()` {#win-show}

显示窗口并使其获得焦点。

#### `win.showInactive()` {#win-showinactive}

显示窗口，但不使其获得焦点。

Wayland（Linux）不支持。

#### `win.hide()` {#win-hide}

隐藏窗口。

#### `win.isVisible()` {#win-isvisible}

返回 `boolean` - 窗口是否在应用的前台对用户可见。

#### `win.isModal()` {#win-ismodal}

返回 `boolean` - 当前窗口是否为模态窗口。

#### `win.maximize()` {#win-maximize}

最大化窗口。如果窗口尚未显示，此操作还会显示（但不聚焦）该窗口。

#### `win.unmaximize()` {#win-unmaximize}

取消最大化窗口。

#### `win.isMaximized()` {#win-ismaximized}

返回 `boolean` - 窗口是否已最大化。

#### `win.minimize()` {#win-minimize}

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

#### `win.restore()` {#win-restore}

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

#### `win.isMinimized()` {#win-isminimized}

返回 `boolean` - 窗口是否已最小化。

#### `win.setFullScreen(flag)` {#win-setfullscreen-flag}

* `flag` boolean

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

> [!NOTE]
> 在 macOS 上，全屏转换是异步进行的。如果后续操作依赖于全屏状态，请使用 ['enter-full-screen'](browser-window.md#event-enter-full-screen) 或 ['leave-full-screen'](browser-window.md#event-leave-full-screen) 事件。

#### `win.isFullScreen()` {#win-isfullscreen}

返回 `boolean` - 窗口是否处于全屏模式。

> [!NOTE]
> 在 macOS 上，全屏转换是异步进行的。查询 BrowserWindow 的全屏状态时，应确保已触发 ['enter-full-screen'](browser-window.md#event-enter-full-screen) 或 ['leave-full-screen'](browser-window.md#event-leave-full-screen) 事件。

#### `win.setSimpleFullScreen(flag)` _macOS_ {#win-setsimplefullscreen-flag-macos}

* `flag` boolean

进入或退出简单全屏模式。

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

#### `win.isSimpleFullScreen()` _macOS_ {#win-issimplefullscreen-macos}

返回 `boolean` - 窗口是否处于简单（Lion 之前）全屏模式。

#### `win.isNormal()` {#win-isnormal}

返回 `boolean` - 窗口是否处于正常状态（未最大化、未最小化、未处于全屏模式）。



#### `win.setAspectRatio(aspectRatio[, extraSize])` {#win-setaspectratio-aspectratio-extrasize}

* `aspectRatio` Float - 用于保持内容视图某一部分的宽高比。
* `extraSize` [Size](structures/size.md)（可选）_macOS_ - 在保持宽高比时不应包含的额外尺寸。

这将使窗口保持一个宽高比。额外尺寸允许开发者拥有以像素为单位的、不包含在宽高比计算中的空间。此 API 已经考虑了窗口大小与其内容大小之间的差异。

考虑一个带有高清视频播放器及相关控件的普通窗口。也许左边缘有 15 像素的控件，右边缘有 25 像素的控件，播放器下方有 50 像素的控件。为了在播放器本身内保持 16:9 宽高比（HD @1920x1080 的标准宽高比），我们会使用参数 16/9 和 \{ width: 40, height: 50 \} 调用此函数。第二个参数不关心额外宽度和高度在内容视图中的位置——只要求它们存在。将整体内容视图中所有额外的宽度和高度区域相加。

当通过 `win.setSize` 等 API 以编程方式调整窗口大小时，宽高比不会被遵守。

要重置宽高比，请将 `aspectRatio` 值设为 0：`win.setAspectRatio(0)`。

#### `win.setBackgroundColor(backgroundColor)` {#win-setbackgroundcolor-backgroundcolor}

* `backgroundColor` string - 十六进制、RGB、RGBA、HSL、HSLA 或命名 CSS 颜色格式的颜色。对于十六进制类型，Alpha 通道是可选的。

有效的 `backgroundColor` 值示例：

* 十六进制
  * #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](https://source.chromium.org/chromium/chromium/src/+/main:third_party/skia/src/utils/SkParseColor.cpp;l=11-152;drc=eea4bf52cb0d55e2a39c828b017c80a5ee054148)
  * 类似于 CSS Color Module Level 3 关键字，但区分大小写。
    * 例如 `blueviolet` 或 `red`

设置窗口的背景颜色。请参阅 [设置 `backgroundColor`](#setting-the-backgroundcolor-property)。

#### `win.previewFile(path[, displayName])` _macOS_ {#win-previewfile-path-displayname-macos}

* `path` string - 使用 QuickLook 预览的文件绝对路径。这一点很重要，因为 Quick Look 会使用路径中的文件名和文件扩展名来确定要打开的文件的内容类型。
* `displayName` string（可选） - 在 Quick Look 模态视图中显示的文件名称。这纯粹是视觉上的，不会影响文件的内容类型。默认为 `path`。

使用 [Quick Look][quick-look] 预览指定路径的文件。

#### `win.closeFilePreview()` _macOS_ {#win-closefilepreview-macos}

关闭当前打开的 [Quick Look][quick-look] 面板。

#### `win.setBounds(bounds[, animate])` {#win-setbounds-bounds-animate}

* `bounds` Partial\<[Rectangle](structures/rectangle.md)\>
* `animate` boolean（可选）_macOS_

调整并移动窗口到提供的边界。未提供的任何属性都将默认使用其当前值。

在 Wayland（Linux）上，具有与 `setSize` 和 `setPosition` 相同的限制。

```js
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())

[!NOTE] 在 macOS 上，y 坐标值不能小于 Tray 高度。托盘高度随时间变化，并取决于操作系统，但介于 20-40px 之间。传入低于托盘高度的值会导致窗口紧贴托盘。

`win.getBounds()`¶

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

[!NOTE] 在 macOS 上，返回的 y 坐标值至少为 Tray 高度。例如，在托盘高度为 38 的情况下调用 win.setBounds({ x: 25, y: 20, width: 800, height: 600 })，意味着 win.getBounds() 将返回 { x: 25, y: 38, width: 800, height: 600 }。

[!NOTE] 在 Wayland 上，此方法将返回 { x: 0, y: 0, ... }，因为禁止内省或以编程方式更改全局窗口坐标。

`win.getBackgroundColor()`¶

返回 string - 以十六进制（#RRGGBB）格式获取窗口的背景颜色。

请参阅设置 backgroundColor。

[!NOTE] Alpha 值不会与红色、绿色和蓝色值一起返回。

`win.setContentBounds(bounds[, animate])`¶

bounds Rectangle
animate boolean（可选）macOS

调整并移动窗口的客户区（例如网页）到提供的边界。

在 Wayland（Linux）上，具有与 setContentSize 和 setPosition 相同的限制。

`win.getContentBounds()`¶

返回 Rectangle - 以 Object 形式表示的窗口客户区的 bounds。

`win.getNormalBounds()`¶

返回 Rectangle - 包含正常状态下的窗口边界

[!NOTE] 无论窗口当前处于何种状态（最大化、最小化或全屏），此函数始终返回窗口在正常状态下的位置和大小。在正常状态下，getBounds 和 getNormalBounds 返回相同的 Rectangle。

`win.setEnabled(enable)`¶

enable boolean

禁用或启用窗口。

`win.isEnabled()`¶

返回 boolean - 窗口是否已启用。

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

width Integer
height Integer
animate boolean（可选）macOS

将窗口调整为 width 和 height。如果 width 或 height 低于任何已设置的最小尺寸约束，窗口将调整为最小尺寸。

在 Wayland（Linux）上可能无法正常工作，因为某些窗口管理器会限制程序化调整窗口大小。

`win.getSize()`¶

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

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

width Integer
height Integer
animate boolean（可选） macOS

将窗口的客户区（例如网页）调整为 width 和 height。

在 Wayland（Linux）上可能无法正常工作，因为某些窗口管理器会限制程序化调整窗口大小。

`win.getContentSize()`¶

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

`win.setMinimumSize(width, height)`¶

width Integer
height Integer

将窗口的最小尺寸设置为 width 和 height。

`win.getMinimumSize()`¶

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

`win.setMaximumSize(width, height)`¶

width Integer
height 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 boolean
level 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 docs。
relativeLevel Integer（可选） macOS - 相对于给定 level 要为此窗口设置的更高层数。默认值为 0。请注意，Apple 不建议将层级设置为比 screen-saver 高 1 层以上。

设置窗口是否应始终显示在其他窗口之上。设置后，窗口仍然是普通窗口，而不是无法获得焦点的工具箱窗口。

在 Wayland（Linux）上不受支持。

`win.isAlwaysOnTop()`¶

返回 boolean - 窗口是否始终位于其他窗口之上。

在 Wayland（Linux）上不受支持。

`win.moveAbove(mediaSourceId)`¶

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

在 z 顺序意义上，将窗口移动到源窗口之上。如果 mediaSourceId 不是窗口类型，或者窗口不存在，则此方法会抛出错误。

`win.moveTop()`¶

无论焦点如何，都将窗口移动到顶部（z 顺序）。

在 Wayland（Linux）上不受支持。

`win.center()`¶

将窗口移动到屏幕中央。

在 Wayland（Linux）上不受支持。

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

x Integer
y Integer
animate boolean（可选） macOS

将窗口移动到 x 和 y。

在 Wayland（Linux）上不受支持。

`win.getPosition()`¶

返回 Integer[] - 包含窗口当前位置。

[!NOTE] 在 Wayland 上，此方法将返回 [0, 0]，因为禁止内省或程序化更改全局窗口坐标。

`win.setTitle(title)`¶

title string

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

`win.getTitle()`¶

返回 string - 原生窗口的标题。

[!NOTE] 网页的标题可能与原生窗口的标题不同。

`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)`¶

rect Rectangle（可选）- 要捕获的边界
opts Object（可选）
stayHidden boolean（可选）- 保持页面隐藏而不是可见。默认值为 false。
stayAwake boolean（可选）- 保持系统唤醒而不是允许其睡眠。默认值为 false。

返回 Promise<NativeImage> - 解析为 NativeImage

捕获 rect 内页面的快照。省略 rect 将捕获整个可见页面。如果页面不可见，rect 可能为空。当页面的浏览器窗口隐藏且捕获器计数不为零时，页面被视为可见。如果你希望页面保持隐藏，应确保将 stayHidden 设置为 true。图像具有页面的设备缩放因子（对于离屏渲染，为 webPreferences.offscreen.deviceScaleFactor），因此 image.getSize() 以 DIP 为单位，image.toBitmap() 包含全分辨率像素。

`win.loadURL(url[, options])`¶

url string
options Object（可选）
httpReferrer (string | Referrer)（可选）- HTTP Referrer URL。
userAgent string（可选）- 发起请求的用户代理。
extraHeaders string（可选）- 以 "\n" 分隔的额外请求头
postData (UploadRawData | UploadFile)[]（可选）
baseURLForDataURL string（可选）- data URL 要加载的文件的基 URL（带尾部路径分隔符）。仅当指定的 url 是 data URL 且需要加载其他文件时才需要此项。

返回 Promise<void> - 当页面完成加载时，该 promise 将解析（参见 did-finish-load），如果页面加载失败，则拒绝（参见 did-fail-load）。已附加一个 noop 拒绝处理程序，以避免未处理的拒绝错误。如果现有页面有 beforeUnload 处理程序，除非处理了 will-prevent-unload，否则将调用 did-fail-load。

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

url 可以是远程地址（例如 http://），也可以是使用 file:// 协议指向本地 HTML 文件的路径。

为确保文件 URL 格式正确，建议使用 Node 的 url.format 方法：

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

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

win.loadURL(url)

你可以通过以下方式，使用带有 URL 编码数据的 POST 请求加载 URL：

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>（可选）- 传递给 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 - 进度条的模式。可以是 none、normal、indeterminate、error 或 paused。

设置进度条中的进度值。有效范围是 [0, 1.0]。

当 progress < 0 时移除进度条；当 progress > 1 时切换为 indeterminate 模式。

在 Windows 上，可以传递一个模式。可接受的值为 none、normal、 indeterminate、error 和 paused。如果调用 setProgressBar 时未设置模式（但值在有效范围内），则默认使用 normal。

在 Linux 上，进度条会显示在支持 LauncherEntry D-Bus API 的 dock 和任务栏上。它与应用程序的 .desktop 文件相关联，因此 app.setDesktopName 必须与应用程序实际 .desktop 文件的名称匹配。不支持 indeterminate 模式。

`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)`¶

opacity number - 介于 0.0（完全透明）和 1.0（完全不透明）之间

设置窗口的不透明度。超出范围的数值会被限制在 [0, 1] 范围内。

`win.getOpacity()`¶

返回 number - 介于 0.0（完全透明）和 1.0（完全不透明）之间。

`win.setShape(rects)` Windows Linux Experimental¶

rects Rectangle[] - 为窗口设置形状。传递空列表会将窗口恢复为矩形。

设置窗口形状会确定窗口内系统允许绘制和用户交互的区域。在给定区域之外，不会绘制任何像素，也不会注册鼠标事件。区域之外的鼠标事件不会被该窗口接收，而是会穿透到窗口后面的内容。

`win.setThumbarButtons(buttons)` Windows¶

buttons ThumbarButton[]

返回 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¶

region Rectangle - 窗口的区域

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

`win.setThumbnailToolTip(toolTip)` Windows¶

toolTip string

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

`win.setAppDetails(options)` Windows¶

options Object
appId string（可选）- 窗口的 App User Model ID。必须设置它，否则其他选项将不生效。
appIconPath string（可选）- 窗口的 Relaunch Icon。
appIconIndex Integer（可选）- appIconPath 中图标的索引。未设置 appIconPath 时忽略。默认值为 0。
relaunchCommand string（可选）- 窗口的 Relaunch Command。
relaunchDisplayName string（可选）- 窗口的 Relaunch Display Name。

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

[!NOTE] relaunchCommand 和 relaunchDisplayName 必须始终一起设置。如果其中一个属性未设置，则两者都不会生效。

`win.setAccentColor(accentColor)` Windows¶

accentColor boolean | string | null - 窗口的强调色。默认情况下，遵循系统设置中的用户偏好。要重置为系统默认值，请传递 null。

设置系统强调色和活动窗口边框的高亮。

accentColor 参数接受以下值：

颜色字符串 - 与 true 类似，但使用标准 CSS 颜色格式（Hex、RGB、RGBA、HSL、HSLA 或命名颜色）设置自定义强调色。RGBA/HSLA 格式中的 Alpha 值将被忽略，颜色被视为完全不透明。
true - 无论系统 Settings. 中是否为窗口启用强调色，都使用系统强调色启用窗口的强调色高亮。
false - 无论系统设置中当前是否为窗口启用强调色，都禁用窗口的强调色高亮。
null - 将窗口强调色行为重置为遵循系统设置中设置的行为。

示例：

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)')

// Enable accent color, using the color specified in System Settings.
win.setAccentColor(true)

// Disable accent color.
win.setAccentColor(false)

// Reset window accent color behavior to follow behavior set in System Settings.
win.setAccentColor(null)

`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. 排列。

窗口可通过将鼠标悬停在窗口最大化按钮上时显示的按钮进行停靠，或将其拖到屏幕边缘进行停靠。

`win.setVisibleOnAllWorkspaces(visible[, options])` macOS Linux¶

visible boolean
options Object（可选）
visibleOnFullScreen boolean（可选）macOS - 设置窗口是否应显示在全屏窗口之上。
skipTransformProcessType boolean（可选）macOS - 调用 setVisibleOnAllWorkspaces 默认会在 UIElementApplication 和 ForegroundApplication 之间转换进程类型，以确保正确行为。但是，每次调用时都会短暂隐藏窗口和 Dock。如果你的窗口已经是 UIElementApplication 类型，可以通过向 skipTransformProcessType 传递 true 来绕过此转换。

设置窗口是否应在所有工作区上可见。

[!NOTE] 此 API 在 Windows 上不起作用。

`win.isVisibleOnAllWorkspaces()` macOS Linux¶

返回 boolean - 窗口是否在所有工作区上可见。

[!NOTE] 此 API 在 Windows 上始终返回 false。

`win.setIgnoreMouseEvents(ignore[, options])`¶

ignore boolean
options Object (可选)
forward boolean (可选) macOS Windows - 如果为 true，则将鼠标移动消息转发给 Chromium，从而启用诸如 mouseleave 之类的鼠标相关事件。仅在 ignore 为 true 时使用。如果 ignore 为 false，则无论此值如何，始终禁用转发。

使窗口忽略所有鼠标事件。

此窗口中发生的所有鼠标事件都将传递给此窗口下方的窗口，但如果此窗口具有焦点，它仍将接收键盘事件。

`win.setContentProtection(enable)` macOS Windows¶

enable boolean

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

在 Windows 上，它使用 WDA_EXCLUDEFROMCAPTURE 调用 SetWindowDisplayAffinity。对于 Windows 10 版本 2004 及更高版本，窗口将完全从捕获中移除；旧版 Windows 的行为等同于应用了 WDA_MONITOR，会捕获一个黑色窗口。

在 macOS 上，它将 NSWindow 的 sharingType 设置为 NSWindowSharingNone。遗憾的是，由于 macOS 中一项有意的更改，使用 ScreenCaptureKit 的新版 Mac 应用即使调用了 win.setContentProtection(true) 也仍会捕获你的窗口。参见此处。

`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 文档。
options Object (可选)
animationDuration number (可选) - 如果大于零，则对 vibrancy 效果的更改将在给定的持续时间（以毫秒为单位）内进行动画过渡。

为浏览器窗口添加 vibrancy 效果。传入 null 或空字符串将移除窗口上的 vibrancy 效果。animationDuration 参数仅对 vibrancy 效果的淡入或淡出进行动画过渡。不支持在不同类型的 vibrancy 之间进行动画过渡。

`win.setBackgroundMaterial(material)` Windows¶

material string
auto - 让桌面窗口管理器 (DWM) 自动决定此窗口的系统绘制背景材料。这是默认值。
none - 不绘制任何系统背景。
mica - 绘制对应于长期存在窗口的背景材料效果。
acrylic - 绘制对应于瞬态窗口的背景材料效果。
tabbed - 绘制对应于带有标签式标题栏窗口的背景材料效果。

此方法设置浏览器窗口的系统绘制背景材料，包括非客户区后面的背景。

有关更多详细信息，请参阅 Windows 文档。

[!NOTE] 此方法仅在 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 会清除触摸栏。此方法仅在机器具有触摸栏时才会生效。

[!NOTE] TouchBar API 目前是实验性的，可能会在未来的 Electron 版本中更改或移除。

`win.setBrowserView(browserView)` 实验性已弃用¶

browserView BrowserView | null - 将 browserView 附加到 win。如果已附加其他 BrowserView，它们将从此窗口中移除。

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.getBrowserView()` 实验性已弃用¶

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

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.addBrowserView(browserView)` 实验性已弃用¶

browserView BrowserView

用于替代 setBrowserView 的 API，支持处理多个浏览器视图。

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.removeBrowserView(browserView)` 实验性已弃用¶

browserView BrowserView

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.setTopBrowserView(browserView)` 实验性已弃用¶

browserView BrowserView

将 browserView 提升到附加到 win 的其他 BrowserView 之上。如果 browserView 未附加到 win，则抛出错误。

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.getBrowserViews()` 实验性已弃用¶

返回 BrowserView[] - 一个按 z 索引排序的数组，包含所有通过 addBrowserView 或 setBrowserView 附加的 BrowserView。最顶层的 BrowserView 是数组的最后一个元素。

[!WARNING] BrowserView 类已弃用，并由新的 WebContentsView 类取代。

`win.setTitleBarOverlay(options)` Windows Linux¶

options Object
color String（可选）- 启用时，窗口控件覆盖层的 CSS 颜色。
symbolColor String（可选）- 启用时，窗口控件覆盖层上符号的 CSS 颜色。
height Integer（可选）- 标题栏和窗口控件覆盖层的高度，以像素为单位。

在已启用窗口控件覆盖层的窗口上，此方法会更新标题栏覆盖层的样式。

在 Linux 上，如果未显式设置 symbolColor，则会自动计算其与 color 之间的最小可访问对比度。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron

BrowserWindow¶

窗口自定义¶

优雅地显示窗口¶

使用 ready-to-show 事件¶

设置 backgroundColor 属性¶

父窗口和子窗口¶

模态窗口¶

页面可见性¶

平台注意事项¶

类：BrowserWindow 继承自 BaseWindow¶

new BrowserWindow([options])¶

实例事件¶

事件：'page-title-updated'¶

事件：'close'¶

事件：'closed'¶

事件：'query-session-end' Windows¶

事件：'session-end' Windows¶

事件：'unresponsive'¶

事件：'responsive'¶

事件：'blur'¶

事件：'focus'¶

事件：'show'¶

事件：'hide'¶

事件：'ready-to-show'¶

事件：'maximize'¶

事件：'unmaximize'¶

事件：'minimize'¶

事件：'restore'¶

事件：'will-resize' macOS Windows¶

事件：'resize'¶

事件：'resized' macOS Windows¶

事件：'will-move' macOS Windows¶

事件：'move'¶

事件：'moved' macOS Windows¶

事件：'enter-full-screen'¶

事件：'leave-full-screen'¶

事件：'enter-html-full-screen'¶

事件：'leave-html-full-screen'¶

事件：'always-on-top-changed'¶

事件：'app-command' Windows Linux¶

事件：'swipe' macOS¶

事件：'rotate-gesture' macOS¶

事件：'sheet-begin' macOS¶

事件：'sheet-end' macOS¶

事件：'new-window-for-tab' macOS¶

事件：'system-context-menu' Windows Linux¶

静态方法¶

BrowserWindow.getAllWindows()¶

BrowserWindow.getFocusedWindow()¶

BrowserWindow.fromWebContents(webContents)¶

BrowserWindow.fromBrowserView(browserView) 已弃用¶

BrowserWindow.fromId(id)¶

实例属性¶

win.webContents 只读¶

win.id 只读¶

win.tabbingIdentifier macOS 只读¶

win.autoHideMenuBar Linux Windows¶

win.simpleFullScreen¶

win.fullScreen¶

win.focusable Windows macOS¶

win.visibleOnAllWorkspaces macOS Linux¶

win.shadow¶

win.menuBarVisible Windows Linux¶

win.kiosk¶

win.documentEdited macOS¶

win.representedFilename macOS¶

win.title¶

win.minimizable macOS Windows¶

win.maximizable macOS Windows¶

win.fullScreenable¶

win.resizable¶

win.closable macOS Windows¶

win.movable macOS Windows¶

win.excludedFromShownWindowsMenu macOS¶

win.getBounds()¶

win.getBackgroundColor()¶

win.setContentBounds(bounds[, animate])¶

win.getContentBounds()¶

win.getNormalBounds()¶

win.setEnabled(enable)¶

使用 `ready-to-show` 事件¶

设置 `backgroundColor` 属性¶

类：BrowserWindow 继承自 `BaseWindow`¶

`new BrowserWindow([options])`¶

`BrowserWindow.getAllWindows()`¶

`BrowserWindow.getFocusedWindow()`¶

`BrowserWindow.fromWebContents(webContents)`¶

`BrowserWindow.fromBrowserView(browserView)` 已弃用¶

`BrowserWindow.fromId(id)`¶

`win.webContents` 只读¶

`win.id` 只读¶

`win.tabbingIdentifier` macOS 只读¶

`win.autoHideMenuBar` Linux Windows¶

`win.simpleFullScreen`¶

`win.fullScreen`¶

`win.focusable` Windows macOS¶

`win.visibleOnAllWorkspaces` macOS Linux¶

`win.shadow`¶

`win.menuBarVisible` Windows Linux¶

`win.kiosk`¶

`win.documentEdited` macOS¶

`win.representedFilename` macOS¶

`win.title`¶

`win.minimizable` macOS Windows¶

`win.maximizable` macOS Windows¶

`win.fullScreenable`¶

`win.resizable`¶

`win.closable` macOS Windows¶

`win.movable` macOS Windows¶

`win.excludedFromShownWindowsMenu` macOS¶

`win.getBounds()`¶

`win.getBackgroundColor()`¶

`win.setContentBounds(bounds[, animate])`¶

`win.getContentBounds()`¶

`win.getNormalBounds()`¶

`win.setEnabled(enable)`¶

`win.isEnabled()`¶

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

`win.getSize()`¶

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

`win.getContentSize()`¶

`win.setMinimumSize(width, height)`¶

`win.getMinimumSize()`¶

`win.setMaximumSize(width, height)`¶

`win.getMaximumSize()`¶

`win.setResizable(resizable)`¶

`win.isResizable()`¶

`win.setMovable(movable)` macOS Windows¶

`win.isMovable()` macOS Windows¶

`win.setMinimizable(minimizable)` macOS Windows¶

`win.isMinimizable()` macOS Windows¶

`win.setMaximizable(maximizable)` macOS Windows¶

`win.isMaximizable()` macOS Windows¶

`win.setFullScreenable(fullscreenable)`¶

`win.isFullScreenable()`¶

`win.setClosable(closable)` macOS Windows¶

`win.isClosable()` macOS Windows¶

`win.setHiddenInMissionControl(hidden)` macOS¶

`win.isHiddenInMissionControl()` macOS¶

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

`win.isAlwaysOnTop()`¶

`win.moveAbove(mediaSourceId)`¶

`win.moveTop()`¶

`win.center()`¶

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

`win.getPosition()`¶

`win.setTitle(title)`¶

`win.getTitle()`¶

`win.setSheetOffset(offsetY[, offsetX])` macOS¶

`win.flashFrame(flag)`¶

`win.loadURL(url[, options])`¶

`win.loadFile(filePath[, options])`¶

`win.reload()`¶

`win.setMenu(menu)` Linux Windows¶

`win.removeMenu()` Linux Windows¶

`win.setProgressBar(progress[, options])`¶

`win.setOverlayIcon(overlay, description)` Windows¶

`win.invalidateShadow()` macOS¶

`win.setHasShadow(hasShadow)`¶

`win.hasShadow()`¶