Skip to main content

自定义标题栏

🌐 Custom Title Bar

基本教程​

🌐 Basic tutorial

应用窗口默认由操作系统应用 谷歌浏览器。不应与 Google Chrome 浏览器混淆，窗口 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 sufficient 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 (40.6.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 (40.6.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 (40.6.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controls 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 (40.6.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controls 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 (40.6.0)Open in Fiddle
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controls 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 中创建自定义的交通灯按钮，但仍然使用本地界面来控制窗口，这会很有用。

🌐 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 shown 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)
note

鉴于可用的 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 是一个网络标准，它让网页应用在安装到桌面时能够自定义标题栏区域。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.

note

titleBarOverlay 在 BrowserWindow 构造函数中要求 titleBarStyle 参数的值不能为 default。

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

🌐 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
  }
})
note

一旦在主进程中启用了标题栏覆盖，你就可以在渲染器中使用一组只读的 JavaScript 接口 和 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.