跳到主要内容

自定义标题栏

基本教程​

应用程序窗口默认由操作系统应用窗口装饰。这里的窗口 装饰 并非指 Google Chrome 浏览器，而是指窗口中不属于主要网页内容的部件（例如标题栏、工具栏、控件）。虽然操作系统提供的默认标题栏对于简单用例已足够，但许多应用程序选择移除它。实现自定义标题栏可以帮助您的应用程序在不同平台间感觉更现代化且一致。

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

docs/fiddles/features/window-customization/custom-title-bar/starter-code (37.1.0)在 Fiddle 中打开
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 (37.1.0)在 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​

在 macOS 上，设置 titleBarStyle: 'hidden' 会移除标题栏，但会保留窗口左上角的交通灯控件。然而在 Windows 和 Linux 上，您需要通过在 BrowserWindow 构造函数中设置 BaseWindowContructorOptions 的 titleBarOverlay 参数来将窗口控件添加回您的 BrowserWindow。

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (37.1.0)在 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 中。如果您有兴趣进一步自定义窗口控件，请查看 自定义交通灯 和 自定义窗口控件 部分，其中详细介绍了这一点。

创建自定义标题栏​

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

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (37.1.0)在 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 来实现这一点。现在我们可以拖动自定义标题栏来重新定位我们的应用程序窗口了！

docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region (37.1.0)在 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 应用程序定义的拖动区域的更多信息，请参阅下面的 自定义可拖动区域 部分。

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

高级窗口自定义​

自定义交通灯 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 应用程序在安装到桌面时自定义其标题栏区域。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 环境变量从渲染进程访问叠加层的颜色和尺寸值。