Skip to main content

Window Customization窗口定制

The BrowserWindow module is the foundation of your Electron application, and it exposes many APIs that can change the look and behavior of your browser windows. BrowserWindow模块是Electron应用程序的基础，它公开了许多可以改变浏览器窗口外观和行为的API。In this tutorial, we will be going over the various use-cases for window customization on macOS, Windows, and Linux.在本教程中，我们将介绍macOS、Windows和Linux上窗口定制的各种用例。

Create frameless windows创建无框架窗口​

A frameless window is a window that has no chrome. 无框架窗口是一个没有chrome的窗口。Not to be confused with the Google Chrome browser, window chrome refers to the parts of the window (e.g. toolbars, controls) that are not a part of the web page.不要与Google Chrome浏览器混淆，window Chrome指的是不属于网页的窗口部分（如工具栏、控件）。

To create a frameless window, you need to set frame to false in the BrowserWindow constructor.要创建无框架窗口，需要在BrowserWindow构造函数中将frame设置为false。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ frame: false })

Apply custom title bar styles应用自定义标题栏样式 macOS Windows​

Title bar styles allow you to hide most of a BrowserWindow's chrome while keeping the system's native window controls intact and can be configured with the titleBarStyle option in the BrowserWindow constructor.标题栏样式允许您隐藏浏览器窗口的大部分chrome，同时保持系统的本机窗口控件不变，并且可以使用BrowserWindow构造函数中的titleBarStyle选项进行配置。

Applying the hidden title bar style results in a hidden title bar and a full-size content window.应用hidden标题栏样式将生成隐藏标题栏和全尺寸内容窗口。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hidden' })

Control the traffic lights控制交通灯 macOS​

On macOS, applying the hidden title bar style will still expose the standard window controls (“traffic lights”) in the top left.在macOS上，应用hidden标题栏样式仍将显示左上角的标准窗口控件（“红绿灯”）。

Customize the look of your traffic lights自定义交通灯的外观 macOS​

The customButtonsOnHover title bar style will hide the traffic lights until you hover over them. customButtonsOnHover标题栏样式将隐藏红绿灯，直到您将其悬停在红绿灯上。This is useful if you want to create custom traffic lights in your HTML but still use the native UI to control the window.如果您想在HTML中创建自定义红绿灯，但仍然使用原生UI来控制窗口，这将非常有用。

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

Customize the traffic light position自定义红绿灯位置 macOS​

To modify the position of the traffic light window controls, there are two configuration options available.要修改交通灯窗口控件的位置，有两个配置选项可用。

Applying hiddenInset title bar style will shift the vertical inset of the traffic lights by a fixed amount.应用hiddenInset标题栏样式将交通信号灯的垂直插入移动固定量。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })

If you need more granular control over the positioning of the traffic lights, you can pass a set of coordinates to the trafficLightPosition option in the BrowserWindow constructor.如果需要对交通灯的定位进行更精细的控制，可以将一组坐标传递给BrowserWindow构造函数中的trafficLightPosition选项。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  trafficLightPosition: { x: 10, y: 10 }
})

Show and hide the traffic lights programmatically以编程方式显示和隐藏交通灯 macOS​

You can also show and hide the traffic lights programmatically from the main process. 您还可以从主进程以编程方式显示和隐藏交通灯。The win.setWindowButtonVisibility forces traffic lights to be show or hidden depending on the value of its boolean parameter.win.setWindowButtonVisibility根据其布尔参数的值强制显示或隐藏交通灯。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// hides the traffic lights
win.setWindowButtonVisibility(false)

Note: Given the number of APIs available, there are many ways of achieving this. 注意：考虑到可用API的数量，有很多方法可以实现这一点。For instance, combining frame: false with win.setWindowButtonVisibility(true) will yield the same layout outcome as setting titleBarStyle: 'hidden'.例如，将frame:false与win.setWindowButtonVisibility(true)组合将产生与设置titleBarStyle: 'hidden'相同的布局结果。

Window Controls Overlay窗口控件覆盖 macOS Windows​

The Window Controls Overlay API is a web standard that gives web apps the ability to customize their title bar region when installed on desktop. 窗口控件覆盖API是一个web标准，它允许web应用程序在安装到桌面上时自定义其标题栏区域。Electron exposes this API through the BrowserWindow constructor option titleBarOverlay.Electron通过BrowserWindow构造函数选项titleBarOverlay公开此API。

This option only works whenever a custom titlebarStyle is applied on macOS or Windows. 此选项仅在macOS或Windows上应用自定义titlebarStyle时有效。When titleBarOverlay is enabled, the window controls become exposed in their default position, and DOM elements cannot use the area underneath this region.启用titleBarOverlay后，窗口控件将在其默认位置公开，DOM元素无法使用该区域下方的区域。

The titleBarOverlay option accepts two different value formats.titleBarOverlay选项接受两种不同的值格式。

Specifying true on either platform will result in an overlay region with default system colors:在任一平台上指定true将导致使用默认系统颜色的覆盖区域：

main.js
// on macOS or Windows
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: true
})

On Windows, you can also specify additional parameters. 在Windows上，还可以指定其他参数。The color of the overlay and its symbols can be specified by setting titleBarOverlay to an object and using the color and symbolColor properties respectively. 覆盖的颜色及其符号可以通过将titleBarOverlay设置为对象并分别使用color和symbolColor属性来指定。The height of the overlay can also be specified with the height property.还可以使用height属性指定覆盖的高度。

If a color option is not specified, the color will default to its system color for the window control buttons. 如果未指定颜色选项，则窗口控制按钮的颜色将默认为其系统颜色。Similarly, if the height option is not specified it will default to the default height:类似地，如果未指定高度选项，它将默认为默认高度：

main.js
// on Windows
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#2f3241',
    symbolColor: '#74b1be',
    height: 60
  }
})

Note: Once your title bar overlay is enabled from the main process, you can access the overlay's color and dimension values from a renderer using a set of readonly JavaScript APIs and CSS Environment Variables.注意：从主进程启用标题栏覆盖后，您可以使用一组只读JavaScript API和CSS环境变量从渲染器访问覆盖的颜色和维度值。

Limitations局限性​

  • Transparent colors are currently not supported. 当前不支持透明颜色。Progress updates for this feature can be found in PR #33567.此功能的进度更新可在PR#33567中找到。

Create transparent windows创建透明窗口​

By setting the transparent option to true, you can make a fully transparent window.通过将transparent选项设置为true，可以创建完全透明的窗口。

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ transparent: true })

Limitations局限性​

  • You cannot click through the transparent area. 您无法单击透明区域。See #1335 for details.
  • Transparent windows are not resizable. 透明窗口不可调整大小。Setting resizable to true may make a transparent window stop working on some platforms.将resizable设置为true可能会使透明窗口在某些平台上停止工作。
  • The CSS blur() filter only applies to the window's web contents, so there is no way to apply blur effect to the content below the window (i.e. other applications open on the user's system).
  • The window will not be transparent when DevTools is opened.打开DevTools时，窗口将不透明。
  • On Windows:
    • Transparent windows will not work when DWM is disabled.禁用DWM时，透明窗口将不工作。
    • Transparent windows can not be maximized using the Windows system menu or by double clicking the title bar. 无法使用windows系统菜单或双击标题栏最大化透明窗口。The reasoning behind this can be seen on PR #28207.这背后的原因可参见PR#28207。
  • On macOS:
    • The native window shadow will not be shown on a transparent window.本机窗口阴影将不会显示在透明窗口上。

Create click-through windows创建点击窗口​

To create a click-through window, i.e. making the window ignore all mouse events, you can call the win.setIgnoreMouseEvents(ignore) API:

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.setIgnoreMouseEvents(true)

Forward mouse events向前鼠标事件 macOS Windows​

Ignoring mouse messages makes the web contents oblivious to mouse movement, meaning that mouse movement events will not be emitted. 忽略鼠标消息会使web内容忽略鼠标移动，这意味着不会发出鼠标移动事件。On Windows and macOS, an optional parameter can be used to forward mouse move messages to the web page, allowing events such as mouseleave to be emitted:在Windows和macOS上，可以使用一个可选参数将鼠标移动消息转发到网页，从而允许发出mouseleve等事件：

main.js
const { BrowserWindow, ipcMain } = require('electron')
const path = require('path')

const win = new BrowserWindow({
  webPreferences: {
    preload: path.join(__dirname, 'preload.js')
  }
})

ipcMain.on('set-ignore-mouse-events', (event, ...args) => {
  const win = BrowserWindow.fromWebContents(event.sender)
  win.setIgnoreMouseEvents(...args)
})
preload.js
window.addEventListener('DOMContentLoaded', () => {
  const el = document.getElementById('clickThroughElement')
  el.addEventListener('mouseenter', () => {
    ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
  })
  el.addEventListener('mouseleave', () => {
    ipcRenderer.send('set-ignore-mouse-events', false)
  })
})

This makes the web page click-through when over the #clickThroughElement element, and returns to normal outside it.

Set custom draggable region​

By default, the frameless window is non-draggable. Apps need to specify -webkit-app-region: drag in CSS to tell Electron which regions are draggable (like the OS's standard titlebar), and apps can also use -webkit-app-region: no-drag to exclude the non-draggable area from the draggable region. Note that only rectangular shapes are currently supported.

To make the whole window draggable, you can add -webkit-app-region: drag as body's style:

styles.css
body {
  -webkit-app-region: drag;
}

And note that if you have made the whole window draggable, you must also mark buttons as non-draggable, otherwise it would be impossible for users to click on them:请注意，如果您已将整个窗口设置为可拖动，则还必须将按钮标记为不可拖动，否则用户将无法单击它们：

styles.css
button {
  -webkit-app-region: no-drag;
}

If you're only setting a custom titlebar as draggable, you also need to make all buttons in titlebar non-draggable.

Tip: disable text selection​

When creating a draggable region, the dragging behavior may conflict with text selection. For example, when you drag the titlebar, you may accidentally select its text contents. To prevent this, you need to disable text selection within a draggable area like this:

.titlebar {
  -webkit-user-select: none;
  -webkit-app-region: drag;
}

Tip: disable context menus​

On some platforms, the draggable area will be treated as a non-client frame, so when you right click on it, a system menu will pop up. To make the context menu behave correctly on all platforms, you should never use a custom context menu on draggable areas.