Skip to main content

커스텀 타이틀 바

기본 튜토리얼​

애플리케이션 윈도우에는 운영체제가 기본적으로 제공하는 [크롬][]이 적용된다. 여기서 크롬은 구글 크롬 브라우저와 혼동해서는 안 된다. 윈도우 크롬은 주 웹 콘텐츠가 아닌 부분(예: 타이틀 바, 툴바, 컨트롤)을 의미한다. 운영체제가 제공하는 기본 타이틀 바는 간단한 용도로 충분하지만, 많은 애플리케이션에서 이를 제거하는 경우가 있다. 커스텀 타이틀 바를 구현하면 애플리케이션을 더 현대적으로 만들고 플랫폼 간 일관성을 유지할 수 있다.

이 튜토리얼을 따라 하려면 아래 스타터 코드로 Fiddle을 열면 된다.

docs/fiddles/features/window-customization/custom-title-bar/starter-code (34.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 (34.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()
})

윈도우와 리눅스에서 네이티브 윈도우 컨트롤 추가​

macOS에서는 titleBarStyle: 'hidden'을 설정하면 제목 표시줄이 사라지지만, 창의 트래픽 라이트 컨트롤은 왼쪽 상단에 그대로 남아 있다. 그러나 윈도우와 리눅스에서는 BrowserWindow 생성자에서 BaseWindowContructorOptions의 titleBarOverlay 매개변수를 설정해 윈도우 컨트롤을 다시 추가해야 한다.

docs/fiddles/features/window-customization/custom-title-bar/native-window-controls (34.1.1)Open in 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에 윈도우 컨트롤을 다시 노출시키는 가장 간단한 방법이다. 윈도우 컨트롤을 더 자세히 커스터마이징하고 싶다면, Custom traffic lights와 Custom window controls 섹션을 참고하면 된다. 이 섹션에서는 이 주제를 더 깊이 다룬다.

커스텀 타이틀 바 만들기​

이제 BrowserWindow의 webContents에 간단한 커스텀 타이틀 바를 구현해 보자. 여기서는 HTML과 CSS만 사용한다!

docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar (34.1.1)Open in 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.1.1)Open in 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()
// 트래픽 라이트를 숨김
win.setWindowButtonVisibility(false)
note

사용 가능한 API가 많기 때문에 이를 달성하는 방법도 다양하다. 예를 들어, frame: false와 win.setWindowButtonVisibility(true)를 함께 사용하면 titleBarStyle: 'hidden'을 설정한 것과 동일한 레이아웃 결과를 얻을 수 있다.

커스텀 윈도우 컨트롤​

Window Controls Overlay API는 웹 앱이 데스크톱에 설치되었을 때 타이틀 바 영역을 커스터마이징할 수 있게 해주는 웹 표준이다. Electron은 이 API를 BrowserWindow 생성자의 titleBarOverlay 옵션을 통해 제공한다. 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 환경 변수를 사용해 오버레이의 색상과 크기 값을 확인할 수 있다.