第12章 Electron 教程：自定义应用标题栏

自定义标题栏 基础教程 应用窗口默认带有操作系统提供的窗口框架（window chrome）。这里的 chrome 别和 Google Chrome 浏览器搞混，它指的是窗口中不属于网页内容的部分，比如标题栏、工具栏、控制按钮等。操作系统默认的标题栏对简单场景来说够用了，但很多应用会选择把它去掉，改用自定义标题栏——这样应用看起来更现代，各平台上的表现也更一致。 你可以用下面的初始代码打开 Fiddle，跟着这个教程一步步做。 docs/fiddles/features/window-customization/custom-title-bar/starter-code (44.6.0)在 Fiddle 中打开 main.jsconst { 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 (44.6.0)在 Fiddle 中打开 main.jsconst { app, BrowserWindow } = require('electron')

function createWindow () {
const win = new BrowserWindow({
// 移除默认标题栏
titleBarStyle: 'hidden'
})
win.loadURL('https://example.com')
}

app.whenReady().then(() => {
createWindow()
})
添加原生窗口控制按钮 Windows Linux 在 macOS 上，设置 titleBarStyle: 'hidden' 会移除标题栏，但左上角的红绿灯控制按钮仍然保留。而在 Windows 和 Linux 上，你需要在 BrowserWindow 构造函数中设置 BaseWindowContructorOptions 的 titleBarOverlay 参数，把窗口控制按钮加回来。 docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (44.6.0)在 Fiddle 中打开 main.jsconst { app, BrowserWindow } = require('electron')

function createWindow () {
const win = new BrowserWindow({
// 移除默认标题栏
titleBarStyle: 'hidden',
// 在 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 (44.6.0)Open in Fiddlemain.jsindex.htmlstyles.cssconst { 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()
})














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 (44.6.0)Open in Fiddlemain.jsindex.htmlstyles.cssconst { app, BrowserWindow } = require('electron')

function createWindow () {
const win = new BrowserWindow({
// remove the default titlebar
titleBarStyle: 'hidden',
// expose window controls in Windows/Linux
关于 Electron 应用中如何管理可拖动区域，详情见下文「自定义可拖动区域」部分。 再补充一步：我们应确保标题栏内容不会与原生窗口控件重叠。按钮可能出现在窗口边框的右侧或左侧（也可能两侧都有，取决于 RTL 模式和用户设置）。我们可以使用 CSS 变量 `env(titlebar-area-x, 0px)` 和 `env(titlebar-area-width, 100%)` 来创建安全区域。 docs/fiddles/features/window-customization/custom-title-bar/safe-area (44.6.0)Open in Fiddlemain.jsindex.htmlstyles.cssconst { 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()
})














body {
margin: 0;
}
.titlebar {
background: blue;
color: white;
display: flex;
justify-content: center;
align-items: center;
app-region: drag;

margin-left: env(titlebar-area-x, 0);
width: env(titlebar-area-width, 100%);
height: env(titlebar-area-height, 30px);
box-sizing: border-box;
border: 1px dashed red;
}
恭喜，你已经实现了一个基础的自定义标题栏！ 进阶窗口定制​ 自定义红绿灯按钮 macOS​ 自定义红绿灯按钮的外观 macOS​ 将标题栏样式设置为 customButtonsOnHover 后，红绿灯按钮会隐藏，直到鼠标悬停其上才会显示。如果你想用 HTML 自己实现红绿灯按钮，同时仍用原生 UI 控制窗口，这个选项会很有用。 const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })
调整红绿灯按钮的位置 macOS​ 要修改红绿灯窗口控制按钮的位置，有两种配置方式可选。 使用 hiddenInset 标题栏样式，红绿灯按钮会按固定距离向下偏移。 main.jsconst { BrowserWindow } = require('electron')

const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })
如果需要更精细地控制红绿灯按钮的位置，可以在 BrowserWindow 构造函数中通过 trafficLightPosition 选项传入一组坐标。 main.jsconst { BrowserWindow } = require('electron')

const win = new BrowserWindow({
titleBarStyle: 'hidden',
trafficLightPosition: { x: 10, y: 10 }
})
通过代码显示和隐藏红绿灯按钮 macOS​ 你也可以在主进程中通过代码来显示或隐藏红绿灯按钮。win.setWindowButtonVisibility 方法会根据其布尔参数的值来强制显示或隐藏红绿灯按钮。 main.jsconst { BrowserWindow } = require('electron')

const win = new BrowserWindow()
// 隐藏红绿灯按钮
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 来暴露窗口控制按钮的基本示例。将 titleBarOverlay 设置为对象可以进一步自定义窗口控制按钮的高度、颜色（Windows/Linux）以及符号颜色（Windows）。 height 属性的值必须是整数。color 和 symbolColor 属性支持 rgba()、hsla() 和 #RRGGBBAA 颜色格式，并支持透明度。如果未指定颜色选项，窗口控制按钮的颜色将默认为系统颜色。同理，如果未指定 height 选项，窗口控制按钮将默认为系统标准高度： main.js const { BrowserWindow } = require('electron')

const win = new BrowserWindow({
titleBarStyle: 'hidden',
titleBarOverlay: {
color: '#2f3241',
symbolColor: '#74b1be',
height: 60
}
})
一旦在主进程中启用了标题栏覆盖层，就可以通过一组只读的 JavaScript API 和 CSS 环境变量在渲染进程中访问该覆盖层的颜色和尺寸值。