自定义标题栏

基础教程

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

您可以通过使用以下启动代码打开 Fiddle 来跟随本教程进行操作。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (34.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 (34.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 参数来将窗口控件添加回您的 BrowserWindow 中。

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

main.js

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

创建一个自定义标题栏

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

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (34.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 controlls 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 (34.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 controlls 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' 相同的布局结果。

自定义窗口控件

Window Controls Overlay 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​

自定义窗口控件​