カスタムのタイトルバー

基本チュートリアル

アプリケーションウインドウには、OS によって適用されるデフォルトの [クロム][] があります。 Google Chrome ブラウザと混同しないでください。ウインドウの クロム とは、メインのウェブコンテンツの一部ではないウインドウの部分 (タイトルバー、ツールバー、コントロールなど) のことです。 OS のクロムが提供するデフォルトのタイトルバーは単純な使用例では十分ですが、多くのアプリケーションではタイトルバーを削除することを選択します。カスタムのタイトルバーを実装すると、アプリケーションがよりモダンになり、プラットフォーム間で一貫性が保たれるようになります。

このチュートリアルに従うにあたっては、次のスターターコードの Fiddle を開くとできます。

docs/fiddles/features/window-customization/custom-title-bar/starter-code (43.2.0)Open in Fiddle

main.js

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.2.0)Open in Fiddle

main.js

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.2.0)Open in Fiddle

main.js

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 (43.2.0)Open in Fiddle

main.js
index.html
styles.css

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()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
    <link href="./styles.css" rel="stylesheet">
    <title>Custom Titlebar App</title>
  </head>
  <body>
	  <!-- mount your title bar at the top of you application's body tag -->
    <div class="titlebar">Cool titlebar</div>
  </body>
</html>

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 (43.2.0)Open in Fiddle

main.js
index.html
styles.css

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()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
    <link href="./styles.css" rel="stylesheet">
    <title>Custom Titlebar App</title>
  </head>
  <body>
	  <!-- mount your title bar at the top of you application's body tag -->
    <div class="titlebar">Cool titlebar</div>
  </body>
</html>

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

Electron アプリケーションによって定義されたドラッグ領域を管理する方法の詳細については、以下の [カスタムのドラッグ可能領域][] の節を参照してください。

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.2.0)Open in Fiddle

main.js
index.html
styles.css

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()
})

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
    <link href="./styles.css" rel="stylesheet">
    <title>Custom Titlebar App</title>
  </head>
  <body>
	  <!-- mount your title bar at the top of you application's body tag -->
    <div class="titlebar">Cool titlebar</div>
  </body>
</html>

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

ウインドウ制御の信号機ボタンの位置を変更するには、2 つの設定オプションがあります。

タイトルバーのスタイルに 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

信号機ボタンの表示と非表示はメインプロセスからプログラムでもできます。 The win.setWindowButtonVisibility forces traffic lights to be shown or hidden depending on the value of its boolean parameter.

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

const win = new BrowserWindow()
// 信号機ボタンを隠します
win.setWindowButtonVisibility(false)

note

利用可能な API の数を考えると、これを実現する方法はたくさんあります。たとえば、frame: false と win.setWindowButtonVisibility(true) を組み合わせると、titleBarStyle: 'hidden' を設定した場合と同じレイアウト結果になります。

カスタムのウインドウコントロール

[ウインドウコントロールオーバーレイ API][] は、デスクトップにインストールされたウェブアプリケーションがタイトルバーの領域をカスタマイズする機能を提供するウェブ標準です。 Electron は BrowserWindow コンストラクタの titleBarOverlay オプションを介してこの API を公開しています。 titleBarOverlay を有効にすると、ウインドウコントロールがその既定の位置で表示されるようになり、この領域の下にある DOM 要素は使用できなくなります。

note

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
  }
})

note

メインプロセスからタイトルバーのオーバーレイを有効にすると、JavaScript API と CSS 環境変数の組み合わせで、レンダラーから読み取り専用のオーバーレイの色と寸法の値にアクセスできます。

基本チュートリアル​

デフォルトのタイトルバーを削除する​

ネイティブのウインドウコントロールを追加する Windows Linux​

カスタムのタイトルバーを作成する​

高度なウインドウのカスタマイズ​

カスタムの信号機ボタン macOS​

信号機ボタンの見た目のカスタマイズ macOS​

信号機ボタンの位置のカスタマイズ macOS​

プログラムによる信号機ボタンの表示と非表示 macOS​

カスタムのウインドウコントロール​

基本チュートリアル

デフォルトのタイトルバーを削除する

ネイティブのウインドウコントロールを追加する Windows Linux

カスタムのタイトルバーを作成する

高度なウインドウのカスタマイズ

カスタムの信号機ボタン macOS

信号機ボタンの見た目のカスタマイズ macOS

信号機ボタンの位置のカスタマイズ macOS

プログラムによる信号機ボタンの表示と非表示 macOS

カスタムのウインドウコントロール