跳至主要內容

自訂標題列

基本教學​

應用程式視窗預設會套用作業系統的 chrome。請勿與 Google Chrome 瀏覽器混淆，視窗的chrome 指的是視窗中不屬於主要網頁內容的部分（例如標題列、工具列、控制項）。雖然作業系統 chrome 提供的預設標題列足以應付簡單的使用情況，但許多應用程式選擇移除它。實作自訂標題列可以讓您的應用程式在跨平台時感覺更現代且一致。

您可以開啟具有以下起始程式碼的 Fiddle，跟著本教學進行。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (34.0.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 (34.0.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，方法是在 BrowserWindow 建構函式中設定 BaseWindowContructorOptions 的 titleBarOverlay 參數。

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (34.0.0)在 Fiddle 中開啟
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls 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 (34.0.0)在 Fiddle 中開啟
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls 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 (34.0.0)在 Fiddle 中開啟
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({
    // remove the default titlebar
    titleBarStyle: 'hidden',
    // expose window controlls 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 是一個網頁標準，可讓網頁應用程式在安裝於桌上型電腦時自訂其標題列區域。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 環境變數，從渲染器存取覆蓋的顏色和尺寸數值。