自定义标题栏

基本教程

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

您可以通过打开 Fiddle 并使用以下入门代码来遵循本教程。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (38.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 (38.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 构造函数中设置 BaseWindowContructorOptions 的 titleBarOverlay 参数，将窗口控件添加回 BrowserWindow。

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (38.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 (38.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 (38.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' 相同的布局效果。

自定义窗口控件

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​

自定义窗口控件​