BaseWindow

윈도우를 생성하고 제어한다.

프로세스: Main

참고 BaseWindow는 단일 윈도우 내에서 여러 웹 뷰를 유연하게 구성할 수 있는 방법을 제공한다. 단일의 전체 크기 웹 뷰만 필요한 경우, BrowserWindow 클래스를 사용하는 것이 더 간단한 선택일 수 있다.

이 모듈은 app 모듈의 ready 이벤트가 발생할 때까지 사용할 수 없다.

// 메인 프로세스에서.
const { BaseWindow, WebContentsView } = require('electron')

const win = new BaseWindow({ width: 800, height: 600 })

const leftView = new WebContentsView()
leftView.webContents.loadURL('https://electronjs.org')
win.contentView.addChildView(leftView)

const rightView = new WebContentsView()
rightView.webContents.loadURL('https://github.com/electron/electron')
win.contentView.addChildView(rightView)

leftView.setBounds({ x: 0, y: 0, width: 400, height: 600 })
rightView.setBounds({ x: 400, y: 0, width: 400, height: 600 })

부모와 자식 윈도우

parent 옵션을 사용하면 자식 윈도우를 생성할 수 있다:

const { BaseWindow } = require('electron')

const parent = new BaseWindow()
const child = new BaseWindow({ parent })

child 윈도우는 항상 parent 윈도우 위에 표시된다.

모달 윈도우

모달 윈도우는 부모 윈도우를 비활성화하는 자식 윈도우다. 모달 윈도우를 생성하려면 parent와 modal 옵션을 모두 설정해야 한다:

const { BaseWindow } = require('electron')

const parent = new BaseWindow()
const child = new BaseWindow({ parent, modal: true })

플랫폼별 주의사항

• macOS에서는 모달 윈도우가 부모 윈도우에 부착된 시트 형태로 표시된다.
• macOS에서는 자식 윈도우가 부모 윈도우의 상대적 위치를 유지하며, 부모 윈도우가 이동할 때 함께 움직인다. 반면 Windows와 Linux에서는 자식 윈도우가 움직이지 않는다.
• Linux에서는 모달 윈도우의 타입이 dialog로 변경된다.
• Linux의 많은 데스크톱 환경에서는 모달 윈도우를 숨기는 기능을 지원하지 않는다.

리소스 관리

BaseWindow에 WebContentsView를 추가하고 BaseWindow가 닫힐 때, WebContentsView의 webContents는 자동으로 파괴되지 않는다.

BaseWindow가 닫힌 경우와 같이 더 이상 webContents가 필요하지 않을 때, 직접 webContents를 닫는 것이 여러분의 책임이다.

const { BaseWindow, WebContentsView } = require('electron')

const win = new BaseWindow({ width: 800, height: 600 })

const view = new WebContentsView()
win.contentView.addChildView(view)

win.on('closed', () => {
  view.webContents.close()
})

BrowserWindow와 달리, 명시적으로 webContents를 닫지 않으면 메모리 누수가 발생할 수 있다.

Class: BaseWindow

윈도우를 생성하고 제어한다.

프로세스: 메인

BaseWindow는 EventEmitter이다.

options로 설정된 네이티브 속성을 가진 새로운 BaseWindow를 생성한다.

new BaseWindow([options])

• options BaseWindowConstructorOptions (옵션)
  • width Integer (선택 사항) - 윈도우의 너비를 픽셀 단위로 지정한다. 기본값은 800이다.
  • height Integer (선택 사항) - 윈도우의 높이를 픽셀 단위로 지정한다. 기본값은 600이다.
  • x Integer (선택 사항) - (y를 사용할 경우 필수) 화면 왼쪽에서 윈도우의 오프셋을 지정한다. 기본값은 윈도우를 화면 중앙에 배치한다.
  • y Integer (선택 사항) - (x를 사용할 경우 필수) 화면 상단에서 윈도우의 오프셋을 지정한다. 기본값은 윈도우를 화면 중앙에 배치한다.
  • useContentSize boolean (선택 사항) - width와 height를 웹 페이지의 크기로 사용한다. 실제 윈도우 크기는 윈도우 프레임의 크기를 포함해 약간 더 커진다. 기본값은 false이다.
  • center boolean (선택 사항) - 윈도우를 화면 중앙에 표시한다. 기본값은 false이다.
  • minWidth Integer (선택 사항) - 윈도우의 최소 너비를 지정한다. 기본값은 0이다.
  • minHeight Integer (선택 사항) - 윈도우의 최소 높이를 지정한다. 기본값은 0이다.
  • maxWidth Integer (선택 사항) - 윈도우의 최대 너비를 지정한다. 기본값은 제한이 없다.
  • maxHeight Integer (선택 사항) - 윈도우의 최대 높이를 지정한다. 기본값은 제한이 없다.
  • resizable boolean (선택 사항) - 윈도우 크기 조절 가능 여부를 지정한다. 기본값은 true이다.
  • movable boolean (선택 사항) macOS Windows - 윈도우 이동 가능 여부를 지정한다. Linux에서는 구현되지 않는다. 기본값은 true이다.
  • minimizable boolean (선택 사항) macOS Windows - 윈도우 최소화 가능 여부를 지정한다. Linux에서는 구현되지 않는다. 기본값은 true이다.
  • maximizable boolean (선택 사항) macOS Windows - 윈도우 최대화 가능 여부를 지정한다. Linux에서는 구현되지 않는다. 기본값은 true이다.
  • closable boolean (선택 사항) macOS Windows - 윈도우 닫기 가능 여부를 지정한다. Linux에서는 구현되지 않는다. 기본값은 true이다.
  • focusable boolean (선택 사항) - 윈도우 포커스 가능 여부를 지정한다. 기본값은 true이다. Windows에서 focusable: false로 설정하면 skipTaskbar: true도 함께 설정된다. Linux에서 focusable: false로 설정하면 윈도우가 wm과 상호작용하지 않아 모든 작업 공간에서 항상 최상위에 위치한다.
  • alwaysOnTop boolean (선택 사항) - 윈도우가 항상 다른 윈도우 위에 위치할지 여부를 지정한다. 기본값은 false이다.
  • fullscreen boolean (선택 사항) - 윈도우를 전체 화면으로 표시할지 여부를 지정한다. macOS에서 명시적으로 false로 설정하면 전체 화면 버튼이 숨겨지거나 비활성화된다. 기본값은 false이다.
  • fullscreenable boolean (선택 사항) - 윈도우를 전체 화면 모드로 전환할 수 있는지 여부를 지정한다. macOS에서는 최대화/확대 버튼이 전체 화면 모드와 윈도우 최대화를 전환할지 여부도 결정한다. 기본값은 true이다.
  • simpleFullscreen boolean (선택 사항) macOS - macOS에서 Lion 이전의 전체 화면 모드를 사용한다. 기본값은 false이다.
  • skipTaskbar boolean (선택 사항) macOS Windows - 윈도우를 작업 표시줄에 표시할지 여부를 지정한다. 기본값은 false이다.
  • hiddenInMissionControl boolean (선택 사항) macOS - 사용자가 미션 컨트롤로 전환할 때 윈도우를 숨길지 여부를 지정한다.
  • kiosk boolean (선택 사항) - 윈도우가 키오스크 모드인지 여부를 지정한다. 기본값은 false이다.
  • title string (선택 사항) - 기본 윈도우 제목을 지정한다. 기본값은 "Electron"이다. loadURL()로 로드된 HTML 파일에 <title> 태그가 정의되어 있으면 이 속성은 무시된다.
  • icon (NativeImage | string) (선택 사항) - 윈도우 아이콘을 지정한다. Windows에서는 ICO 아이콘을 사용해 최상의 시각적 효과를 얻을 수 있으며, 정의하지 않으면 실행 파일의 아이콘이 사용된다.
  • show boolean (선택 사항) - 윈도우 생성 시 표시할지 여부를 지정한다. 기본값은 true이다.
  • frame boolean (선택 사항) - false로 설정하면 프레임 없는 윈도우를 생성한다. 기본값은 true이다.
  • parent BaseWindow (선택 사항) - 부모 윈도우를 지정한다. 기본값은 null이다.
  • modal boolean (선택 사항) - 이 윈도우가 모달 윈도우인지 여부를 지정한다. 이 옵션은 윈도우가 자식 윈도우일 때만 작동한다. 기본값은 false이다.
  • acceptFirstMouse boolean (선택 사항) macOS - 비활성화된 윈도우를 클릭할 때 웹 콘텐츠까지 클릭이 전달될지 여부를 지정한다. macOS에서 기본값은 false이며, 다른 플랫폼에서는 설정할 수 없다.
  • disableAutoHideCursor boolean (선택 사항) - 타이핑 시 커서를 숨길지 여부를 지정한다. 기본값은 false이다.
  • autoHideMenuBar boolean (선택 사항) - Alt 키를 누르지 않으면 메뉴 바를 자동으로 숨긴다. 기본값은 false이다.
  • enableLargerThanScreen boolean (선택 사항) macOS - 윈도우를 화면보다 크게 조절할 수 있게 한다. macOS에서만 유효하며, 다른 OS는 기본적으로 화면보다 큰 윈도우를 허용한다. 기본값은 false이다.
  • backgroundColor string (선택 사항) - 윈도우의 배경색을 Hex, RGB, RGBA, HSL, HSLA 또는 CSS 색상 이름 형식으로 지정한다. transparent가 true로 설정된 경우 #AARRGGBB 형식의 알파 값을 지원한다. 기본값은 #FFF(흰색)이다. 자세한 내용은 win.setBackgroundColor을 참고한다.
  • hasShadow boolean (선택 사항) - 윈도우에 그림자를 표시할지 여부를 지정한다. 기본값은 true이다.
  • opacity number (선택 사항) macOS Windows - 윈도우의 초기 투명도를 0.0(완전 투명)에서 1.0(완전 불투명) 사이로 설정한다. Windows와 macOS에서만 구현된다.
  • darkTheme boolean (선택 사항) - 윈도우에 다크 테마를 강제로 적용한다. 일부 GTK+3 데스크톱 환경에서만 작동한다. 기본값은 false이다.
  • transparent boolean (선택 사항) - 윈도우를 투명하게 만든다. 기본값은 false이다. Windows에서는 프레임 없는 윈도우에서만 작동한다.
  • type string (선택 사항) - 윈도우 타입을 지정한다. 기본값은 일반 윈도우이다. 자세한 내용은 아래를 참고한다.
  • visualEffectState string (선택 사항) macOS - macOS에서 윈도우 활동 상태에 따라 재질 외관이 어떻게 반영될지 지정한다. vibrancy 속성과 함께 사용해야 한다. 가능한 값은 다음과 같다:
    • followWindow - 윈도우가 활성화되면 배경이 자동으로 활성화되고, 비활성화되면 비활성화된다. 기본값이다.
    • active - 배경이 항상 활성화된 상태로 유지된다.
    • inactive - 배경이 항상 비활성화된 상태로 유지된다.
  • titleBarStyle string (선택 사항) - 윈도우 타이틀 바 스타일을 지정한다. 기본값은 default이다. 가능한 값은 다음과 같다:
    • default - macOS 또는 Windows의 표준 타이틀 바를 사용한다.
    • hidden - 타이틀 바를 숨기고 콘텐츠 창을 전체 크기로 표시한다. macOS에서는 여전히 왼쪽 상단에 표준 윈도우 컨트롤("트래픽 라이트")이 표시된다. Windows와 Linux에서 titleBarOverlay: true와 함께 사용하면 Window Controls Overlay가 활성화되고, 그렇지 않으면 윈도우 컨트롤이 표시되지 않는다.
    • hiddenInset macOS - 타이틀 바를 숨기고 트래픽 라이트 버튼이 윈도우 가장자리에서 약간 안쪽으로 들어간 대체 스타일을 사용한다.
    • customButtonsOnHover macOS - 타이틀 바를 숨기고 콘텐츠 창을 전체 크기로 표시하며, 윈도우 왼쪽 상단을 호버할 때 트래픽 라이트 버튼이 표시된다. 참고: 이 옵션은 현재 실험적이다.
  • titleBarOverlay Object | Boolean (선택 사항) - macOS에서 win.setWindowButtonVisibility(true)와 함께 프레임 없는 윈도우를 사용하거나 titleBarStyle을 사용해 표준 윈도우 컨트롤("트래픽 라이트" on macOS)이 표시될 때, 이 속성은 Window Controls Overlay JavaScript APIs와 CSS Environment Variables를 활성화한다. true로 지정하면 기본 시스템 색상으로 오버레이가 표시된다. 기본값은 false이다.
    • color String (선택 사항) Windows Linux - Window Controls Overlay의 CSS 색상을 지정한다. 기본값은 시스템 색상이다.
    • symbolColor String (선택 사항) Windows - Window Controls Overlay의 심볼 CSS 색상을 지정한다. 기본값은 시스템 색상이다.
    • height Integer (선택 사항) - 타이틀 바와 Window Controls Overlay의 높이를 픽셀 단위로 지정한다. 기본값은 시스템 높이이다.
  • trafficLightPosition Point (선택 사항) macOS - 프레임 없는 윈도우에서 트래픽 라이트 버튼의 위치를 지정한다.
  • roundedCorners boolean (선택 사항) macOS - 프레임 없는 윈도우의 모서리를 둥글게 할지 여부를 지정한다. 기본값은 true이다. 이 속성을 false로 설정하면 윈도우를 전체 화면으로 전환할 수 없다.
  • thickFrame boolean (선택 사항) - Windows에서 프레임 없는 윈도우에 WS_THICKFRAME 스타일을 사용해 표준 윈도우 프레임을 추가한다. false로 설정하면 윈도우 그림자와 애니메이션이 제거된다. 기본값은 true이다.
  • vibrancy string (선택 사항) macOS - 윈도우에 특정 유형의 비브란시 효과를 추가한다. macOS에서만 사용할 수 있다. 가능한 값은 appearance-based, titlebar, selection, menu, popover, sidebar, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, under-page이다.
  • backgroundMaterial string (선택 사항) Windows - 윈도우의 시스템 그려진 배경 재질을 설정한다. 비클라이언트 영역 뒤에도 적용된다. 가능한 값은 auto, none, mica, acrylic, tabbed이다. 자세한 내용은 win.setBackgroundMaterial을 참고한다.
  • zoomToPageWidth boolean (선택 사항) macOS - macOS에서 툴바의 녹색 정지 버튼을 옵션 클릭하거나 Window > Zoom 메뉴 항목을 클릭할 때의 동작을 제어한다. true로 설정하면 확대 시 웹 페이지의 기본 너비로 윈도우가 확대되고, false로 설정하면 화면 너비로 확대된다. 이 설정은 maximize()를 직접 호출할 때도 영향을 미친다. 기본값은 false이다.
  • tabbingIdentifier string (선택 사항) macOS - 탭 그룹 이름을 지정해 윈도우를 네이티브 탭으로 열 수 있게 한다. 동일한 탭 그룹 식별자를 가진 윈도우는 함께 그룹화된다. 또한 윈도우 탭 바에 네이티브 새 탭 버튼이 추가되고 app과 윈도우가 new-window-for-tab 이벤트를 받을 수 있게 된다.

  minWidth/maxWidth/minHeight/maxHeight로 윈도우의 최소 또는 최대 크기를 설정할 때, 이는 사용자만 제한한다. setBounds/setSize 또는 BrowserWindow 생성자에 크기 제약을 따르지 않는 크기를 전달하는 것을 막지는 않는다.

  type 옵션의 가능한 값과 동작은 플랫폼에 따라 다르다. 가능한 값은 다음과 같다:

  • Linux에서 가능한 타입은 desktop, dock, toolbar, splash, notification이다.
    • desktop 타입은 윈도우를 데스크톱 배경 윈도우 레벨(kCGDesktopWindowLevel - 1)에 배치한다. 하지만 데스크톱 윈도우는 포커스, 키보드, 마우스 이벤트를 받지 않는다. globalShortcut을 사용해 간헐적으로 입력을 받을 수 있다.
    • dock 타입은 독(Dock)과 유사한 윈도우 동작을 생성한다.
    • toolbar 타입은 툴바 형태의 윈도우를 생성한다.
    • splash 타입은 특정 방식으로 동작한다. 윈도우 본문의 CSS 스타일에 -webkit-app-region: drag가 포함되어 있어도 드래그할 수 없다. 이 타입은 주로 스플래시 스크린에 사용된다.
    • notification 타입은 시스템 알림과 유사한 동작을 하는 윈도우를 생성한다.
  • macOS에서 가능한 타입은 desktop, textured, panel이다.
    • textured 타입은 금속 그라데이션 외관을 추가한다. 이 옵션은 더 이상 사용되지 않는다.
    • desktop 타입은 윈도우를 데스크톱 배경 윈도우 레벨(kCGDesktopWindowLevel - 1)에 배치한다. 데스크톱 윈도우는 포커스, 키보드, 마우스 이벤트를 받지 않지만 globalShortcut을 사용해 간헐적으로 입력을 받을 수 있다.
    • panel 타입은 런타임에 NSWindowStyleMaskNonactivatingPanel 스타일 마스크를 추가해 윈도우가 전체 화면 앱 위에 떠 있게 한다. 일반적으로 NSPanel에 예약된 스타일이며, 윈도우는 모든 스페이스(데스크톱)에 나타난다.
  • Windows에서 가능한 타입은 toolbar이다.

인스턴스 이벤트

new BaseWindow로 생성된 객체는 다음과 같은 이벤트를 발생시킨다:

참고: 일부 이벤트는 특정 운영체제에서만 사용할 수 있으며, 해당 이벤트에는 이를 명시해 두었다.

이벤트: 'close'

반환값:

• event Event

이 이벤트는 윈도우가 닫히기 직전에 발생한다. DOM의 beforeunload와 unload 이벤트보다 먼저 발생한다. event.preventDefault()를 호출하면 윈도우 닫기를 취소할 수 있다.

일반적으로 윈도우를 닫을지 여부를 결정하기 위해 beforeunload 핸들러를 사용한다. 이 핸들러는 윈도우가 다시 로드될 때도 호출된다. Electron에서는 undefined가 아닌 값을 반환하면 윈도우 닫기가 취소된다. 예를 들어:

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed')

  // 일반 브라우저에서는 사용자에게 메시지 박스가 표시되지만, 여기서는
  // non-void 값을 반환하면 윈도우 닫기가 조용히 취소된다.
  // 애플리케이션 종료를 사용자가 확인할 수 있도록 다이얼로그 API를 사용하는 것이 권장된다.
  e.returnValue = false
}

참고: window.onbeforeunload = handler와 window.addEventListener('beforeunload', handler)의 동작에는 미묘한 차이가 있다. Electron 내에서 더 일관되게 동작하려면 값을 반환하는 대신 event.returnValue를 명시적으로 설정하는 것이 좋다.

이벤트: 'closed'

윈도우가 닫힐 때 발생하는 이벤트다. 이 이벤트를 받은 후에는 해당 윈도우에 대한 참조를 제거하고 더 이상 사용하지 않아야 한다.

이벤트: 'session-end' Windows

윈도우 세션이 강제 종료, 시스템 재시작, 또는 세션 로그오프로 인해 종료될 때 발생한다.

이벤트: 'blur'

반환값:

• event Event

윈도우가 포커스를 잃을 때 발생한다.

이벤트: 'focus'

반환값:

• event Event

윈도우가 포커스를 얻을 때 발생한다.

이벤트: 'show'

윈도우가 표시될 때 발생한다.

이벤트: 'hide'

윈도우가 숨겨질 때 발생한다.

이벤트: 'maximize'

윈도우가 최대화될 때 발생한다.

이벤트: 'unmaximize'

윈도우가 최대화 상태에서 벗어날 때 발생한다.

이벤트: 'minimize'

이 이벤트는 윈도우가 최소화될 때 발생한다.

이벤트: 'restore'

윈도우가 최소화 상태에서 복원될 때 발생한다.

이벤트: 'will-resize' macOS Windows

반환값:

• event Event
• newBounds Rectangle - 윈도우가 조정될 크기.
• details Object
  • edge (string) - 윈도우 크기 조정을 위해 드래그 중인 가장자리. bottom, left, right, top-left, top-right, bottom-left, bottom-right 중 하나일 수 있다.

윈도우 크기가 조정되기 전에 발생한다. event.preventDefault()를 호출하면 윈도우 크기 조정을 막을 수 있다.

이 이벤트는 윈도우를 수동으로 조정할 때만 발생한다. setBounds/setSize를 사용해 윈도우 크기를 조정할 때는 이 이벤트가 발생하지 않는다.

edge 옵션의 가능한 값과 동작은 플랫폼에 따라 다르다. 가능한 값은 다음과 같다:

• Windows에서는 bottom, top, left, right, top-left, top-right, bottom-left, bottom-right가 가능하다.
• macOS에서는 bottom과 right가 가능하다.
  • bottom 값은 세로 크기 조정을 의미한다.
  • right 값은 가로 크기 조정을 의미한다.

이벤트: 'resize'

윈도우 크기가 조정된 후에 발생하는 이벤트이다.

이벤트: 'resized' macOS Windows

윈도우 크기 조정이 완료되면 한 번 발생하는 이벤트다.

일반적으로 윈도우를 수동으로 크기 조정했을 때 이 이벤트가 발생한다. macOS에서는 setBounds나 setSize를 사용해 윈도우 크기를 조정할 때 animate 매개변수를 true로 설정하면, 크기 조정이 끝난 후 이 이벤트가 한 번 발생한다.

이벤트: 'will-move' macOS Windows

반환값:

• event Event
• newBounds Rectangle - 윈도우가 이동될 위치

윈도우가 이동되기 전에 발생한다. 윈도우에서 event.preventDefault()를 호출하면 윈도우 이동을 막을 수 있다.

이 이벤트는 윈도우를 수동으로 이동할 때만 발생한다. setPosition, setBounds, center를 사용해 윈도우를 이동할 때는 이 이벤트가 발생하지 않는다.

이벤트: 'move'

윈도우가 새로운 위치로 이동할 때 발생하는 이벤트다.

이벤트: 'moved' macOS Windows

윈도우가 새로운 위치로 이동했을 때 한 번 발생한다.

참고: macOS에서는 이 이벤트가 move의 별칭이다.

이벤트: 'enter-full-screen'

윈도우가 전체 화면 상태로 전환될 때 발생한다.

이벤트: 'leave-full-screen'

윈도우가 전체 화면 상태에서 빠져나올 때 발생한다.

이벤트: 'always-on-top-changed'

반환값:

• event Event
• isAlwaysOnTop boolean

윈도우가 다른 윈도우 위에 항상 표시되도록 설정되거나 해제될 때 발생한다.

이벤트: 'app-command' Windows Linux

반환값:

• event Event
• command string

App Command가 호출될 때 발생한다. 이 이벤트는 일반적으로 키보드 미디어 키나 브라우저 명령, 그리고 일부 마우스에 내장된 "뒤로 가기" 버튼과 관련이 있다.

명령어는 소문자로 변환되고, 언더스코어는 하이픈으로 대체되며, APPCOMMAND_ 접두사는 제거된다. 예를 들어, APPCOMMAND_BROWSER_BACKWARD는 browser-backward로 발생한다.

const { BaseWindow } = require('electron')
const win = new BaseWindow()
win.on('app-command', (e, cmd) => {
  // 사용자가 마우스 뒤로 가기 버튼을 누르면 윈도우를 뒤로 이동
  if (cmd === 'browser-backward') {
    // 적절한 WebContents를 찾아 네비게이션 수행
  }
})

Linux에서 명시적으로 지원되는 app 명령어는 다음과 같다:

• browser-backward
• browser-forward

이벤트: 'swipe' macOS

반환값:

• event Event
• direction string

이 이벤트는 3손가락 스와이프 동작 시 발생한다. 가능한 방향은 up, right, down, left이다.

이 이벤트의 기반이 되는 메서드는 오래된 macOS 스타일 트랙패드 스와이프를 처리하도록 설계되었다. 이 방식에서는 화면의 콘텐츠가 스와이프와 함께 움직이지 않는다. 대부분의 macOS 트랙패드는 더 이상 이런 종류의 스와이프를 허용하도록 설정되어 있지 않다. 따라서 이 이벤트가 올바르게 발생하려면 시스템 환경설정 > 트랙패드 > 추가 제스처에서 '페이지 간 스와이프' 설정을 '두 손가락 또는 세 손가락으로 스와이프'로 변경해야 한다.

이벤트: 'rotate-gesture' macOS

반환값:

• event Event
• rotation Float

트랙패드 회전 제스처가 발생할 때 이벤트가 발생한다. 회전 제스처가 끝날 때까지 지속적으로 이벤트가 발생한다. 각 이벤트에서 rotation 값은 마지막 이벤트 이후 회전한 각도를 나타낸다. 회전 제스처가 끝날 때 마지막으로 발생하는 이벤트의 rotation 값은 항상 0이다. 반시계 방향 회전은 양수 값으로, 시계 방향 회전은 음수 값으로 표현된다.

이벤트: 'sheet-begin' macOS

윈도우가 시트를 열 때 발생하는 이벤트다.

이벤트: 'sheet-end' macOS

윈도우가 시트를 닫았을 때 발생한다.

이벤트: 'new-window-for-tab' macOS

네이티브 새 탭 버튼을 클릭할 때 발생한다.

이벤트: 'system-context-menu' Windows

반환값:

• event Event
• point Point - 컨텍스트 메뉴가 트리거된 화면 좌표

시스템 컨텍스트 메뉴가 윈도우에서 트리거될 때 발생한다. 일반적으로 사용자가 윈도우의 비클라이언트 영역에서 오른쪽 클릭할 때만 트리거된다. 이는 윈도우 제목 표시줄 또는 프레임리스 윈도우에서 -webkit-app-region: drag로 선언한 영역을 의미한다.

event.preventDefault()를 호출하면 메뉴가 표시되지 않도록 할 수 있다.

정적 메서드

BaseWindow 클래스는 다음과 같은 정적 메서드를 제공한다:

BaseWindow.getAllWindows()

BaseWindow[] 타입을 반환한다. 현재 열려 있는 모든 브라우저 윈도우의 배열을 가져온다.

BaseWindow.getFocusedWindow()

BaseWindow | null 타입의 값을 반환한다. 현재 애플리케이션에서 포커스된 윈도우를 반환하며, 포커스된 윈도우가 없을 경우 null을 반환한다.

BaseWindow.fromId(id)

• id Integer

BaseWindow | null을 반환한다. 주어진 id에 해당하는 윈도우를 찾아 반환한다.

인스턴스 속성

new BaseWindow로 생성된 객체는 다음과 같은 속성을 가진다:

const { BaseWindow } = require('electron')
// 이 예제에서 `win`은 우리의 인스턴스다
const win = new BaseWindow({ width: 800, height: 600 })

win.id 읽기 전용

이 속성은 윈도우의 고유 ID를 나타내는 정수(Integer) 타입이다. 이 ID는 전체 Electron 애플리케이션 내의 모든 BaseWindow 인스턴스 중에서 유일한 값을 가진다.

win.contentView

윈도우의 콘텐츠 뷰를 나타내는 View 프로퍼티이다.

win.tabbingIdentifier macOS 읽기 전용

tabbingIdentifier는 BrowserWindow 생성자에 전달된 문자열(선택적) 속성이다. 만약 설정되지 않았다면 undefined 값을 가진다.

win.autoHideMenuBar

이 boolean 타입의 속성은 윈도우의 메뉴 바가 자동으로 숨겨질지 여부를 결정한다. 이 속성을 설정하면, 사용자가 Alt 키를 누를 때만 메뉴 바가 표시된다.

만약 메뉴 바가 이미 보이는 상태에서 이 속성을 true로 설정하더라도, 메뉴 바가 즉시 숨겨지지는 않는다.

win.simpleFullScreen은 윈도우가 간단한 (Lion 이전) 전체 화면 모드인지 여부를 결정하는 불리언 타입의 속성이다.

win.fullScreen은 윈도우가 전체 화면 모드인지 여부를 결정하는 불리언 타입의 속성이다.

win.focusable Windows macOS

boolean 타입의 속성으로, 윈도우가 포커스를 받을 수 있는지 여부를 결정한다.

win.visibleOnAllWorkspaces macOS Linux

boolean 타입의 속성으로, 윈도우가 모든 작업 공간에 표시될지 여부를 결정한다.

참고: 윈도우에서는 항상 false를 반환한다.

win.shadow

윈도우에 그림자가 있는지 여부를 결정하는 boolean 타입의 프로퍼티이다.

win.menuBarVisible Windows Linux

메뉴 바의 가시성을 결정하는 boolean 타입의 속성이다.

참고: 메뉴 바가 자동 숨김 상태일 때, 사용자는 단일 Alt 키를 눌러 메뉴 바를 다시 표시할 수 있다.

win.kiosk

boolean 타입의 프로퍼티로, 윈도우가 키오스크 모드인지 여부를 결정한다.

win.documentEdited macOS

윈도우의 문서가 편집되었는지 여부를 지정하는 boolean 타입의 속성이다.

이 값을 true로 설정하면 타이틀 바의 아이콘이 회색으로 변한다.

win.representedFilename macOS

윈도우가 나타내는 파일의 경로명을 결정하는 string 타입의 프로퍼티다. 이 파일의 아이콘은 윈도우의 제목 표시줄에 표시된다.

win.title

win.title은 네이티브 윈도우의 제목을 결정하는 문자열(string) 속성이다.

참고: 웹 페이지의 제목과 네이티브 윈도우의 제목은 서로 다를 수 있다.

win.minimizable macOS Windows

boolean 타입의 속성으로, 사용자가 윈도우를 수동으로 최소화할 수 있는지 여부를 결정한다.

리눅스에서는 이 속성을 설정해도 아무런 동작을 하지 않지만, 값을 가져올 때는 true를 반환한다.

win.maximizable macOS Windows

boolean 타입의 프로퍼티로, 사용자가 윈도우를 수동으로 최대화할 수 있는지 여부를 결정한다.

리눅스에서는 설정자(setter)가 동작하지 않지만, 게터(getter)는 true를 반환한다.

win.fullScreenable

이 boolean 타입의 프로퍼티는 최대화/확대 버튼이 전체 화면 모드로 전환할지, 아니면 윈도우를 최대화할지를 결정한다.

win.resizable은 사용자가 윈도우의 크기를 직접 조정할 수 있는지 여부를 결정하는 불리언 타입의 속성이다. 이 값을 true로 설정하면 사용자가 윈도우의 크기를 조절할 수 있고, false로 설정하면 크기 조절이 불가능하다.

win.closable macOS Windows

이 속성은 사용자가 직접 윈도우를 닫을 수 있는지 여부를 결정하는 boolean 타입의 값이다.

리눅스에서는 설정자(setter)가 아무런 동작을 하지 않지만, 게터(getter)는 true를 반환한다.

win.movable macOS Windows

boolean 타입의 속성으로, 사용자가 윈도우를 이동할 수 있는지 여부를 결정한다.

Linux에서는 설정자(setter)가 동작하지 않지만, 값은 true를 반환한다.

win.excludedFromShownWindowsMenu macOS

이 boolean 속성은 윈도우가 애플리케이션의 Windows 메뉴에서 제외될지 여부를 결정한다. 기본값은 false이다.

const { Menu, BaseWindow } = require('electron')
const win = new BaseWindow({ height: 600, width: 600 })

const template = [
  {
    role: 'windowmenu'
  }
]

win.excludedFromShownWindowsMenu = true

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

win.accessibleTitle

win.accessibleTitle은 스크린 리더와 같은 접근성 도구에만 제공되는 대체 제목을 정의하는 string 타입의 프로퍼티이다. 이 문자열은 사용자에게 직접 보이지 않는다.

인스턴스 메서드

new BaseWindow로 생성된 객체는 다음과 같은 인스턴스 메서드를 제공한다.

참고: 일부 메서드는 특정 운영체제에서만 사용 가능하며, 해당 메서드는 별도로 표시되어 있다.

win.setContentView(view)

• view View

윈도우의 콘텐츠 뷰를 설정한다.

win.getContentView()

View를 반환한다. 윈도우의 컨텐츠 뷰를 가져온다.

win.destroy()

윈도우를 강제로 닫는다. 이 경우 웹 페이지에서 unload와 beforeunload 이벤트가 발생하지 않으며, 해당 윈도우에서 close 이벤트도 발생하지 않는다. 하지만 closed 이벤트는 반드시 발생한다.

win.close()

윈도우를 닫으려고 시도한다. 이 기능은 사용자가 직접 윈도우의 닫기 버튼을 클릭하는 것과 동일한 효과를 낸다. 하지만 웹 페이지가 닫기를 취소할 수도 있다. 자세한 내용은 close 이벤트를 참고한다.

win.focus()

윈도우에 포커스를 설정한다.

win.blur()

윈도우에서 포커스를 제거한다.

win.isFocused()

boolean을 반환한다. 윈도우가 현재 포커스 상태인지 여부를 나타낸다.

win.isDestroyed()

boolean 타입을 반환한다. 윈도우가 파괴되었는지 여부를 나타낸다.

win.show()

윈도우를 보여주고 포커스를 준다.

win.showInactive()

윈도우를 보여주지만 포커스를 주지 않는다.

win.hide()

윈도우를 숨긴다.

win.isVisible()

boolean 타입의 값을 반환한다. 이 값은 윈도우가 앱의 전경에서 사용자에게 보이는지 여부를 나타낸다.

win.isModal()

boolean 타입의 값을 반환한다. 현재 윈도우가 모달 윈도우인지 여부를 나타낸다.

win.maximize()

윈도우를 최대화한다. 현재 윈도우가 화면에 표시되지 않았다면, 윈도우를 표시하지만 포커스는 주지 않는다.

win.unmaximize()

윈도우의 최대화 상태를 해제한다.

win.isMaximized()

boolean 값을 반환한다. 윈도우가 최대화 상태인지 여부를 나타낸다.

win.minimize()

윈도우를 최소화한다. 일부 플랫폼에서는 최소화된 윈도우가 Dock에 표시된다.

win.restore()

윈도우를 최소화된 상태에서 이전 상태로 복원한다.

win.isMinimized()

boolean 타입의 값을 반환한다. 윈도우가 최소화되었는지 여부를 나타낸다.

win.setFullScreen(flag)

• flag boolean

윈도우를 전체 화면 모드로 설정할지 여부를 결정한다.

참고: macOS에서는 전체 화면 전환이 비동기적으로 이루어진다. 전체 화면 상태에 따라 추가 작업을 수행해야 한다면 'enter-full-screen' 또는 'leave-full-screen' 이벤트를 사용한다.

win.isFullScreen()

boolean 타입의 값을 반환한다. 윈도우가 전체 화면 모드인지 여부를 나타낸다.

win.setSimpleFullScreen(flag) macOS

• flag boolean

단순 전체 화면 모드를 활성화하거나 비활성화한다.

단순 전체 화면 모드는 macOS Lion(10.7) 이전 버전의 네이티브 전체 화면 동작을 에뮬레이트한다.

win.isSimpleFullScreen() macOS

boolean 값을 반환한다. 윈도우가 (Lion 이전 버전의) 단순 전체 화면 모드인지 여부를 확인한다.

win.isNormal()

boolean 값을 반환한다. 윈도우가 일반 상태인지 여부를 확인한다. 일반 상태란 최대화, 최소화, 전체 화면 모드가 아닌 상태를 의미한다.

win.setAspectRatio(aspectRatio[, extraSize])

• aspectRatio Float - 콘텐츠 뷰의 일부 영역에 대해 유지할 화면 비율.
• extraSize Size (선택 사항) macOS - 화면 비율 계산에서 제외할 추가 크기.

이 함수는 윈도우가 특정 화면 비율을 유지하도록 설정한다. extraSize 매개변수는 개발자가 화면 비율 계산에서 제외할 공간을 픽셀 단위로 지정할 수 있게 해준다. 이 API는 윈도우 크기와 콘텐츠 크기 간의 차이를 이미 고려하고 있다.

HD 비디오 플레이어와 관련 컨트롤이 있는 일반적인 윈도우를 예로 들어보자. 플레이어 왼쪽 가장자리에 15픽셀, 오른쪽 가장자리에 25픽셀, 플레이어 아래쪽에 50픽셀의 컨트롤이 있다고 가정한다. 플레이어 자체 내에서 16:9 비율(HD @1920x1080의 표준 화면 비율)을 유지하려면 이 함수를 16/9와 { width: 40, height: 50 } 인자로 호출한다. 두 번째 인자는 추가 너비와 높이가 콘텐츠 뷰 내 어디에 위치하는지와는 상관없이, 단지 그 존재만을 고려한다. 전체 콘텐츠 뷰 내 추가 너비와 높이 영역을 모두 합산하면 된다.

win.setSize와 같은 API로 프로그래밍 방식으로 윈도우 크기를 조정할 때는 화면 비율이 적용되지 않는다.

화면 비율을 초기화하려면 aspectRatio 값으로 0을 전달한다: win.setAspectRatio(0).

win.setBackgroundColor(backgroundColor)

• backgroundColor string - Hex, RGB, RGBA, HSL, HSLA 또는 CSS 색상 이름 형식으로 색상을 지정한다. Hex 타입의 경우 알파 채널은 선택 사항이다.

유효한 backgroundColor 값의 예제:

• Hex
  • #fff (RGB 단축형)
  • #ffff (ARGB 단축형)
  • #ffffff (RGB)
  • #ffffffff (ARGB)
• RGB
  • rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)
    • 예: rgb(255, 255, 255)
• RGBA
  • rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)
    • 예: rgba(255, 255, 255, 1.0)
• HSL
  • hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)
    • 예: hsl(200, 20%, 50%)
• HSLA
  • hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)
    • 예: hsla(200, 20%, 50%, 0.5)
• 색상 이름
  • 사용 가능한 옵션은 SkParseColor.cpp에서 확인할 수 있다.
  • CSS Color Module Level 3 키워드와 유사하지만 대소문자를 구분한다.
    • 예: blueviolet 또는 red

윈도우의 배경색을 설정한다. 자세한 내용은 Setting backgroundColor를 참고한다.

win.previewFile(path[, displayName]) macOS

• path string - QuickLook으로 미리 보기할 파일의 절대 경로. QuickLook은 파일 경로의 이름과 확장자를 사용해 열 파일의 콘텐츠 타입을 결정하므로 이 값은 중요하다.
• displayName string (선택사항) - Quick Look 모달 뷰에 표시할 파일 이름. 이 값은 순전히 시각적인 용도이며 파일의 콘텐츠 타입에는 영향을 미치지 않는다. 기본값은 path이다.

주어진 경로의 파일을 Quick Look을 사용해 미리 본다.

win.closeFilePreview() macOS

현재 열려 있는 퀵 룩 패널을 닫는다.

win.setBounds(bounds[, animate])

• bounds Partial<Rectangle>
• animate boolean (선택 사항) macOS

윈도우의 크기와 위치를 지정한 범위로 조정한다. 제공하지 않은 속성은 현재 값을 그대로 유지한다.

const { BaseWindow } = require('electron')
const win = new BaseWindow()

// 모든 bounds 속성 설정
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// 단일 bounds 속성 설정
win.setBounds({ width: 100 })

// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())

참고: macOS에서는 y 좌표 값이 Tray 높이보다 작을 수 없다. Tray 높이는 시간이 지남에 따라 변경되었으며, 운영체제에 따라 다르지만 일반적으로 20-40px 사이이다. Tray 높이보다 작은 값을 전달하면 윈도우가 Tray에 딱 붙게 된다.

win.getBounds()

Rectangle 타입의 객체를 반환한다. 이 객체는 윈도우의 bounds를 나타낸다.

참고: macOS에서는 반환된 y 좌표 값이 최소 트레이 높이 이상이 된다. 예를 들어, 트레이 높이가 38일 때 win.setBounds({ x: 25, y: 20, width: 800, height: 600 })를 호출하면 win.getBounds()는 { x: 25, y: 38, width: 800, height: 600 }을 반환한다.

win.getBackgroundColor()

string 타입을 반환한다. 윈도우의 배경색을 Hex (#RRGGBB) 형식으로 가져온다.

자세한 내용은 backgroundColor 설정하기를 참고한다.

참고: 빨간색, 녹색, 파란색 값과 함께 알파 값은 반환되지 않는다.

win.setContentBounds(bounds[, animate])

• bounds Rectangle
• animate boolean (선택 사항) macOS

윈도우의 클라이언트 영역(예: 웹 페이지)을 지정된 크기와 위치로 조정하고 이동한다.

win.getContentBounds()

Rectangle 타입의 객체를 반환한다. 이 객체는 윈도우의 클라이언트 영역의 bounds를 나타낸다.

win.getNormalBounds()

Rectangle을 반환한다. 이는 윈도우의 일반 상태에서의 경계를 포함한다.

참고: 윈도우의 현재 상태(최대화, 최소화, 전체 화면 등)와 상관없이, 이 함수는 항상 윈도우의 일반 상태에서의 위치와 크기를 반환한다. 일반 상태에서는 getBounds와 getNormalBounds가 동일한 Rectangle을 반환한다.

win.setEnabled(enable)

• enable boolean

윈도우를 비활성화하거나 활성화한다.

win.isEnabled()

boolean 타입의 값을 반환한다. 윈도우가 활성화 상태인지 여부를 나타낸다.

win.setSize(width, height[, animate])

• width Integer
• height Integer
• animate boolean (선택 사항) macOS

윈도우의 크기를 width와 height로 조정한다. width나 height가 설정된 최소 크기 제한보다 작을 경우, 윈도우는 최소 크기로 고정된다.

win.getSize()

Integer[] 타입의 값을 반환한다. 이 값은 윈도우의 너비와 높이를 포함한다.

win.setContentSize(width, height[, animate])

• width Integer
• height Integer
• animate boolean (선택 사항) macOS

윈도우의 클라이언트 영역(예: 웹 페이지)을 지정한 width와 height로 크기를 조정한다.

win.getContentSize()

Integer[] 타입의 값을 반환한다. 이 배열은 윈도우의 클라이언트 영역 너비와 높이를 포함한다.

win.setMinimumSize(width, height)

• width Integer
• height Integer

윈도우의 최소 크기를 width와 height로 설정한다.

win.getMinimumSize()

Integer[] 타입을 반환한다. 윈도우의 최소 너비와 높이를 포함한다.

win.setMaximumSize(width, height)

• width Integer
• height Integer

윈도우의 최대 크기를 width와 height로 설정한다.

win.getMaximumSize()

Integer[] 타입의 값을 반환한다. 이 배열은 윈도우의 최대 너비와 높이를 포함한다.

win.setResizable(resizable)

• resizable boolean

사용자가 수동으로 윈도우 크기를 조절할 수 있는지 여부를 설정한다.

win.isResizable()

boolean 타입의 값을 반환한다. 이 값은 사용자가 직접 윈도우 크기를 조절할 수 있는지 여부를 나타낸다.

win.setMovable(movable) macOS Windows

• movable boolean

사용자가 윈도우를 이동할 수 있는지 여부를 설정한다. Linux에서는 아무런 동작을 하지 않는다.

win.isMovable() macOS Windows

boolean 값을 반환한다. 사용자가 윈도우를 이동할 수 있는지 여부를 나타낸다.

Linux에서는 항상 true를 반환한다.

win.setMinimizable(minimizable) macOS Windows

• minimizable boolean

사용자가 윈도우를 수동으로 최소화할 수 있는지 여부를 설정한다. Linux에서는 아무런 동작을 하지 않는다.

win.isMinimizable() macOS Windows

boolean 타입의 값을 반환한다. 이 값은 사용자가 직접 윈도우를 최소화할 수 있는지 여부를 나타낸다.

리눅스에서는 항상 true를 반환한다.

win.setMaximizable(maximizable) macOS Windows

• maximizable boolean

사용자가 윈도우를 수동으로 최대화할 수 있는지 여부를 설정한다. 리눅스에서는 아무런 동작을 하지 않는다.

win.isMaximizable() macOS Windows

boolean 값을 반환한다. 사용자가 윈도우를 수동으로 최대화할 수 있는지 여부를 나타낸다.

Linux에서는 항상 true를 반환한다.

win.setFullScreenable(fullscreenable)

• fullscreenable boolean

창의 최대화/확대 버튼이 전체 화면 모드로 전환할지, 아니면 창을 최대화할지 설정한다.

win.isFullScreenable()

boolean 값을 반환한다. 이 메서드는 윈도우의 최대화/확대 버튼이 전체 화면 모드를 전환할지, 아니면 윈도우를 최대화할지를 확인한다.

win.setClosable(closable) macOS Windows

• closable boolean

사용자가 윈도우를 수동으로 닫을 수 있는지 여부를 설정한다. Linux에서는 아무런 동작을 하지 않는다.

win.isClosable() macOS Windows

boolean 값을 반환한다. 사용자가 직접 윈도우를 닫을 수 있는지 여부를 나타낸다.

Linux에서는 항상 true를 반환한다.

win.setHiddenInMissionControl(hidden) macOS

• hidden boolean

사용자가 미션 컨트롤로 전환할 때 윈도우를 숨길지 여부를 설정한다.

win.isHiddenInMissionControl() macOS

boolean을 반환한다. 사용자가 미션 컨트롤로 전환할 때 해당 윈도우가 숨겨지는지 여부를 나타낸다.

win.setAlwaysOnTop(flag[, level][, relativeLevel])

• flag boolean
• level string (선택 사항) macOS Windows - 값으로는 normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver 그리고 dock (더 이상 사용되지 않음)이 포함된다. flag가 true일 때 기본값은 floating이다. flag가 false일 때 level은 normal로 재설정된다. floating부터 status까지는 macOS에서는 Dock 아래, Windows에서는 작업 표시줄 아래에 윈도우가 위치한다. pop-up-menu부터 더 높은 레벨은 macOS에서는 Dock 위, Windows에서는 작업 표시줄 위에 윈도우가 표시된다. 자세한 내용은 macOS 문서를 참고한다.
• relativeLevel Integer (선택 사항) macOS - 주어진 level에 상대적으로 이 윈도우를 몇 단계 위로 설정할지 지정한다. 기본값은 0이다. Apple은 screen-saver보다 1단계 이상 높은 레벨을 설정하는 것을 권장하지 않는다.

윈도우가 항상 다른 윈도우 위에 표시되도록 설정한다. 이 설정을 적용해도 윈도우는 여전히 일반 윈도우로 유지되며, 포커스를 받을 수 없는 툴박스 윈도우로 변하지 않는다.

win.isAlwaysOnTop()

boolean 타입을 반환한다. 윈도우가 다른 윈도우 위에 항상 표시되는지 여부를 나타낸다.

win.moveAbove(mediaSourceId)

• mediaSourceId string - 윈도우 ID. DesktopCapturerSource의 ID 형식으로 지정한다. 예를 들어 "window:1869:0"과 같은 형태다.

z-order 기준으로 현재 윈도우를 소스 윈도우 위로 이동한다. mediaSourceId가 윈도우 타입이 아니거나 해당 윈도우가 존재하지 않으면 이 메서드는 에러를 발생시킨다.

win.moveTop()

윈도우를 포커스 여부와 상관없이 z-order 상단으로 이동시킨다.

win.center()는 윈도우를 화면의 중앙으로 이동시킨다.

win.setPosition(x, y[, animate])

• x Integer
• y Integer
• animate boolean (선택 사항) macOS

윈도우를 지정된 x와 y 위치로 이동시킨다.

win.getPosition()

Integer[] 타입의 값을 반환한다. 이 값은 현재 윈도우의 위치를 나타낸다.

win.setTitle(title)

• title string

네이티브 윈도우의 제목을 title로 변경한다.

win.getTitle()

string 타입의 값을 반환한다. 이 값은 네이티브 윈도우의 제목을 나타낸다.

참고: 웹 페이지의 제목과 네이티브 윈도우의 제목은 서로 다를 수 있다.

win.setSheetOffset(offsetY[, offsetX]) macOS

• offsetY Float
• offsetX Float (선택 사항)

macOS에서 시트의 부착 위치를 변경한다. 기본적으로 시트는 윈도우 프레임 바로 아래에 부착되지만, HTML로 렌더링된 툴바 아래에 표시하고 싶을 수 있다. 예를 들면 다음과 같다:

const { BaseWindow } = require('electron')
const win = new BaseWindow()

const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)

win.flashFrame(flag)

History

Version(s)	Changes
None	window.flashFrame(bool) will flash dock icon continuously on macOS
None	API ADDED

• flag boolean

사용자의 주의를 끌기 위해 윈도우를 깜빡이게 하거나 멈춘다.

win.setSkipTaskbar(skip) macOS Windows

• skip boolean

윈도우가 작업 표시줄에 표시되지 않도록 설정한다.

win.setKiosk(flag)

• flag boolean

키오스크 모드를 활성화하거나 비활성화한다.

win.isKiosk()

boolean 타입을 반환한다. 현재 윈도우가 키오스크 모드인지 여부를 나타낸다.

win.isTabletMode() Windows

boolean을 반환한다. 윈도우가 Windows 10 태블릿 모드인지 여부를 나타낸다.

Windows 10 사용자는 PC를 태블릿처럼 사용할 수 있다. 이 모드에서 앱은 태블릿에 맞게 UI를 최적화할 수 있다. 예를 들어, 타이틀 바를 확대하거나 타이틀 바 버튼을 숨기는 등의 조정이 가능하다.

이 API는 윈도우가 태블릿 모드인지 여부를 반환한다. 또한 resize 이벤트를 통해 태블릿 모드 변경을 감지할 수 있다.

win.getMediaSourceId()

string 타입의 값을 반환한다. 이 값은 DesktopCapturerSource의 id 형식으로 윈도우 ID를 나타낸다. 예를 들어 "window:1324:0"과 같은 형태이다.

보다 정확히 말하면, 이 형식은 window:id:other_id이다. 여기서 id는 윈도우즈에서는 HWND, macOS에서는 CGWindowID (uint64_t), 리눅스에서는 Window (unsigned long)에 해당한다. other_id는 웹 콘텐츠(탭)를 식별하기 위해 사용되며, 동일한 최상위 윈도우 내에서 구분하는 역할을 한다.

win.getNativeWindowHandle()

Buffer를 반환한다. 이는 윈도우의 플랫폼별 핸들을 나타낸다.

핸들의 네이티브 타입은 다음과 같다:

• Windows에서는 HWND
• macOS에서는 NSView*
• Linux에서는 Window (unsigned long)

win.hookWindowMessage(message, callback) Windows

• message Integer
• callback Function
  • wParam Buffer - WndProc에 전달된 wParam
  • lParam Buffer - WndProc에 전달된 lParam

윈도우 메시지를 후킹한다. WndProc에서 메시지를 수신하면 callback이 호출된다.

win.isWindowMessageHooked(message) Windows

• message Integer

boolean을 반환한다. 메시지가 후킹되었는지 여부에 따라 true 또는 false를 반환한다.

win.unhookWindowMessage(message) Windows

• message Integer

윈도우 메시지 후킹을 해제한다.

win.unhookAllWindowMessages() Windows

모든 윈도우 메시지의 후킹을 해제한다.

win.setRepresentedFilename(filename) macOS

• filename string

윈도우가 나타내는 파일의 경로를 설정한다. 이 파일의 아이콘은 윈도우의 제목 표시줄에 표시된다.

win.getRepresentedFilename() macOS

string 타입을 반환한다. 이 메서드는 윈도우가 나타내는 파일의 경로명을 반환한다.

win.setDocumentEdited(edited) macOS

• edited boolean

윈도우의 문서가 편집되었는지 여부를 지정한다. true로 설정하면 타이틀 바의 아이콘이 회색으로 변한다.

win.isDocumentEdited() macOS

boolean 타입의 값을 반환한다. 윈도우의 문서가 편집되었는지 여부를 나타낸다.

win.setMenu(menu) Linux Windows

• menu Menu | null

menu를 윈도우의 메뉴 바로 설정한다.

win.removeMenu() Linux Windows

윈도우의 메뉴 바를 제거한다.

win.setProgressBar(progress[, options])

• progress Double
• options Object (선택 사항)
  • mode string Windows - 프로그레스 바의 모드. none, normal, indeterminate, error, paused 중 하나를 선택할 수 있다.

프로그레스 바의 진행 값을 설정한다. 유효한 범위는 [0, 1.0]이다.

progress가 0보다 작으면 프로그레스 바를 제거한다. progress가 1보다 크면 불확정(indeterminate) 모드로 변경한다.

Linux 플랫폼에서는 Unity 데스크톱 환경만 지원하며, package.json 파일의 desktopName 필드에 *.desktop 파일 이름을 지정해야 한다. 기본값은 {app.name}.desktop이다.

Windows에서는 모드를 전달할 수 있다. 허용되는 값은 none, normal, indeterminate, error, paused이다. 모드를 설정하지 않고 setProgressBar를 호출하면(단, 유효 범위 내의 값을 전달한 경우) normal 모드로 간주한다.

win.setOverlayIcon(overlay, description) Windows

• overlay NativeImage | null - 작업 표시줄 아이콘의 오른쪽 하단에 표시할 아이콘. 이 인자가 null이면 오버레이가 사라진다.
• description string - 접근성 스크린 리더기에 제공할 설명

현재 작업 표시줄 아이콘 위에 16x16 픽셀 크기의 오버레이를 설정한다. 주로 애플리케이션 상태를 나타내거나 사용자에게 수동적으로 알림을 보내는 데 사용된다.

win.invalidateShadow() macOS

윈도우의 그림자를 무효화하여 현재 윈도우 모양을 기반으로 다시 계산한다.

투명한 BaseWindow는 macOS에서 시각적 잔상(artifact)을 남길 수 있다. 이 메서드는 애니메이션을 수행할 때와 같은 상황에서 이러한 잔상을 제거하는 데 사용할 수 있다.

win.setHasShadow(hasShadow)

• hasShadow boolean

윈도우에 그림자를 표시할지 여부를 설정한다.

win.hasShadow()

boolean을 반환한다. 윈도우에 그림자가 있는지 여부를 나타낸다.

win.setOpacity(opacity) Windows macOS

• opacity number - 0.0(완전 투명)부터 1.0(완전 불투명) 사이의 값

윈도우의 투명도를 설정한다. 리눅스에서는 아무 동작도 하지 않는다. 범위를 벗어난 숫자 값은 [0, 1] 범위로 제한된다.

win.getOpacity()

number 타입의 값을 반환한다. 이 값은 0.0(완전 투명)부터 1.0(완전 불투명) 사이의 범위를 가진다. Linux에서는 항상 1을 반환한다.

win.setShape(rects) Windows Linux Experimental

• rects Rectangle[] - 윈도우의 모양을 설정한다. 빈 리스트를 전달하면 윈도우를 기본 사각형으로 되돌린다.

윈도우 모양을 설정하면 시스템이 그리기와 사용자 상호작용을 허용하는 영역을 결정한다. 지정된 영역 밖에서는 픽셀이 그려지지 않고, 마우스 이벤트도 등록되지 않는다. 해당 영역 밖에서 발생한 마우스 이벤트는 윈도우가 받지 않으며, 윈도우 뒤에 있는 다른 요소로 전달된다.

win.setThumbarButtons(buttons) Windows

• buttons ThumbarButton[]

반환값 boolean - 버튼이 성공적으로 추가되었는지 여부

윈도우의 작업 표시줄 버튼 레이아웃에서 썸네일 이미지에 지정된 버튼 세트를 포함한 썸네일 툴바를 추가한다. 썸네일이 성공적으로 추가되었는지 여부를 나타내는 boolean 객체를 반환한다.

썸네일 툴바에 추가할 수 있는 버튼의 수는 공간 제한으로 인해 7개를 초과할 수 없다. 썸네일 툴바를 설정한 후에는 플랫폼의 제한으로 인해 툴바를 제거할 수 없다. 하지만 빈 배열을 사용해 API를 호출하면 버튼을 정리할 수 있다.

buttons는 Button 객체의 배열이다:

• Button 객체
  • icon NativeImage - 썸네일 툴바에 표시되는 아이콘
  • click Function
  • tooltip string (선택 사항) - 버튼의 툴팁 텍스트
  • flags string[] (선택 사항) - 버튼의 특정 상태와 동작을 제어한다. 기본값은 ['enabled']이다.

flags는 다음과 같은 string을 포함할 수 있는 배열이다:

• enabled - 버튼이 활성화되어 사용자에게 제공된다.
• disabled - 버튼이 비활성화된다. 버튼은 존재하지만 사용자 동작에 반응하지 않음을 나타내는 시각적 상태를 가진다.
• dismissonclick - 버튼을 클릭하면 썸네일 윈도우가 즉시 닫힌다.
• nobackground - 버튼 테두리를 그리지 않고 이미지만 사용한다.
• hidden - 버튼이 사용자에게 표시되지 않는다.
• noninteractive - 버튼은 활성화되어 있지만 상호작용하지 않는다. 눌린 상태가 그려지지 않는다. 이 값은 버튼이 알림에 사용되는 경우를 위한 것이다.

win.setThumbnailClip(region) Windows

• region Rectangle - 윈도우 영역

작업표시줄에서 윈도우 위로 마우스를 가져갔을 때 보이는 썸네일 이미지로 표시될 윈도우 영역을 설정한다. 전체 윈도우를 썸네일로 사용하려면 빈 영역을 지정하면 된다: { x: 0, y: 0, width: 0, height: 0 }.

win.setThumbnailToolTip(toolTip) Windows

• toolTip string

작업 표시줄에서 윈도우 썸네일 위에 마우스를 올렸을 때 표시되는 툴팁을 설정한다.

win.setAppDetails(options) Windows

• options Object
  • appId string (선택 사항) - 윈도우의 앱 사용자 모델 ID. 이 값을 설정하지 않으면 다른 옵션들은 적용되지 않는다.
  • appIconPath string (선택 사항) - 윈도우의 재실행 아이콘.
  • appIconIndex Integer (선택 사항) - appIconPath에 있는 아이콘의 인덱스. appIconPath가 설정되지 않은 경우 무시된다. 기본값은 0이다.
  • relaunchCommand string (선택 사항) - 윈도우의 재실행 명령어.
  • relaunchDisplayName string (선택 사항) - 윈도우의 재실행 표시 이름.

윈도우의 작업 표시줄 버튼 속성을 설정한다.

참고: relaunchCommand와 relaunchDisplayName은 항상 함께 설정해야 한다. 이 중 하나라도 설정하지 않으면 둘 다 사용되지 않는다.

win.setIcon(icon) Windows Linux

• icon NativeImage | string

윈도우 아이콘을 변경한다.

win.setWindowButtonVisibility(visible) macOS

• visible boolean

윈도우의 트래픽 라이트 버튼(최소화, 최대화, 닫기)의 가시성을 설정한다.

win.setAutoHideMenuBar(hide) Windows Linux

• hide boolean

윈도우의 메뉴 바가 자동으로 숨겨지도록 설정한다. 이 기능을 활성화하면 사용자가 Alt 키를 누를 때만 메뉴 바가 표시된다.

메뉴 바가 이미 보이는 상태에서 setAutoHideMenuBar(true)를 호출하면 즉시 숨겨지지 않는다.

win.isMenuBarAutoHide() Windows Linux

boolean 타입의 값을 반환한다. 메뉴 바가 자동으로 숨겨지는지 여부를 나타낸다.

win.setMenuBarVisibility(visible) Windows Linux

• visible boolean

메뉴 바의 가시성을 설정한다. 메뉴 바가 자동 숨김 상태일 때, 사용자는 Alt 키를 한 번 눌러 메뉴 바를 다시 표시할 수 있다.

win.isMenuBarVisible() Windows Linux

boolean 타입을 반환한다. 메뉴 바가 보이는지 여부를 나타낸다.

win.setVisibleOnAllWorkspaces(visible[, options]) macOS Linux

• visible boolean
• options Object (선택 사항)
  • visibleOnFullScreen boolean (선택 사항) macOS - 전체 화면 윈도우 위에서도 윈도우가 보이도록 설정한다.
  • skipTransformProcessType boolean (선택 사항) macOS - setVisibleOnAllWorkspaces를 호출하면 기본적으로 UIElementApplication과 ForegroundApplication 간의 프로세스 타입 변환이 발생한다. 이는 올바른 동작을 보장하기 위한 것이다. 하지만 이 과정에서 윈도우와 독이 잠시 사라질 수 있다. 만약 윈도우가 이미 UIElementApplication 타입이라면, skipTransformProcessType에 true를 전달해 이 변환 과정을 건너뛸 수 있다.

윈도우가 모든 작업 공간에서 보이도록 설정한다.

참고: 이 API는 윈도우에서는 아무런 동작을 하지 않는다.

win.isVisibleOnAllWorkspaces() macOS Linux

boolean 타입의 값을 반환한다. 윈도우가 모든 작업 공간에서 보이는지 여부를 나타낸다.

참고: 이 API는 윈도우 운영체제에서 항상 false를 반환한다.

win.setIgnoreMouseEvents(ignore[, options])

• ignore boolean
• options Object (선택 사항)
  • forward boolean (선택 사항) macOS Windows - true로 설정하면 마우스 이동 메시지를 Chromium으로 전달하여 mouseleave와 같은 마우스 관련 이벤트를 활성화한다. 이 옵션은 ignore가 true일 때만 사용된다. ignore가 false면 이 값과 관계없이 전달이 항상 비활성화된다.

이 메서드는 윈도우가 모든 마우스 이벤트를 무시하도록 만든다.

이 윈도우에서 발생한 모든 마우스 이벤트는 아래에 있는 윈도우로 전달된다. 하지만 이 윈도우가 포커스를 가지고 있다면 키보드 이벤트는 여전히 받을 수 있다.

win.setContentProtection(enable) macOS Windows

• enable boolean

윈도우의 내용이 다른 앱에 의해 캡처되는 것을 방지한다.

macOS에서는 NSWindow의 sharingType을 NSWindowSharingNone으로 설정한다. Windows에서는 SetWindowDisplayAffinity를 WDA_EXCLUDEFROMCAPTURE와 함께 호출한다. Windows 10 버전 2004 이상에서는 윈도우가 캡처에서 완전히 제외되며, 이전 버전의 Windows에서는 WDA_MONITOR가 적용된 것처럼 검은색 윈도우가 캡처된다.

win.setFocusable(focusable) macOS Windows

• focusable boolean

윈도우가 포커스를 받을 수 있는지 여부를 변경한다.

macOS에서는 윈도우에서 포커스를 제거하지 않는다.

win.isFocusable() macOS Windows

boolean 값을 반환한다. 윈도우가 포커스를 받을 수 있는지 여부를 나타낸다.

win.setParentWindow(parent)

• parent BaseWindow | null

현재 윈도우의 부모 윈도우를 parent로 설정한다. null을 전달하면 현재 윈도우를 최상위 윈도우로 변경한다.

win.getParentWindow()

BaseWindow | null 타입의 값을 반환한다. 부모 윈도우가 존재하면 해당 윈도우를 반환하고, 부모 윈도우가 없으면 null을 반환한다.

win.getChildWindows()

BaseWindow[] 타입을 반환한다. 모든 자식 윈도우를 나타낸다.

win.setAutoHideCursor(autoHide) macOS

• autoHide boolean

타이핑할 때 커서를 숨길지 여부를 제어한다.

win.selectPreviousTab() macOS

네이티브 탭이 활성화되어 있고 윈도우에 다른 탭이 있을 때, 이전 탭을 선택한다.

win.selectNextTab() macOS

네이티브 탭 기능이 활성화된 상태에서, 현재 윈도우에 다른 탭이 있을 경우 다음 탭을 선택한다.

win.showAllTabs() macOS

네이티브 탭이 활성화된 상태에서 탭 개요를 표시하거나 숨긴다.

win.mergeAllWindows() macOS

네이티브 탭 기능이 활성화되어 있고 열린 윈도우가 둘 이상일 때, 모든 윈도우를 하나의 윈도우로 합치며 각각을 탭으로 표시한다.

win.moveTabToNewWindow() macOS

현재 윈도우에 두 개 이상의 탭이 있고 네이티브 탭 기능이 활성화된 경우, 현재 탭을 새로운 윈도우로 이동시킨다.

win.toggleTabBar() macOS

현재 윈도우에 탭이 하나만 있고 네이티브 탭이 활성화된 경우, 탭 바의 가시성을 전환한다.

win.addTabbedWindow(baseWindow) macOS

• baseWindow BaseWindow

이 윈도우에 탭으로 다른 윈도우를 추가한다. 새 탭은 현재 윈도우 인스턴스의 탭 뒤에 위치한다.

win.setVibrancy(type) macOS

• type string | null - titlebar, selection, menu, popover, sidebar, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, under-page 중 하나를 선택할 수 있다. 자세한 내용은 macOS 문서를 참고한다.

윈도우에 비브란시 효과를 추가한다. null이나 빈 문자열을 전달하면 윈도우의 비브란시 효과를 제거한다.

win.setBackgroundMaterial(material) Windows

• material string
  • auto - 데스크톱 윈도우 관리자(DWM)가 이 윈도우의 시스템 드로우 백드롭 재질을 자동으로 결정한다. 기본값이다.
  • none - 시스템 백드롭을 그리지 않는다.
  • mica - 장기 실행 윈도우에 해당하는 백드롭 재질 효과를 그린다.
  • acrylic - 일시적인 윈도우에 해당하는 백드롭 재질 효과를 그린다.
  • tabbed - 탭이 있는 제목 표시줄을 가진 윈도우에 해당하는 백드롭 재질 효과를 그린다.

이 메서드는 브라우저 윈도우의 시스템 드로우 배경 재질을 설정하며, 비클라이언트 영역 뒤쪽도 포함한다.

자세한 내용은 Windows 문서를 참고한다.

참고: 이 메서드는 Windows 11 22H2 이상에서만 지원된다.

win.setWindowButtonPosition(position) macOS

• position Point | null

프레임리스 윈도우에서 트래픽 라이트 버튼의 위치를 커스텀하게 설정한다.
null을 전달하면 기본 위치로 초기화된다.

win.getWindowButtonPosition() macOS

Point | null 타입의 값을 반환한다. 프레임리스 윈도우에서 트래픽 라이트 버튼의 커스텀 위치를 나타내며, 커스텀 위치가 없을 경우 null을 반환한다.

win.setTouchBar(touchBar) macOS

• touchBar TouchBar | null

현재 윈도우의 터치바 레이아웃을 설정한다. null이나 undefined를 지정하면 터치바를 지운다. 이 메서드는 기기에 터치바가 있을 때만 효과가 있다.

참고: TouchBar API는 현재 실험 중이며, 향후 Electron 릴리스에서 변경되거나 제거될 수 있다.

win.setTitleBarOverlay(options) Windows Linux

• options Object
  • color String (선택 사항) - 윈도우 컨트롤 오버레이가 활성화되었을 때의 CSS 색상.
  • symbolColor String (선택 사항) - 윈도우 컨트롤 오버레이가 활성화되었을 때 심볼의 CSS 색상.
  • height Integer (선택 사항) - 타이틀 바와 윈도우 컨트롤 오버레이의 높이를 픽셀 단위로 지정.

이 메서드는 이미 윈도우 컨트롤 오버레이가 활성화된 윈도우에서 타이틀 바 오버레이의 스타일을 업데이트한다.

Linux에서는 symbolColor가 명시적으로 설정되지 않은 경우, color와 최소 접근성 대비를 유지하도록 자동으로 계산된다.