Skip to main content

自定义标题栏

¥Custom Title Bar

基本教程​

¥Basic tutorial

应用窗口具有由操作系统应用的默认 chrome。不要与 Google Chrome 浏览器混淆，窗口镶边是指窗口的部分（例如标题栏、工具栏、控件），这些部分不属于主要 Web 内容。虽然 OS chrome 提供的默认标题栏足以满足简单的用例，但许多应用选择将其删除。实现自定义标题栏可以帮助你的应用在各个平台上感觉更现代、更一致。

¥Application windows have a default chrome applied by the OS. Not to be confused with the Google Chrome browser, window chrome refers to the parts of the window (e.g. title bar, toolbars, controls) that are not a part of the main web content. While the default title bar provided by the OS chrome is sufficent for simple use cases, many applications opt to remove it. Implementing a custom title bar can help your application feel more modern and consistent across platforms.

你可以通过使用以下入门代码打开 Fiddle 来跟随本教程。

¥You can follow along with this tutorial by opening Fiddle with the following starter code.

docs/fiddles/features/window-customization/custom-title-bar/starter-code (34.0.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({})
  win.loadURL('https://example.com')
}

app.whenReady().then(() => {
  createWindow()
})

删除默认标题栏​

¥Remove the default title bar

让我们从配置具有原生窗口控件和隐藏标题栏的窗口开始。要删除默认标题栏，请将 BrowserWindow 构造函数中的 BaseWindowContructorOptions titleBarStyle 参数设置为 'hidden'。

¥Let’s start by configuring a window with native window controls and a hidden title bar. To remove the default title bar, set the BaseWindowContructorOptions titleBarStyle param in the BrowserWindow constructor to 'hidden'.

docs/fiddles/features/window-customization/custom-title-bar/remove-title-bar (34.0.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden'
  })
  win.loadURL('https://example.com')
}

app.whenReady().then(() => {
  createWindow()
})

添加原生窗口控件 Windows Linux​

¥Add native window controls Windows Linux

在 macOS 上，设置 titleBarStyle: 'hidden' 会删除标题栏，同时保持窗口的交通灯控件在左上角可用。但是在 Windows 和 Linux 上，你需要通过在 BrowserWindow 构造函数中设置 BaseWindowContructorOptions titleBarOverlay 参数将窗口控件添加回你的 BrowserWindow。

¥On macOS, setting titleBarStyle: 'hidden' removes the title bar while keeping the window’s traffic light controls available in the upper left hand corner. However on Windows and Linux, you’ll need to add window controls back into your BrowserWindow by setting the BaseWindowContructorOptions titleBarOverlay param in the BrowserWindow constructor.

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (34.0.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls in Windows/Linux
    ...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
  })
  win.loadURL('https://example.com')
}

app.whenReady().then(() => {
  createWindow()
})

设置 titleBarOverlay: true 是将窗口控件重新显示到 BrowserWindow 中的最简单方法。如果你有兴趣进一步自定义窗口控件，请查看更详细地介绍此内容的 自定义交通灯 和 自定义窗口控件 部分。

¥Setting titleBarOverlay: true is the simplest way to expose window controls back into your BrowserWindow. If you’re interested in customizing the window controls further, check out the sections Custom traffic lights and Custom window controls that cover this in more detail.

创建自定义标题栏​

¥Create a custom title bar

现在，让我们在 BrowserWindow 的 webContents 中实现一个简单的自定义标题栏。这里没有什么花哨的东西，只有 HTML 和 CSS！

¥Now, let’s implement a simple custom title bar in the webContents of our BrowserWindow. There’s nothing fancy here, just HTML and CSS!

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (34.0.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls in Windows/Linux
    ...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
  })

  win.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()
})

目前我们的应用窗口无法移动。由于我们删除了默认标题栏，应用需要告诉 Electron 哪些区域是可拖动的。我们将通过将 CSS 样式 app-region: drag 添加到自定义标题栏来实现这一点。现在我们可以拖动自定义标题栏来重新定位我们的应用窗口！

¥Currently our application window can’t be moved. Since we’ve removed the default title bar, the application needs to tell Electron which regions are draggable. We’ll do this by adding the CSS style app-region: drag to the custom title bar. Now we can drag the custom title bar to reposition our app window!

docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region (34.0.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls in Windows/Linux
    ...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
  })

  win.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()
})

有关如何管理 Electron 应用定义的拖动区域的更多信息，请参阅下面的 自定义可拖动区域 部分。

¥For more information around how to manage drag regions defined by your electron application, see the Custom draggable regions section below.

恭喜，你刚刚实现了一个基本的自定义标题栏！

¥Congratulations, you've just implemented a basic custom title bar!

高级窗口自定义​

¥Advanced window customization

自定义交通信号灯 macOS​

¥Custom traffic lights macOS

自定义交通灯 macOS 的外观​

¥Customize the look of your traffic lights macOS

customButtonsOnHover 标题栏样式将隐藏交通灯，直到你将鼠标悬停在它们上方。如果你想在 HTML 中创建自定义交通灯，但仍使用原生 UI 来控制窗口，这非常有用。

¥The customButtonsOnHover title bar style will hide the traffic lights until you hover over them. This is useful if you want to create custom traffic lights in your HTML but still use the native UI to control the window.

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

自定义交通灯位置 macOS​

¥Customize the traffic light position macOS

要修改交通灯窗口控件的位置，有两个配置选项可用。

¥To modify the position of the traffic light window controls, there are two configuration options available.

应用 hiddenInset 标题栏样式会将交通信号灯的垂直插入移动固定量。

¥Applying hiddenInset title bar style will shift the vertical inset of the traffic lights by a fixed amount.

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

如果需要对交通灯的位置进行更精细的控制，可以将一组坐标传递给 BrowserWindow 构造函数中的 trafficLightPosition 选项。

¥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.

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

以编程方式显示和隐藏交通灯 macOS​

¥Show and hide the traffic lights programmatically macOS

你还可以在主进程中以编程方式显示和隐藏交通信号灯。win.setWindowButtonVisibility 根据其布尔参数的值强制显示或隐藏交通灯。

¥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.

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

考虑到可用 API 的数量，有很多方法可以实现这一目标。例如，将 frame: false 与 win.setWindowButtonVisibility(true) 组合将产生与设置 titleBarStyle: 'hidden' 相同的布局结果。

¥Given the number of APIs available, there are many ways of achieving this. For instance, combining frame: false with win.setWindowButtonVisibility(true) will yield the same layout outcome as setting titleBarStyle: 'hidden'.

自定义窗口控件​

¥Custom window controls

窗口控件覆盖 API 是一种 Web 标准，使 Web 应用能够在安装在桌面上时自定义其标题栏区域。Electron 通过 BrowserWindow 构造函数中的 titleBarOverlay 选项公开此 API。当启用 titleBarOverlay 时，窗口控件将在其默认位置公开，并且 DOM 元素无法使用该区域下方的区域。

¥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. Electron exposes this API through the titleBarOverlay option in the BrowserWindow constructor. When titleBarOverlay is enabled, the window controls become exposed in their default position, and DOM elements cannot use the area underneath this region.

注意

titleBarOverlay 要求 BrowserWindow 构造函数中的 titleBarStyle 参数具有除 default 以外的值。

¥titleBarOverlay requires the titleBarStyle param in the BrowserWindow constructor to have a value other than default.

自定义标题栏教程涵盖了通过设置 titleBarOverlay: true 来公开窗口控件的 基本示例。可以通过将 titleBarOverlay 设置为对象来进一步自定义窗口控件的高度、颜色（Windows Linux）和符号颜色（Windows）。

¥The custom title bar tutorial covers a basic example of exposing window controls by setting titleBarOverlay: true. The height, color (Windows Linux), and symbol colors (Windows) of the window controls can be customized further by setting titleBarOverlay to an object.

传递给 height 属性的值必须是整数。color 和 symbolColor 属性接受 rgba()、hsla() 和 #RRGGBBAA 颜色格式并支持透明度。如果未指定颜色选项，则窗口控制按钮的颜色将默认为其系统颜色。同样，如果未指定高度选项，窗口控件将默认为标准系统高度：

¥The value passed to the height property must be an integer. The color and symbolColor properties accept rgba(), hsla(), and #RRGGBBAA color formats and support transparency. 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, the window controls will default to the standard system height:

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

从主进程启用标题栏覆盖后，你可以使用一组只读 JavaScript API 和 CSS 环境变量 从渲染器访问覆盖的颜色和尺寸值。

¥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.