自定义标题栏

基础教程

应用程序窗口默认应用了操作系统提供的 chrome。请勿与 Google Chrome 浏览器混淆，窗口 chrome 指的是窗口的部分（例如标题栏、工具栏、控件），这些部分不属于主要的网页内容。虽然操作系统 chrome 提供的默认标题栏对于简单的用例来说已经足够，但许多应用程序选择将其移除。实现自定义标题栏可以帮助您的应用程序在跨平台时感觉更现代化和一致。

您可以按照本教程，通过打开 Fiddle 并使用以下启动代码进行操作。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (40.0.0)在 Fiddle 中打开

main.js

const { app, BrowserWindow } = require('electron')

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

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

移除默认标题栏

让我们首先配置一个带有原生窗口控件和隐藏标题栏的窗口。要移除默认标题栏，请在 BrowserWindow 构造函数中将 BaseWindowContructorOptions titleBarStyle 参数设置为 'hidden'。

docs/fiddles/features/window-customization/custom-title-bar/remove-title-bar (40.0.0)在 Fiddle 中打开

main.js

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

在 macOS 上，设置 titleBarStyle: 'hidden' 会移除标题栏，同时保留窗口左上角的流量控制按钮。但是，在 Windows 和 Linux 上，您需要在 BrowserWindow 中通过在 BrowserWindow 构造函数中设置 BaseWindowContructorOptions titleBarOverlay 参数来添加回窗口控件。

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (40.0.0)在 Fiddle 中打开

main.js

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 的最简单方法。如果您有兴趣进一步自定义窗口控件，请查看自定义流量灯和自定义窗口控件部分，这些部分将更详细地介绍这一点。

创建一个自定义标题栏

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

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (40.0.0)在 Fiddle 中打开

main.js
index.html
styles.css

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

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://mdn.org.cn/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
    <link href="./styles.css" rel="stylesheet">
    <title>Custom Titlebar App</title>
  </head>
  <body>
	  <!-- mount your title bar at the top of you application's body tag -->
    <div class="titlebar">Cool titlebar</div>
  </body>
</html>

body {
    margin: 0;
}

.titlebar {
  height: 30px;
  background: blue;
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
}

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

docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region (40.0.0)在 Fiddle 中打开

main.js
index.html
styles.css

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

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://mdn.org.cn/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
    <link href="./styles.css" rel="stylesheet">
    <title>Custom Titlebar App</title>
  </head>
  <body>
	  <!-- mount your title bar at the top of you application's body tag -->
    <div class="titlebar">Cool titlebar</div>
  </body>
</html>

body {
  margin: 0;
}
.titlebar {
  height: 30px;
  background: blue;
  color: white;
  display: flex;
  justify-content: center;
  align-items: center;
  app-region: drag;
}

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

恭喜您，您已经实现了一个基本的自定义标题栏！

高级窗口自定义

自定义流量灯 macOS

自定义流量灯的外观 macOS

customButtonsOnHover 标题栏样式会在您将鼠标悬停在流量灯上时隐藏它们。如果您想在 HTML 中创建自定义流量灯，但仍然使用原生 UI 来控制窗口，这将很有用。

const { BrowserWindow } = require('electron')

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

自定义流量灯的位置 macOS

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

应用 hiddenInset 标题栏样式会将流量灯的垂直内边距移动固定量。

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

const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })

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

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

const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  trafficLightPosition: { x: 10, y: 10 }
})

以编程方式显示和隐藏流量灯 macOS

您还可以从主进程以编程方式显示和隐藏流量灯。win.setWindowButtonVisibility 会根据其布尔参数的值强制流量灯显示或隐藏。

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' 相同的布局结果。

自定义窗口控件

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

注意

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

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

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

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

const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#2f3241',
    symbolColor: '#74b1be',
    height: 60
  }
})

注意

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

基础教程​

移除默认标题栏​

添加原生窗口控件 Windows Linux​

创建一个自定义标题栏​

高级窗口自定义​

自定义流量灯 macOS​

自定义流量灯的外观 macOS​

自定义流量灯的位置 macOS​

以编程方式显示和隐藏流量灯 macOS​

自定义窗口控件​