跳转到主内容

自定义标题栏

基础教程​

应用窗口有操作系统设置的默认窗口外框（chrome）。 不要与 Google Chrome 浏览器混淆， 窗口外框（chrome） 是指窗口中不是主网页内容的部分（如标题栏，工具栏，控件）。 虽然操作系统的窗口外框提供的默认标题栏对于简单用例足够了，但是很多应用选择去除它。 实现一个自定义的标题栏可以使您的应用更有现代感，并在多个平台中保持一致。

你可以打开有以下初始代码的 Fiddle 来跟随本教程。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (43.1.1)Open in 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 (43.1.1)Open in 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 (43.1.1)Open in 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 最简单的方法。 如果你对如何深入自定义窗口控件感兴趣，请查看 Custom traffic lights 和 Custom window controls 部分，这两个部分讲解地更详细。

创建自定义标题栏​

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

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (43.1.1)Open in 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 哪些区域可以拖拽。 我们通过添加 样式的 app-region: drag 到自定义标题栏来做到这一点。 现在我们可以拖动自定义标题栏来重新定位我们的应用窗口了！

docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region (43.1.1)Open in 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 应用定义的拖动区域，查看下面的Custom draggable regions部分。

One more step: we should make sure our title bar content doesn't overlap with the native window controls. Buttons can appear on the right or left side of the frame (or both) depending on RTL and the user's settings. We can create a safe area using the CSS variables env(titlebar-area-x, 0px) and env(titlebar-area-width, 100%).

docs/fiddles/features/window-customization/custom-title-bar/safe-area (43.1.1)Open in 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()
})

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

高级窗口自定义​

自定义红绿灯 macOS​

自定义红绿灯的外观 macOS​

customButtonsOnHover 标题栏样式将隐藏红绿灯，直到你悬停在它们上面。 如果您想要在您的 HTML 中创建自定义红绿灯，但仍然 使用原生界面来控制窗口，这是有用的。

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)
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 和 symbolor属性接受rgba()、hsla()和#RRGGBBAA的颜色格式，并支持透明度。 如果未指定颜色选项，则窗口控件按钮的颜色将是系统默认颜色。 同样，如果未指定高度选项，窗口控件将默认为标准系统高度：

main.js
const { BrowserWindow } = require('electron')

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

一旦你的标题栏叠加层在主进程启用，你可以用一组只读的JavaScript APIs and CSS Environment Variables在渲染器获取叠加层的颜色和尺寸。