跳到主要内容

自定义标题栏

基本教程​

应用程序窗口默认情况下会应用由操作系统提供的 chrome。 此处提及的窗口 chrome 与 Google Chrome 浏览器无关，它指的是不属于主要网页内容的窗口部分（例如标题栏、工具栏、控件）。 虽然操作系统 chrome 提供的默认标题栏对于简单的用例来说已经足够，但许多应用程序选择将其移除。 实现自定义标题栏可以帮助您的应用程序感觉更现代化并在不同平台上保持一致。

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

docs/fiddles/features/window-customization/custom-title-bar/starter-code (36.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 (36.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' 设置为 'hidden' 会移除标题栏，同时保留窗口左上角的红绿灯控件。 但在 Windows 和 Linux 上，您需要通过在 BrowserWindow 构造函数中设置 BaseWindowContructorOptions 的 titleBarOverlay 参数来将窗口控件添加回 BrowserWindow。

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (36.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 (36.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 (36.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 (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 环境变量 来访问覆盖层的颜色和尺寸值。