跳到主要內容

自訂標題列

基本教學​

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

您可以開啟 Fiddle 並使用以下入門程式碼，跟著本教學進行操作。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (35.0.1)在 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 (35.0.1)在 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 (35.0.1)在 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 (35.0.1)在 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 (35.0.1)在 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 環境變數，從渲染器存取覆疊的顏色和尺寸值。