02 · OS Integration — OS / UI 용어

이 챕터: Electron이 OS에 닿는 모듈들 — Tray·Menu·dialog·shell·clipboard 같은 UI 표면과 screen·powerMonitor·systemPreferences 같은 시스템 정보. 참고 챕터: 04-native-integration

app.getPath()

OS의 표준 위치를 키로 받아 절대 경로로 돌려주는 헬퍼.

app.getPath('userData') (앱 데이터), 'temp', 'downloads', 'desktop', 'documents', 'logs', 'cache', 'home'. 사용자 데이터를 OS 규약(~/Library/Application Support/..., %APPDATA%\..., ~/.config/...) 에 맞춰 저장하는 유일한 안전한 방법. 직접 경로를 조립하지 말 것.

관련: [shell (Electron module)], [protocol handler] 참고 챕터: 04-native-integration

clipboard

OS 클립보드 읽기/쓰기 모듈. text/HTML/이미지/RTF/bookmark까지.

clipboard.writeText(...), clipboard.readImage(), clipboard.readHTML(). macOS에는 [pasteboard 이름]이 여러 개라 clipboard.readText('selection')처럼 보조 클립보드를 지정할 수 있다. 보안: renderer에서 직접 호출하면 권한 우회 — Main에서 호출 + IPC로 전달이 안전한 패턴.

관련: [nativeImage], [shell (Electron module)] 참고 챕터: 04-native-integration

desktopCapturer

화면/창 캡처 소스 목록을 가져오는 모듈. 화면 공유·녹화의 기반.

desktopCapturer.getSources({ types: ['screen', 'window'] }) → 각 소스의 thumbnail + id. id를 getUserMedia 의 chromeMediaSourceId로 넘기면 video stream 획득. macOS 10.15+는 Screen Recording 권한이 필요하고, systemPreferences.getMediaAccessStatus('screen')로 상태 확인.

관련: [screen], [systemPreferences] 참고 챕터: 04-native-integration

dialog

OS 네이티브 다이얼로그(파일 열기/저장/메시지/에러)를 띄우는 모듈.

dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }), showSaveDialog, showMessageBox, showErrorBox. Main 전용 — renderer에서는 IPC로 우회. 비동기(show*Dialog) vs 동기(show*DialogSync) — 동기는 모달이 끝날 때까지 모든 창이 멈춘다, 피할 것.

관련: [BrowserWindow], [shell (Electron module)] 참고 챕터: 04-native-integration

dock (macOS)

macOS Dock 아이콘 제어 모듈. app.dock 으로 접근.

app.dock.setBadge('3') (배지), app.dock.bounce('critical') (반동), app.dock.setMenu(menu) (Dock 메뉴), app.dock.hide() (메뉴 막대만 살리는 background 앱). macOS 전용 — Windows/Linux에서는 호출해도 무시. 비교: Windows에서는 [taskbar] 메서드를 쓴다.

관련: [taskbar], [JumpList], [Tray] 참고 챕터: 04-native-integration

globalShortcut

앱에 포커스가 없어도 동작하는 OS 전역 단축키 등록 모듈.

globalShortcut.register('CommandOrControl+Shift+K', () => ...). 음악 플레이어의 미디어 키, 캡처 도구의 핫키. 주의: 다른 앱과 충돌 가능 — 충돌 시 register는 false 반환. app.on('will-quit', () => globalShortcut.unregisterAll()) 필수.

관련: [Menu], [accelerator] 참고 챕터: 04-native-integration

JumpList (Windows)

Windows 작업 표시줄 아이콘을 우클릭했을 때 뜨는 최근 항목/태스크 목록.

app.setJumpList([{ type: 'custom', name: 'Recent', items: [...] }]). Recent/Frequent는 OS가 자동 관리(app.addRecentDocument), Tasks/Custom은 앱이 직접. Windows 전용. macOS의 [dock] 메뉴와 대응되는 개념.

관련: [taskbar], [dock (macOS)] 참고 챕터: 04-native-integration

Launch Services (macOS)

macOS가 어떤 앱이 어떤 파일 타입/URL scheme을 처리하는지 등록하는 데이터베이스.

Electron에서 직접 다루지는 않지만 app.setAsDefaultProtocolClient('myapp')이 내부에서 이 데이터베이스를 갱신한다. macOS 캐시 문제로 등록이 반영 안 될 때 lsregister -kill -r -domain local -domain user로 재빌드.

관련: [protocol handler (custom scheme)] 참고 챕터: 04-native-integration

Menu

Application Menu / Context Menu / Dock Menu 등을 구성하는 객체.

Menu.buildFromTemplate([{ label: 'File', submenu: [...] }]) → Menu.setApplicationMenu(menu). macOS는 Application Menu가 메뉴 바에 강제로 표시되므로 한 번은 만들어야 한다. Context Menu는 menu.popup({ window })로 띄운다.

관련: [MenuItem], [accelerator], [Tray] 참고 챕터: 04-native-integration

MenuItem

Menu의 한 항목. label·role·accelerator·click·submenu를 가진다.

role은 OS 표준 메뉴 동작('copy', 'paste', 'quit', 'minimize') — 직접 구현하지 말고 role을 쓸 것, OS별 단축키·번역까지 알아서 처리된다. type: 'separator', type: 'checkbox', type: 'radio'도 가능.

관련: [Menu], [accelerator] 참고 챕터: 04-native-integration

nativeImage

Electron의 플랫폼 독립 이미지 객체. 아이콘·트레이·메뉴·dialog가 받는 타입.

nativeImage.createFromPath('icon.png'), createFromBuffer, createFromDataURL. macOS의 Template Image (image.setTemplateImage(true))는 자동으로 light/dark에 맞춰 색이 반전된다 — Tray 아이콘은 거의 항상 template으로. @2x.png, @3x.png 같은 HiDPI 변형을 자동으로 골라준다.

관련: [Tray], [Menu], [BrowserWindow] 참고 챕터: 04-native-integration

nativeTheme

OS의 다크 모드 / 액센트 컬러를 읽고 변경에 반응하는 모듈.

nativeTheme.shouldUseDarkColors (현재 다크인지), nativeTheme.on('updated', ...) (사용자가 OS 테마 바꿨을 때). nativeTheme.themeSource = 'dark'로 앱만 강제할 수도 있다 — OS 따라가는 'system'이 디폴트.

관련: [systemPreferences], [screen] 참고 챕터: 04-native-integration

Notification

OS 네이티브 알림 (banner / toast / notification center).

new Notification({ title, body, icon }).show(). macOS는 Notification Center, Windows는 Action Center, Linux는 libnotify. Windows 주의: notification에 AppUserModelId 설정이 없으면 “electron.app.Electron” 같은 이름으로 뜬다 — app.setAppUserModelId('com.company.app') 필수.

관련: [Tray], [dock (macOS)] 참고 챕터: 04-native-integration

powerMonitor

시스템의 전원/잠금/세션 상태를 알려주는 모듈.

on('suspend'), on('resume'), on('lock-screen'), on('on-battery'), on('on-ac'). powerMonitor.getSystemIdleTime()으로 사용자 유휴 시간(초). 슬립 → 깨어남 후 연결 재설정이 필요한 채팅·VoIP 앱에 필수.

관련: [powerSaveBlocker], [systemPreferences] 참고 챕터: 04-native-integration

powerSaveBlocker

OS의 슬립·디스플레이 꺼짐을 막는 모듈. 비디오 재생·다운로드 중에 필요.

powerSaveBlocker.start('prevent-display-sleep') (영상 재생용), 'prevent-app-suspension' (백그라운드 작업용). 종료 시 반드시 .stop(id) — 안 하면 사용자 배터리를 갈아먹는다.

관련: [powerMonitor] 참고 챕터: 04-native-integration

protocol (Electron module)

커스텀 URL scheme을 앱 내부에서 처리하는 모듈. 두 종류 — privileged scheme 등록 + 핸들러 등록.

protocol.registerSchemesAsPrivileged([{ scheme: 'app', privileges: { secure: true, standard: true } }])는 app.ready 전에 호출해야 한다. 그 뒤 protocol.handle('app', request => ...)로 실제 응답을 만든다. file:// 대신 app://을 쓰면 상대 경로·CSP가 깔끔해진다.

관련: [protocol handler (custom scheme)], [session] 참고 챕터: 02-window-lifecycle, 05-security

protocol handler (custom scheme)

OS에 내 앱이 어떤 URL scheme을 처리할지 등록. 예: myapp://login?code=....

app.setAsDefaultProtocolClient('myapp') — OS가 myapp://를 열면 내 앱을 띄운다. OAuth callback, deep link, 외부 SSO 통합에 쓰인다. 위의 Electron protocol module과 헷갈리지 말 것 — 그건 앱 내부 scheme, 이건 OS 차원 scheme.

관련: [Launch Services (macOS)], [app (module)] 참고 챕터: 04-native-integration

screen

모니터 정보를 읽는 모듈. 디스플레이·DPI·작업 영역.

screen.getAllDisplays(), screen.getPrimaryDisplay(), screen.getCursorScreenPoint(). app.ready 후에만 사용 가능. 다중 모니터 환경에서 창을 어디에 띄울지 결정할 때, HiDPI에서 좌표 계산할 때 (scaleFactor) 필수.

관련: [BrowserWindow], [desktopCapturer] 참고 챕터: 02-window-lifecycle

shell (Electron module)

OS에 외부로 위임하는 모듈. 기본 브라우저로 URL 열기, 파일 탐색기에서 보기, 휴지통으로 보내기.

shell.openExternal('https://...') (기본 브라우저), shell.openPath('/Users/x/Documents') (파일 매니저), shell.showItemInFolder(file), shell.trashItem(file), shell.beep(). 보안 함정: openExternal에 사용자 입력이 그대로 들어가면 file://, javascript:, 임의 protocol handler 호출 가능 — 항상 scheme 화이트리스트.

관련: [protocol handler (custom scheme)], [clipboard] 참고 챕터: 04-native-integration, 05-security

systemPreferences

OS별 시스템 설정·미디어 권한을 읽고 일부 변경하는 모듈.

systemPreferences.getMediaAccessStatus('camera' | 'microphone' | 'screen') — macOS 권한 상태. askForMediaAccess('camera')로 권한 요청. macOS의 액센트 컬러(getUserDefault), Windows의 액센트 컬러(getAccentColor), 다크 모드 (isDarkMode — deprecated, nativeTheme 사용 권장).

관련: [nativeTheme], [powerMonitor] 참고 챕터: 04-native-integration

Taskbar (Windows)

Windows 작업 표시줄 아이콘·진행률·오버레이 아이콘 제어.

win.setProgressBar(0.5) (다운로드 진행률), win.setOverlayIcon(image, desc) (작은 배지 아이콘), win.flashFrame(true) (주의 끌기 — 아이콘 깜박임). macOS의 [dock]과 대응.

관련: [JumpList], [dock (macOS)], [BrowserWindow] 참고 챕터: 04-native-integration

Touch Bar (macOS, deprecated hardware)

MacBook Pro의 Touch Bar 컨트롤 객체. TouchBar, TouchBarButton, TouchBarLabel 등.

Apple이 2023년 Touch Bar 단종 — 신규 앱은 거의 필요 없음. 기존 Touch Bar 지원 앱은 그대로 동작. 역사적 흔적으로 알아두면 충분.

관련: [Menu], [MenuItem] 참고 챕터: 04-native-integration

Tray

시스템 트레이(macOS 메뉴바 우상단 / Windows 알림 영역) 아이콘.

new Tray(nativeImage) + tray.setContextMenu(menu). 백그라운드 상주형 앱(Discord, Slack, 1Password)의 핵심 UX. 아이콘은 [nativeImage]의 template image로. garbage-collect 방지를 위해 모듈 스코프에 변수로 들고 있어야 한다 — 흔한 함정.

관련: [Menu], [nativeImage], [dock (macOS)] 참고 챕터: 04-native-integration

부록: OS별 같은 개념 대응표

부록: 자주 헷갈리는 짝

더 읽기

• 04-native-integration — OS API 통합 본문
• electron docs · Tray
• electron docs · Menu
• electron docs · shell