自定义标题栏¶

基础教程¶

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

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

```fiddle docs/fiddles/features/window-customization/custom-title-bar/starter-code

### 移除默认标题栏 {#remove-the-default-title-bar}

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

```fiddle docs/fiddles/features/window-customization/custom-title-bar/remove-title-bar

添加原生窗口控件 Windows Linux¶

在 macOS 上，设置 titleBarStyle: 'hidden' 会移除标题栏，同时保留窗口左上角的红绿灯控件。然而在 Windows 和 Linux 上，你需要通过在 BrowserWindow 构造函数中设置 [BaseWindowContructorOptions][] 的 titleBarOverlay 参数，将窗口控件重新添加到你的 BrowserWindow 中。

```fiddle docs/fiddles/features/window-customization/custom-title-bar/native-window-controls

设置 `titleBarOverlay: true` 是将窗口控件重新暴露到你的 `BrowserWindow` 中的最简单方式。如果你有兴趣进一步自定义窗口控件，请查看 [自定义红绿灯按钮][Custom traffic lights] 和 [自定义窗口控件][Custom window controls] 部分，它们对此有更详细的介绍。

### 创建自定义标题栏 {#create-a-custom-title-bar}

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

```fiddle docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar

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

```fiddle docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region

有关如何管理由你的 Electron 应用程序定义的拖拽区域的更多信息，请参见下面的 [自定义可拖拽区域][Custom draggable regions] 部分。

再进一步：我们应该确保标题栏内容不会与原生窗口控件重叠。按钮可能出现在边框的右侧或左侧（或两者都有），具体取决于 RTL 和用户的设置。我们可以使用 CSS 变量 `env(titlebar-area-x, 0px)` 和 `env(titlebar-area-width, 100%)` 创建一个安全区域。

```fiddle docs/fiddles/features/window-customization/custom-title-bar/safe-area

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

高级窗口自定义¶

自定义红绿灯按钮 macOS¶

自定义红绿灯按钮外观 macOS¶

customButtonsOnHover 标题栏样式会隐藏红绿灯按钮，直到你悬停在它们上面。如果你想在 HTML 中创建自定义红绿灯按钮，但仍使用原生 UI 来控制窗口，这很有用。

const { BrowserWindow } = require('electron')

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

自定义红绿灯按钮位置 macOS¶

要修改红绿灯窗口控件的位置，有两种可用的配置选项。

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

const { BrowserWindow } = require('electron')

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

如果你需要对红绿灯按钮的位置进行更精细的控制，可以向 BrowserWindow 构造函数中的 trafficLightPosition 选项传递一组坐标。

const { BrowserWindow } = require('electron')

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

以编程方式显示和隐藏红绿灯按钮 macOS¶

你也可以从主进程以编程方式显示和隐藏红绿灯按钮。win.setWindowButtonVisibility 会根据其布尔参数的值强制显示或隐藏红绿灯按钮。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow()
// hides the traffic lights
win.setWindowButtonVisibility(false)

:::note 鉴于可用的 API 数量，实现此功能的方式有很多。例如，将 frame: false 与 win.setWindowButtonVisibility(true) 组合使用，会产生与设置 titleBarStyle: 'hidden' 相同的布局结果。 :::

自定义窗口控件¶

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

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

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

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

const { BrowserWindow } = require('electron')

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

:::note 一旦从主进程启用了标题栏覆盖层，你就可以从渲染进程中使用一组只读的 JavaScript APIs 和 CSS Environment Variables 来访问覆盖层的颜色和尺寸值。 :::