BrowserWindow

创建和控制浏览器窗口。

进程: 主进程

在发出 app 模块的 ready 事件之前，此模块将无法使用。

// In the main process.
const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

// Load a remote URL
win.loadURL('https://github.com')

// Or load a local HTML file
win.loadFile('index.html')

窗口自定义

BrowserWindow 类提供了多种修改应用程序窗口外观和行为的方式。有关更多详细信息，请参阅 窗口自定义 教程。

优雅地显示窗口

当直接在窗口中加载页面时，用户可能会看到页面逐步加载，这对于原生应用程序来说不是一个好的体验。为了使窗口在没有视觉闪烁的情况下显示，针对不同的情况有两种解决方案。

使用 ready-to-show 事件

在加载页面时，如果窗口尚未显示，则当渲染进程首次渲染页面时将发出 ready-to-show 事件。在该事件之后显示窗口将不会有视觉闪烁。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
  win.show()
})

此事件通常在 did-finish-load 事件之后发出，但对于具有许多远程资源的页面，它可能在 did-finish-load 事件之前发出。

请注意，使用此事件意味着渲染器将被视为“可见”并进行绘制，即使 show 为 false。如果您使用 paintWhenInitiallyHidden: false，则此事件将永远不会触发。

设置 backgroundColor 属性

对于复杂的应用程序，ready-to-show 事件可能发出得太晚，导致应用程序感觉缓慢。在这种情况下，建议立即显示窗口，并使用接近应用程序背景的 backgroundColor。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')

即使对于使用 ready-to-show 事件的应用程序，也建议设置 backgroundColor 以使应用程序感觉更原生。

一些有效的 backgroundColor 值的示例包括

const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')

有关这些颜色类型的更多信息，请参阅 win.setBackgroundColor 中的有效选项。

父窗口和子窗口

通过使用 parent 选项，您可以创建子窗口。

const { BrowserWindow } = require('electron')

const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()

child 窗口始终显示在 top 窗口的上方。

模态窗口

模态窗口是一个禁用父窗口的子窗口。要创建模态窗口，必须同时设置 parent 和 modal 选项。

const { BrowserWindow } = require('electron')

const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

页面可见性

《页面可见性 API》的工作方式如下：

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

建议在可见性状态为 hidden 时暂停耗费大量资源的运算，以最大限度地降低功耗。

平台注意事项

• 在 macOS 上，模态窗口将显示为附加到父窗口的工作表。
• 在 macOS 上，子窗口在父窗口移动时将保持相对于父窗口的位置，而在 Windows 和 Linux 上，子窗口将不会移动。
• 在 Linux 上，模态窗口的类型将更改为 dialog。
• 在 Linux 上，许多桌面环境不支持隐藏模态窗口。

类: BrowserWindow 继承自 BaseWindow

创建和控制浏览器窗口。

进程: 主进程

BrowserWindow 是一个 EventEmitter。

它使用通过 options 设置的本机属性创建一个新的 BrowserWindow。

警告

Electron 的内置类不能在用户代码中被继承。有关更多信息，请参阅 FAQ。

new BrowserWindow([options])

• options BrowserWindowConstructorOptions (可选)
  • webPreferences WebPreferences (可选) - 网页功能的设置。
    • devTools boolean (可选) - 是否启用开发者工具。如果设置为 false，则无法使用 BrowserWindow.webContents.openDevTools() 打开开发者工具。默认为 true。
    • nodeIntegration boolean (可选) - 是否启用 Node 集成。默认为 false。
    • nodeIntegrationInWorker 布尔值 (可选) - 是否在 Web Worker 中启用 Node 集成。默认值为 false。有关更多信息，请参阅 多线程。
    • nodeIntegrationInSubFrames boolean (可选) - 一个实验性选项，用于在子框架（如 iframe 和子窗口）中启用 Node.js 支持。您的所有预加载脚本都将为每个 iframe 加载，您可以使用 process.isMainFrame 来确定您是否在主框架中。
    • preload 字符串 (可选) - 指定在页面中运行其他脚本之前加载的脚本。无论是否启用 Node 集成，此脚本始终可以访问 Node API。该值应该是脚本的绝对文件路径。当 Node 集成关闭时，预加载脚本可以将 Node 全局符号重新引入全局作用域。请参阅示例 此处。
    • sandbox 布尔值 (可选) - 如果设置为 true，这将对与窗口关联的渲染器进行沙箱化处理，使其与 Chromium OS 级别的沙箱兼容，并禁用 Node.js 引擎。这与 nodeIntegration 选项不同，并且预加载脚本可用的 API 更加有限。Electron 20 之后的默认值为 true。当 nodeIntegration 设置为 true 时，沙箱将自动禁用。请阅读更多关于此选项的信息 此处。
    • session Session (可选) - 设置页面使用的会话。您可以选择使用 partition 选项代替直接传递 Session 对象，该选项接受一个分区字符串。当同时提供 session 和 partition 时，将优先使用 session。默认值为默认会话。
    • partition string (可选) - 根据会话的分区字符串设置页面使用的会话。如果 partition 以 persist: 开头，则页面将使用该应用中具有相同 partition 的所有页面可用的持久会话。如果不存在 persist: 前缀，则页面将使用内存中的会话。通过分配相同的 partition，多个页面可以共享同一个会话。默认是默认会话。
    • zoomFactor number (可选) - 页面的默认缩放系数，3.0 表示 300%。默认为 1.0。
    • javascript boolean (可选) - 启用 JavaScript 支持。默认为 true。
    • webSecurity boolean (可选) - 当设置为 false 时，它将禁用同源策略（通常用于人们测试网站），并将 allowRunningInsecureContent 设置为 true（如果用户尚未设置此选项）。默认为 true。
    • allowRunningInsecureContent boolean (可选) - 允许 https 页面运行来自 http URL 的 JavaScript、CSS 或插件。默认为 false。
    • images boolean (可选) - 启用图像支持。默认为 true。
    • imageAnimationPolicy string (可选) - 指定如何运行图像动画（例如 GIF）。可以是 animate、animateOnce 或 noAnimation。默认为 animate。
    • textAreasAreResizable boolean (可选) - 使 TextArea 元素可调整大小。默认为 true。
    • webgl boolean (可选) - 启用 WebGL 支持。默认为 true。
    • plugins boolean (可选) - 是否启用插件。默认为 false。
    • experimentalFeatures boolean (可选) - 启用 Chromium 的实验性功能。默认为 false。
    • scrollBounce boolean (可选) macOS - 在 macOS 上启用滚动反弹（弹性）效果。默认为 false。
    • enableBlinkFeatures 字符串 (可选) - 一个由 , 分隔的特性字符串列表，例如 CSSVariables,KeyboardEventKey 以启用。完整的支持特性字符串列表可以在 RuntimeEnabledFeatures.json5 文件中找到。
    • disableBlinkFeatures 字符串 (可选) - 一个由 , 分隔的特性字符串列表，例如 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。
      • math string (可选) - 默认为 Latin Modern Math。
    • defaultFontSize Integer (可选) - 默认为 16。
    • defaultMonospaceFontSize Integer (可选) - 默认为 13。
    • minimumFontSize Integer (可选) - 默认为 0。
    • defaultEncoding string (可选) - 默认为 ISO-8859-1。
    • backgroundThrottling 布尔值 (可选) - 页面变为后台时是否限制动画和计时器。这也会影响 页面可见性 API。当至少一个 webContents 显示在单个 browserWindow 中时，如果禁用了 backgroundThrottling，则将为整个窗口绘制和交换帧，以及显示的其他 webContents。默认值为 true。
    • offscreen 对象 | 布尔值 (可选) - 是否为浏览器窗口启用离屏渲染。默认值为 false。有关更多详细信息，请参阅 离屏渲染教程。
      • useSharedTexture 布尔值 (可选) 实验性 - 是否使用 GPU 共享纹理进行加速的绘制事件。默认值为 false。有关更多详细信息，请参阅 离屏渲染教程。
      • sharedTexturePixelFormat 字符串 (可选) 实验性 - 共享纹理请求的输出格式。默认值为 argb。名称源自 Chromium media::VideoPixelFormat 枚举后缀，并且仅支持其中一部分。纹理的实际输出像素格式和颜色空间应参考 paint 事件中的 OffscreenSharedTexture 对象。
        • argb - 请求的输出纹理格式为 8 位 unorm RGBA，具有 SRGB SDR 颜色空间。
        • rgbaf16 - 请求的输出纹理格式为 16 位浮点 RGBA，具有 scRGB HDR 颜色空间。
    • contextIsolation 布尔值 (可选) - 是否在单独的 JavaScript 上下文中运行 Electron API 和指定的 preload 脚本。默认为 true。preload 脚本运行的上下文只能访问其自己的专用 document 和 window 全局变量，以及其自己的 JavaScript 内置对象 (Array、Object、JSON 等)，这些都对加载的内容不可见。Electron API 仅在 preload 脚本中可用，而不是加载的页面中。当加载潜在的不受信任的远程内容时，应使用此选项，以确保加载的内容无法篡改 preload 脚本和正在使用的任何 Electron API。此选项使用与 Chrome 内容脚本 相同的方法。您可以在控制台选项卡顶部的组合框中选择“Electron Isolated Context”条目，在开发工具中访问此上下文。
    • webviewTag 布尔值 (可选) - 是否启用 <webview> 标签。默认值为 false。注意： 为 <webview> 配置的 preload 脚本在执行时将启用 Node 集成，因此您应确保远程/不受信任的内容无法使用可能具有恶意 preload 脚本创建 <webview> 标签。您可以使用 webContents 上的 will-attach-webview 事件来剥离 preload 脚本，并验证或更改 <webview> 的初始设置。
    • additionalArguments string[] (可选) - 将附加到此应用程序的渲染器进程的 process.argv 的字符串列表。用于将少量数据传递给渲染器进程 preload 脚本。
    • 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 布尔值 (可选) - 是否启用 WebSQL api。默认值为 true。
    • v8CacheOptions string (可选) - 强制执行 blink 使用的 v8 代码缓存策略。可接受的值包括
      • none - 禁用代码缓存
      • code - 基于启发式代码缓存
      • bypassHeatCheck - 绕过代码缓存启发式但具有惰性编译
      • bypassHeatCheckAndEagerCompile - 与上面相同，除了编译是急切的。默认策略是 code。
    • enablePreferredSizeMode boolean (可选) - 是否启用首选尺寸模式。首选尺寸是容纳文档布局所需的最小尺寸，无需滚动。启用此选项将导致当首选尺寸发生变化时，在 WebContents 上发出 preferred-size-changed 事件。默认值为 false。
    • transparent 布尔值 (可选) - 是否为访客页面启用背景透明度。默认值为 true。注意： 访客页面的文本和背景颜色源自其根元素的 颜色方案。当启用透明度时，文本颜色仍然会相应更改，但背景将保持透明。
    • enableDeprecatedPaste 布尔值 (可选) 已弃用 - 是否启用 paste execCommand。默认值为 false。
  • paintWhenInitiallyHidden 布尔值 (可选) - 在 show 为 false 且刚创建时，渲染器是否应处于活动状态。为了使 document.visibilityState 在首次使用 show: false 加载时正确工作，您应该将其设置为 false。将其设置为 false 将导致 ready-to-show 事件不会触发。默认值为 true。

实例事件

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

注意

某些事件仅在特定操作系统上可用，并已相应标记。

事件: 'page-title-updated'

返回

• event Event
• title string
• explicitSet boolean

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

事件: 'close'

返回

• event Event

当窗口即将关闭时发出。它在 DOM 的 beforeunload 和 unload 事件之前发出。调用 event.preventDefault() 将取消关闭。

通常，您希望使用 beforeunload 处理程序来确定窗口是否应关闭，这也会在重新加载窗口时被调用。在 Electron 中，返回任何非 undefined 的值都会取消关闭。例如

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

  // Unlike usual browsers that a message box will be prompted to users, returning
  // a non-void value will silently cancel the close.
  // It is recommended to use the dialog API to let the user confirm closing the
  // application.
  e.returnValue = false
}

注意

window.onbeforeunload = handler 和 window.addEventListener('beforeunload', handler) 的行为之间存在细微的差别。建议始终显式设置 event.returnValue，而不是仅返回值，因为后者在 Electron 中更一致地工作。

事件: 'closed'

当窗口关闭时发出。收到此事件后，您应该删除对窗口的引用并避免再使用它。

事件: 'query-session-end' Windows

返回

• event WindowSessionEndEvent

当由于关机、机器重启或用户注销而即将结束会话时发出。调用 event.preventDefault() 可以延迟系统关机，但通常最好尊重用户结束会话的选择。但是，您可能会选择使用它，如果结束会话会使用户面临数据丢失的风险。

事件: 'session-end' Windows

返回

• event WindowSessionEndEvent

当由于关机、机器重启或用户注销而即将结束会话时发出。一旦此事件触发，就无法阻止会话结束。

事件: 'unresponsive'

当网页无响应时发出。

事件: 'responsive'

当无响应的网页再次响应时发出。

事件: 'blur'

当窗口失去焦点时发出。

事件: 'focus'

当窗口获得焦点时发出。

事件: 'show'

当窗口显示时发出。

事件: 'hide'

当窗口隐藏时发出。

事件: 'ready-to-show'

当网页已渲染（未显示时）并且可以显示窗口而没有视觉闪烁时发出。

请注意，使用此事件意味着渲染器将被视为“可见”并进行绘制，即使 show 为 false。如果您使用 paintWhenInitiallyHidden: false，则此事件将永远不会触发。

事件: 'maximize'

当窗口最大化时发出。

事件: 'unmaximize'

当窗口退出最大化状态时发出。

事件: 'minimize'

当窗口最小化时发出。

事件: 'restore'

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

事件: 'will-resize' macOS Windows

返回

• event Event
• newBounds Rectangle - 窗口正在调整为的大小。
• details Object
  • 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 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 布尔值

在窗口设置为或取消设置为始终位于其他窗口之上时发出。

事件: 'app-command' Windows Linux

返回

• event Event
• command 字符串

在调用 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 字符串

在三指滑动时发出。可能的方向是 up（向上）、right（向右）、down（向下）、left（向左）。

此事件的基础方法构建为处理旧版 macOS 风格的触控板滑动，其中屏幕上的内容不会随滑动移动。大多数 macOS 触控板未配置为允许这种类型的滑动，因此为了正确发出此事件，必须将“系统偏好设置 > 触控板 > 更多手势”中的“用两或三根手指滑动”首选项设置为“用两或三根手指滑动”。

事件: 'rotate-gesture' macOS

返回

• event Event
• rotation 浮点数

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

事件: 'sheet-begin' macOS

在窗口打开床单时发出。

事件: 'sheet-end' macOS

在窗口关闭床单时发出。

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

在单击本机的新选项卡按钮时发出。

事件: 'system-context-menu' Windows Linux

返回

• 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

注意

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

返回 BrowserWindow | null - 拥有给定 browserView 的窗口。如果给定的视图未附加到任何窗口，则返回 null。

BrowserWindow.fromId(id)

• id Integer

返回 BrowserWindow | null - 具有给定 id 的窗口。

实例属性

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

const { BrowserWindow } = require('electron')
// In this example `win` is our instance
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

win.webContents 只读

此窗口拥有的 WebContents 对象。所有网页相关事件和操作都将通过它完成。

请参阅 webContents 文档，了解其方法和事件。

win.id 只读

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

win.tabbingIdentifier macOS 只读

一个 string 属性（可选），等于传递给 BrowserWindow 构造函数或未设置的 tabbingIdentifier。

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 win = new BrowserWindow({ height: 600, width: 600 })

const template = [
  {
    role: 'windowmenu'
  }
]

win.excludedFromShownWindowsMenu = true

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

win.accessibleTitle

一个 string 属性，用于为屏幕阅读器等辅助工具定义一个替代标题。此字符串对用户不可见。

win.snapped Windows 只读

一个 boolean 属性，指示窗口是否通过 “窗口捕捉” 功能排列。

实例方法

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

注意

某些方法仅在特定操作系统上可用，并已如此标记。

win.destroy()

强制关闭窗口，网页将不会发出 unload 和 beforeunload 事件，并且此窗口也不会发出 close 事件，但它保证会发出 closed 事件。

win.close()

尝试关闭窗口。这与用户手动单击窗口的关闭按钮的效果相同。网页可能会取消关闭。请参阅 close 事件。

win.focus()

将焦点设置到窗口。

win.blur()

从窗口移除焦点。

win.isFocused()

返回 boolean - 窗口是否处于焦点状态。

win.isDestroyed()

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

win.show()

显示并聚焦到窗口。

win.showInactive()

显示窗口但不聚焦到它。

win.hide()

隐藏窗口。

win.isVisible()

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

win.isModal()

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

win.maximize()

最大化窗口。如果窗口尚未显示，这将同时显示（但不聚焦）窗口。

win.unmaximize()

取消最大化窗口。

win.isMaximized()

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

win.minimize()

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

win.restore()

将窗口从最小化状态恢复到其先前状态。

win.isMinimized()

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

win.setFullScreen(flag)

• flag boolean

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

注意

在 macOS 上，全屏过渡是异步进行的。如果进一步的操作依赖于全屏状态，请使用 'enter-full-screen' 或 'leave-full-screen' 事件。

win.isFullScreen()

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

注意

在 macOS 上，全屏过渡是异步进行的。在查询 BrowserWindow 的全屏状态时，应确保已发出 'enter-full-screen' 或 'leave-full-screen' 事件。

win.setSimpleFullScreen(flag) macOS

• flag boolean

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

简单的全屏模式模拟了 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 的宽高比（高清的标准宽高比 @1920x1080），我们将使用 16/9 和 { width: 40, height: 50 } 作为参数调用此函数。第二个参数不关心额外的宽度和高度在内容视图中的位置——只关心它们的存在。将内容视图中所有额外的宽度和高度区域相加。

当窗口使用诸如 win.setSize 之类的 API 以编程方式调整大小时，宽高比不会被尊重。

要重置宽高比，将 0 作为 aspectRatio 值传递：win.setAspectRatio(0)。

win.setBackgroundColor(backgroundColor)

• backgroundColor string - 十六进制、RGB、RGBA、HSL、HSLA 或命名的 CSS 颜色格式的颜色。十六进制类型可以选择性地包含 alpha 通道。

有效的 backgroundColor 值的示例

• Hex
  • #fff (简写 RGB)
  • #ffff (简写 ARGB)
  • #ffffff (RGB)
  • #ffffffff (ARGB)
• RGB
  • rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)
    • 例如 rgb(255, 255, 255)
• RGBA
  • rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)
    • 例如 rgba(255, 255, 255, 1.0)
• HSL
  • hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)
    • 例如 hsl(200, 20%, 50%)
• HSLA
  • hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)
    • 例如 hsla(200, 20%, 50%, 0.5)
• 颜色名称
  • 选项列在 SkParseColor.cpp 中
  • 与 CSS Color Module Level 3 关键字类似，但区分大小写。
    • 例如：blueviolet 或 red

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

win.previewFile(path[, displayName]) macOS

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

使用 Quick Look 预览给定路径下的文件。

win.closeFilePreview() macOS

关闭当前打开的 Quick Look 面板。

win.setBounds(bounds[, animate])

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

将窗口调整为提供的边界。未提供的任何属性都将默认为其当前值。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

// set all bounds properties
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// set a single bounds property
win.setBounds({ width: 100 })

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

注意

在 macOS 上，y 坐标值不能小于 托盘 的高度。托盘高度随时间变化，并且取决于操作系统，但介于 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 - 获取窗口的背景颜色，格式为十六进制 (#RRGGBB)。

请参阅 设置 backgroundColor。

注意

alpha 值不与红色、绿色和蓝色值一起返回。

win.setContentBounds(bounds[, animate])

• bounds Rectangle
• animate 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 Integer
• height Integer
• animate boolean (可选) macOS

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

win.getSize()

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

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

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

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

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 (已弃用)。默认值为 floating，当 flag 为 true 时。当 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 Integer
• y Integer
• animate boolean (可选) macOS

将窗口移动到 x 和 y。

win.getPosition()

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

win.setTitle(title)

• title string

将本机窗口的标题更改为 title。

win.getTitle()

返回 string - 本机窗口的标题。

注意

网页的标题可能与原生窗口的标题不同。

win.setSheetOffset(offsetY[, offsetX]) macOS

• offsetY Float
• offsetX Float (可选)

更改 macOS 上工作表的附着点。默认情况下，工作表附着在窗口框架下方，但您可能希望在 HTML 渲染的工具栏下方显示它们。例如

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)

win.flashFrame(flag)

历史

版本(s)	更改
None	window.flashFrame(bool) 会在 macOS 上持续闪烁 Dock 图标

• flag boolean

开始或停止闪烁窗口以吸引用户的注意力。

win.setSkipTaskbar(skip) macOS Windows

• skip boolean

使窗口不在任务栏中显示。

win.setKiosk(flag)

• flag boolean

进入或退出全屏模式。

win.isKiosk()

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

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 Integer
• callback Function
  • wParam 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 布尔值

指定窗口的文档是否已被编辑。如果设置为 true，则标题栏中的图标将变为灰色。

win.isDocumentEdited() macOS

返回 布尔值 - 窗口的文档是否已被编辑。

win.focusOnWebView()

win.blurWebView()

win.capturePage([rect, opts])

• rect 矩形 (可选) - 要捕获的边界
• opts 对象 (可选)
  • stayHidden 布尔值 (可选) - 保持页面隐藏而不是可见。默认值为 false。
  • stayAwake 布尔值 (可选) - 保持系统唤醒而不是允许其休眠。默认值为 false。

返回 Promise<NativeImage> - 解析为 NativeImage

捕获 rect 内页面的快照。省略 rect 将捕获整个可见页面。如果页面不可见，rect 可能为空。当其浏览器窗口隐藏且捕获计数非零时，页面被认为是可见的。如果您希望页面保持隐藏状态，则应确保将 stayHidden 设置为 true。

win.loadURL(url[, options])

• url string
• options Object (可选)
  • httpReferrer (字符串 | Referrer) (可选) - HTTP Referrer URL。
  • userAgent string (可选) - 发起请求的用户代理。
  • extraHeaders 字符串 (可选) - 以 "\n" 分隔的额外标头
  • postData (UploadRawData | UploadFile)[] (可选)
  • baseURLForDataURL 字符串 (可选) - 用于通过数据 URL 加载文件的基本 URL（以尾随路径分隔符结尾）。只有当指定的 url 是数据 URL 并且需要加载其他文件时，才需要此项。

返回 Promise<void> - 当页面完成加载时（请参阅 did-finish-load），promise 将解析，如果页面加载失败（请参阅 did-fail-load），则 promise 将拒绝。已经附加了一个无操作的拒绝处理程序，以避免未处理的拒绝错误。如果现有页面具有 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('https://:8000/post', {
  postData: [{
    type: 'rawData',
    bytes: Buffer.from('hello=world')
  }],
  extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})

win.loadFile(filePath[, options])

• filePath string
• options Object (可选)
  • query Record<string, string> (可选) - 传递给 url.format()。
  • search 字符串 (可选) - 传递给 url.format()。
  • hash 字符串 (可选) - 传递给 url.format()。

返回 Promise<void> - 当页面完成加载时（请参阅 did-finish-load），promise 将解析，如果页面加载失败（请参阅 did-fail-load），则 promise 将拒绝。

与 webContents.loadFile 相同，filePath 应该是相对于应用程序根目录的 HTML 文件的路径。有关更多信息，请参阅 webContents 文档。

win.reload()

与 webContents.reload 相同。

win.setMenu(menu) Linux Windows

• menu Menu | null

将 menu 设置为窗口的菜单栏。

win.removeMenu() Linux Windows

删除窗口的菜单栏。

win.setProgressBar(progress[, options])

• progress 双精度数
• options Object (可选)
  • mode 字符串 Windows - 进度条的模式。可以是 none、normal、indeterminate、error 或 paused。

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

当进度 < 0 时删除进度条；当进度 > 1 时更改为不确定模式。

在 Linux 平台上，仅支持 Unity 桌面环境，您需要在 package.json 的 desktopName 字段中指定 *.desktop 文件名。默认情况下，它将假定 {app.name}.desktop。

在 Windows 上，可以传递一种模式。允许的值是 none、normal、indeterminate、error 和 paused。如果您在有效范围内设置了值的情况下调用 setProgressBar 而没有设置模式，则假定为 normal。

win.setOverlayIcon(overlay, description) Windows

• overlay NativeImage | null - 要显示在任务栏图标右下角的图标。如果此参数为 null，则清除叠加层
• description 字符串 - 将提供给辅助功能屏幕阅读器的描述

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

win.invalidateShadow() macOS

使窗口阴影失效，以便根据当前窗口形状重新计算。

透明的 BrowserWindows 在 macOS 上有时会留下视觉伪影。当执行动画时，可以使用此方法清除这些伪影。

win.setHasShadow(hasShadow)

• hasShadow 布尔值

设置窗口是否应该有阴影。

win.hasShadow()

返回 布尔值 - 窗口是否具有阴影。

win.setOpacity(opacity) Windows macOS

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

设置窗口的不透明度。在 Linux 上，不起作用。超出范围的数字值将被限制在 [0, 1] 范围内。

win.getOpacity()

返回 数字 - 介于 0.0（完全透明）和 1.0（完全不透明）之间。在 Linux 上，始终返回 1。

win.setShape(rects) Windows Linux 实验性

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

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

win.setThumbarButtons(buttons) Windows

• buttons ThumbarButton[]

返回 布尔值 - 指示是否已成功添加按钮

使用指定的按钮集向任务栏按钮布局中的窗口缩略图图像添加缩略图工具栏。返回一个 布尔值 对象，指示是否已成功添加缩略图。

由于空间有限，缩略图工具栏中的按钮数量不应超过 7 个。设置缩略图工具栏后，由于平台限制，无法删除工具栏。但是，您可以使用空数组调用 API 来清除按钮。

buttons 是一个 Button 对象数组

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

flags 是一个可以包含以下 string 的数组

• enabled - 按钮处于活动状态，可供用户使用。
• disabled - 按钮已禁用。它存在，但具有视觉状态，表明它不会响应用户操作。
• dismissonclick - 单击按钮时，缩略图窗口将立即关闭。
• nobackground - 不绘制按钮边框，仅使用图像。
• hidden - 按钮不会显示给用户。
• noninteractive - 按钮已启用但不可交互；不绘制按下按钮状态。此值用于按钮用作通知的情况。

win.setThumbnailClip(region) Windows

• region Rectangle - 窗口区域

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

win.setThumbnailToolTip(toolTip) Windows

• toolTip string

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

win.setAppDetails(options) Windows

• options Object
  • appId string (可选) - 窗口的 App User Model ID。必须设置，否则其他选项将无效。
  • appIconPath string (可选) - 窗口的 重新启动图标。
  • appIconIndex Integer (可选) - appIconPath 中的图标索引。当未设置 appIconPath 时，将被忽略。默认值为 0。
  • relaunchCommand string (可选) - 窗口的 重新启动命令。
  • relaunchDisplayName string (可选) - 窗口的 重新启动显示名称。

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

注意

relaunchCommand 和 relaunchDisplayName 必须始终一起设置。如果其中一个属性未设置，则两者都不会被使用。

win.setAccentColor(accentColor) Windows

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

设置系统强调色和活动窗口边框的突出显示。

accentColor 参数接受以下值

• 颜色字符串 - 类似于 true，但使用标准的 CSS 颜色格式（Hex、RGB、RGBA、HSL、HSLA 或命名颜色）设置自定义强调色。RGBA/HSLA 格式中的 Alpha 值将被忽略，颜色将被视为完全不透明。
• true - 启用窗口的强调色突出显示，使用系统强调色，无论系统设置中是否为窗口启用了强调色。
• 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 - 以十六进制 RGB 格式显示的系统强调色和活动窗口边框的突出显示。

如果窗口已设置与系统强调色不同的颜色，则将返回窗口强调色。否则，将返回一个布尔值，其中 true 表示窗口使用全局系统强调色，而 false 表示窗口的强调色突出显示已禁用。

win.showDefinitionForSelection() macOS

与 webContents.showDefinitionForSelection() 相同。

win.setIcon(icon) Windows Linux

• icon NativeImage | string

更改窗口图标。

win.setWindowButtonVisibility(visible) macOS

• visible boolean

设置窗口交通信号灯按钮是否可见。

win.setAutoHideMenuBar(hide) Windows Linux

• hide boolean

设置窗口菜单栏是否应自动隐藏。设置后，菜单栏仅在用户按下单个 Alt 键时才会显示。

如果菜单栏已可见，调用 setAutoHideMenuBar(true) 不会立即隐藏它。

win.isMenuBarAutoHide() Windows Linux

返回 boolean - 菜单栏是否自动隐藏。

win.setMenuBarVisibility(visible) Windows Linux

• visible boolean

设置菜单栏是否应可见。如果菜单栏是自动隐藏的，用户仍然可以通过按下单个 Alt 键来调出菜单栏。

win.isMenuBarVisible() Windows Linux

返回 boolean - 菜单栏是否可见。

win.isSnapped() Windows

返回 boolean - 窗口是否通过 Snap 方式排列。

窗口通过将鼠标悬停在窗口最大化按钮上显示的按钮或将其拖动到屏幕边缘来 Snap。

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

• visible boolean
• options Object (可选)
  • visibleOnFullScreen boolean (可选) macOS - 设置窗口是否应在全屏窗口之上可见。
  • skipTransformProcessType boolean (可选) macOS - 调用 setVisibleOnAllWorkspaces 默认会将进程类型在 UIElementApplication 和 ForegroundApplication 之间进行转换，以确保正确的行为。但是，每次调用时都会隐藏窗口并停靠一段时间。如果您的窗口已经是 UIElementApplication 类型，则可以通过将 true 传递给 skipTransformProcessType 来绕过此转换。

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

注意

此 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 为 true 时使用。如果 ignore 为 false，则无论此值如何，都将始终禁用转发。

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

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

win.setContentProtection(enable) macOS Windows

• enable boolean

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

在 Windows 上，它调用 SetWindowDisplayAffinity 并使用 WDA_EXCLUDEFROMCAPTURE。对于 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 布尔值

控制在输入时是否隐藏光标。

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 字符串 | null - 可以是 titlebar、selection、menu、popover、sidebar、header、sheet、window、hud、fullscreen-ui、tooltip、content、under-window 或 under-page。有关更多详细信息，请参阅 macOS 文档。
• options Object (可选)
  • animationDuration 数字 (可选) - 如果大于零，则 vibrancy 的更改将在给定的持续时间内（以毫秒为单位）进行动画处理。

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

win.setBackgroundMaterial(material) Windows

• material 字符串
  • auto - 让桌面窗口管理器 (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

设置当前窗口的触控栏布局。指定 null 或 undefined 将清除触控栏。只有机器具有触控栏时，此方法才有效。

注意

TouchBar API 目前仍处于实验阶段，在未来的 Electron 版本中可能会发生更改或被移除。

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

• browserView BrowserView | null - 将 browserView 附加到 win。如果有其他 BrowserView 附加，它们将从该窗口中删除。

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

win.getBrowserView() 实验性 已弃用

返回 BrowserView | null - 附加到 win 的 BrowserView。如果没有附加，则返回 null。如果附加了多个 BrowserView，则会引发错误。

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

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

• browserView BrowserView

支持使用多个浏览器视图的 setBrowserView 的替代 API。

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

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

• browserView BrowserView

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

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

• browserView BrowserView

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

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

win.getBrowserViews() 实验性 已弃用

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

警告

BrowserView 类已弃用，并由新的 WebContentsView 类取代。

win.setTitleBarOverlay(options) Windows Linux

• options Object
  • color 字符串 (可选) - 启用后窗口控件叠加的 CSS 颜色。
  • symbolColor 字符串 (可选) - 启用后窗口控件叠加上符号的 CSS 颜色。
  • height 整数 (可选) - 标题栏和窗口控件叠加的高度（以像素为单位）。

在已经启用窗口控件叠加的窗口上，此方法更新标题栏叠加的样式。

在 Linux 上，如果未显式设置，则 symbolColor 会自动计算为与 color 具有最小可访问对比度的颜色。