Skip to main content

systemPreferences

시스템 환경설정을 가져온다.

프로세스: Main, Utility

const { systemPreferences } = require('electron')
console.log(systemPreferences.isAeroGlassEnabled())

이벤트​

systemPreferences 객체는 다음과 같은 이벤트를 발생시킨다:

이벤트: 'accent-color-changed' Windows​

반환값:

  • event Event
  • newColor string - 사용자가 시스템 액센트 색상으로 지정한 새로운 RGBA 색상값

이벤트: 'color-changed' Windows​

반환값:

  • event Event

메서드​

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

boolean을 반환한다. 페이지 간 스와이프 설정이 활성화되어 있는지 여부를 나타낸다.

systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOS​

  • event string
  • userInfo Record<string, any>
  • deliverImmediately boolean (선택 사항) - 구독 중인 앱이 비활성 상태일 때도 즉시 알림을 전송하려면 true로 설정한다.

macOS의 네이티브 알림으로 event를 전송한다. userInfo는 알림과 함께 전송되는 사용자 정보 딕셔너리를 포함하는 객체이다.

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

macOS의 네이티브 알림으로 event를 전송한다. userInfo는 알림과 함께 전송되는 사용자 정보 딕셔너리를 포함하는 객체다.

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

macOS의 네이티브 알림으로 event를 전송한다. userInfo는 알림과 함께 전송되는 사용자 정보 딕셔너리를 포함하는 객체이다.

systemPreferences.subscribeNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • object string

반환값 number - 이 구독의 ID

macOS의 네이티브 알림을 구독한다. 해당 event가 발생하면 callback(event, userInfo) 형태로 콜백 함수가 호출된다. userInfo는 알림과 함께 전송된 사용자 정보 딕셔너리를 포함하는 객체이다. object는 알림의 발신자이며, 현재는 NSString 값만 지원한다.

구독자의 id가 반환되며, 이 ID를 사용해 event 구독을 취소할 수 있다.

내부적으로 이 API는 NSDistributedNotificationCenter를 구독한다. event의 예시 값은 다음과 같다:

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

event가 null인 경우, NSDistributedNotificationCenter는 이를 관찰자에게 전달하는 기준으로 사용하지 않는다. 더 자세한 정보는 문서를 참고한다.

systemPreferences.subscribeLocalNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • object string

반환값 number - 이 구독의 ID

subscribeNotification과 동일하지만, 로컬 기본값에 대해 NSNotificationCenter를 사용한다. NSUserDefaultsDidChangeNotification과 같은 이벤트에 필요하다.

event가 null인 경우, NSNotificationCenter는 이를 관찰자에게 전달하는 기준으로 사용하지 않는다. 더 많은 정보는 문서를 참고한다.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • object string

number 타입의 값을 반환한다. 이 구독의 ID를 나타낸다.

subscribeNotification과 동일하지만, NSWorkspace.sharedWorkspace.notificationCenter를 사용한다. 이 메서드는 NSWorkspaceDidActivateApplicationNotification과 같은 이벤트에 필요하다.

event가 null인 경우, NSWorkspaceNotificationCenter는 이를 옵저버에게 전달하는 기준으로 사용하지 않는다. 더 자세한 정보는 문서를 참고한다.

systemPreferences.unsubscribeNotification(id) macOS​

  • id Integer

id에 해당하는 구독자를 제거한다.

systemPreferences.unsubscribeLocalNotification(id) macOS​

  • id Integer

unsubscribeNotification과 동일하지만, NSNotificationCenter에서 구독자를 제거한다.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

  • id Integer

unsubscribeNotification과 동일한 기능을 수행하지만, 구독자를 NSWorkspace.sharedWorkspace.notificationCenter에서 제거한다.

systemPreferences.registerDefaults(defaults) macOS​

  • defaults Record<string, string | boolean | number> - (키: 값) 형태의 사용자 기본값 딕셔너리

지정된 기본값을 애플리케이션의 NSUserDefaults에 추가한다.

systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOS​

  • key string
  • type Type - string, boolean, integer, float, double, url, array, dictionary 중 하나

반환값: UserDefaultTypes[Type] - NSUserDefaults에서 key에 해당하는 값

주로 사용되는 key와 type의 예시:

  • AppleInterfaceStyle: string
  • AppleAquaColorVariant: integer
  • AppleHighlightColor: string
  • AppleShowScrollBars: string
  • NSNavRecentPlaces: array
  • NSPreferredWebServices: dictionary
  • NSUserDictionaryReplacementItems: array

systemPreferences.setUserDefault<Type extends keyof UserDefaultTypes>(key, type, value) macOS​

  • key string
  • type Type - string, boolean, integer, float, double, url, array, dictionary 중 하나가 될 수 있다.
  • value UserDefaultTypes[Type]

NSUserDefaults에서 key의 값을 설정한다.

type은 value의 실제 타입과 일치해야 한다. 일치하지 않을 경우 예외가 발생한다.

일반적으로 사용되는 key와 type의 예는 다음과 같다:

  • ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS​

  • key string

NSUserDefaults에서 key를 제거한다. 이 메서드는 setUserDefault로 설정된 key의 값을 기본값이나 전역 값으로 복원할 때 사용할 수 있다.

systemPreferences.isAeroGlassEnabled() Windows​

boolean 값을 반환한다. DWM 컴포지션 (Aero Glass)이 활성화되어 있으면 true를, 그렇지 않으면 false를 반환한다.

이 기능을 사용해 투명 윈도우를 생성할지 여부를 결정하는 예제를 살펴보자 (DWM 컴포지션이 비활성화된 상태에서는 투명 윈도우가 제대로 동작하지 않는다):

const { BrowserWindow, systemPreferences } = require('electron')
const browserOptions = { width: 1000, height: 800 }

// 플랫폼이 투명 윈도우를 지원하는 경우에만 투명 옵션을 활성화한다.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// 윈도우를 생성한다.
const win = new BrowserWindow(browserOptions)

// 네비게이션을 처리한다.
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // 투명 옵션이 비활성화된 경우 기본 스타일을 사용하는 대체 파일을 로드한다.
  win.loadFile('fallback.html')
}

systemPreferences.getAccentColor() Windows macOS​

string 타입을 반환한다. 현재 시스템 전체에서 사용 중인 강조 색상을 RGBA 16진수 형식으로 나타낸다.

const color = systemPreferences.getAccentColor() // `"aabbccdd"`
const red = color.substr(0, 2) // "aa"
const green = color.substr(2, 2) // "bb"
const blue = color.substr(4, 2) // "cc"
const alpha = color.substr(6, 2) // "dd"

이 API는 macOS 10.14 Mojave 이상에서만 사용할 수 있다.

systemPreferences.getColor(color) Windows macOS​

  • color string - 다음 값 중 하나:
    • Windows에서:
      • 3d-dark-shadow - 3D 디스플레이 요소의 어두운 그림자.
      • 3d-face - 3D 디스플레이 요소와 대화 상자 배경의 표면 색상.
      • 3d-highlight - 3D 디스플레이 요소의 하이라이트 색상.
      • 3d-light - 3D 디스플레이 요소의 밝은 색상.
      • 3d-shadow - 3D 디스플레이 요소의 그림자 색상.
      • active-border - 활성화된 윈도우의 테두리.
      • active-caption - 활성화된 윈도우의 제목 표시줄. 그라데이션 효과가 활성화된 경우, 활성화된 윈도우 제목 표시줄의 왼쪽 색상을 지정.
      • active-caption-gradient - 활성화된 윈도우 제목 표시줄의 그라데이션 오른쪽 색상.
      • app-workspace - MDI(Multiple Document Interface) 애플리케이션의 배경 색상.
      • button-text - 푸시 버튼의 텍스트.
      • caption-text - 캡션, 크기 조정 상자, 스크롤 바 화살표 상자의 텍스트.
      • desktop - 데스크톱 배경 색상.
      • disabled-text - 비활성화된(회색 처리된) 텍스트.
      • highlight - 컨트롤에서 선택된 항목.
      • highlight-text - 컨트롤에서 선택된 항목의 텍스트.
      • hotlight - 하이퍼링크 또는 핫 트랙된 항목의 색상.
      • inactive-border - 비활성화된 윈도우의 테두리.
      • inactive-caption - 비활성화된 윈도우의 캡션. 그라데이션 효과가 활성화된 경우, 비활성화된 윈도우 제목 표시줄의 왼쪽 색상을 지정.
      • inactive-caption-gradient - 비활성화된 윈도우 제목 표시줄의 그라데이션 오른쪽 색상.
      • inactive-caption-text - 비활성화된 캡션의 텍스트 색상.
      • info-background - 툴팁 컨트롤의 배경 색상.
      • info-text - 툴팁 컨트롤의 텍스트 색상.
      • menu - 메뉴 배경.
      • menu-highlight - 평면 메뉴로 표시될 때 메뉴 항목을 강조하는 데 사용되는 색상.
      • menubar - 평면 메뉴로 표시될 때 메뉴 바의 배경 색상.
      • menu-text - 메뉴의 텍스트.
      • scrollbar - 스크롤 바의 회색 영역.
      • window - 윈도우 배경.
      • window-frame - 윈도우 프레임.
      • window-text - 윈도우의 텍스트.
    • macOS에서:
      • control-background - 브라우저나 테이블과 같은 큰 인터페이스 요소의 배경.
      • control - 컨트롤의 표면.
      • control-text - 비활성화되지 않은 컨트롤의 텍스트.
      • disabled-control-text - 비활성화된 컨트롤의 텍스트.
      • find-highlight - 찾기 표시기의 색상.
      • grid - 테이블과 같은 인터페이스 요소의 그리드 라인.
      • header-text - 테이블의 헤더 cell 텍스트.
      • highlight - 화면상의 가상 광원.
      • keyboard-focus-indicator - 키보드를 사용해 인터페이스를 탐색할 때 현재 포커스된 컨트롤 주위에 나타나는 링.
      • label - 주요 콘텐츠를 포함하는 라벨의 텍스트.
      • link - 다른 콘텐츠로의 링크.
      • placeholder-text - 컨트롤 또는 텍스트 뷰의 플레이스홀더 문자열.
      • quaternary-label - 워터마크 텍스트와 같은 3차 라벨보다 중요도가 낮은 라벨의 텍스트.
      • scrubber-textured-background - 터치 바의 스크러버 배경.
      • secondary-label - 일반 라벨보다 중요도가 낮은 라벨의 텍스트. 예: 부제목 또는 추가 정보를 나타내는 라벨.
      • selected-content-background - 키 윈도우 또는 뷰에서 선택된 콘텐츠의 배경.
      • selected-control - 선택된 컨트롤의 표면.
      • selected-control-text - 선택된 컨트롤의 텍스트.
      • selected-menu-item-text - 선택된 메뉴의 텍스트.
      • selected-text-background - 선택된 텍스트의 배경.
      • selected-text - 선택된 텍스트.
      • separator - 콘텐츠의 다른 섹션 사이의 구분선.
      • shadow - 화면상의 돌출된 객체가 만드는 가상 그림자.
      • tertiary-label - 2차 라벨보다 중요도가 낮은 라벨의 텍스트. 예: 비활성화된 텍스트를 나타내는 라벨.
      • text-background - 텍스트 배경.
      • text - 문서의 텍스트.
      • under-page-background - 문서 콘텐츠 뒤의 배경.
      • unemphasized-selected-content-background - 비-키 윈도우 또는 뷰에서 선택된 콘텐츠의 배경.
      • unemphasized-selected-text-background - 비-키 윈도우 또는 뷰에서 선택된 텍스트의 배경.
      • unemphasized-selected-text - 비-키 윈도우 또는 뷰에서 선택된 텍스트.
      • window-background - 윈도우의 배경.
      • window-frame-text - 윈도우의 타이틀바 영역의 텍스트.

string을 반환 - RGBA 16진수 형식(#RRGGBBAA)의 시스템 색상 설정.

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

다음 색상은 macOS 10.14 이상에서만 사용 가능: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS​

  • color string - 다음 값 중 하나:
    • blue
    • brown
    • gray
    • green
    • orange
    • pink
    • purple
    • red
    • yellow

반환값 string - #RRGGBBAA 형식으로 표준 시스템 색상을 반환한다.

이 메서드는 '대비 증가'나 '투명도 감소'와 같은 접근성 설정 변경에 자동으로 적응하는 여러 표준 시스템 색상 중 하나를 반환한다. 자세한 내용은 Apple 문서를 참고한다.

systemPreferences.getEffectiveAppearance() macOS​

string을 반환한다. 반환값은 dark, light, 또는 unknown 중 하나이다.

이 메서드는 현재 애플리케이션에 적용된 macOS의 외관 설정을 가져온다. 이는 NSApplication.effectiveAppearance에 매핑된다.

systemPreferences.canPromptTouchID() macOS​

boolean 타입을 반환한다. 이 기기가 Touch ID를 사용할 수 있는지 여부를 나타낸다.

systemPreferences.promptTouchID(reason) macOS​

  • reason string - Touch ID 인증을 요청하는 이유

Promise<void>를 반환한다. 사용자가 Touch ID로 성공적으로 인증하면 resolve된다.

const { systemPreferences } = require('electron')

systemPreferences.promptTouchID('보안이 필요한 작업에 대한 동의를 얻기 위해').then(success => {
  console.log('Touch ID로 성공적으로 인증했습니다!')
}).catch(err => {
  console.log(err)
})

이 API 자체는 사용자 데이터를 보호하지 않는다. 오히려 이를 가능하게 하는 메커니즘을 제공한다. 네이티브 앱은 키체인 항목에 kSecAccessControlUserPresence와 같은 Access Control Constants를 설정해야 한다. 이를 통해 키체인을 읽을 때 Touch ID 생체 인증 동의를 자동으로 요청할 수 있다. 이는 node-keytar를 사용해 구현할 수 있다. node-keytar로 암호화 키를 저장하고, promptTouchID()가 resolve된 경우에만 해당 키를 가져오는 방식이다.

systemPreferences.isTrustedAccessibilityClient(prompt) macOS​

  • prompt boolean - 현재 프로세스가 신뢰할 수 없는 경우 사용자에게 알릴지 여부를 결정한다.

boolean을 반환한다. 현재 프로세스가 신뢰할 수 있는 접근성 클라이언트라면 true를, 그렇지 않다면 false를 반환한다.

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

  • mediaType string - microphone, camera, screen 중 하나를 지정할 수 있다.

string을 반환한다. 반환값은 not-determined, granted, denied, restricted, unknown 중 하나가 될 수 있다.

macOS 10.13 High Sierra에서는 사용자 동의가 필요하지 않았기 때문에 이 메서드는 항상 granted를 반환한다. macOS 10.14 Mojave 이상에서는 microphone과 camera 접근에 대한 동의가 필요하다. macOS 10.15 Catalina 이상에서는 screen 접근에 대한 동의가 필요하다.

Windows 10은 모든 win32 애플리케이션에 대해 microphone과 camera 접근을 제어하는 전역 설정을 가지고 있다. 이전 버전의 Windows에서는 screen 및 모든 미디어 타입에 대해 항상 granted를 반환한다.

systemPreferences.askForMediaAccess(mediaType) macOS​

  • mediaType string - 요청할 미디어 타입. microphone 또는 camera를 지정할 수 있다.

Promise<boolean>을 반환한다. 사용자가 권한을 허용하면 true, 거부하면 false로 이행된다. 유효하지 않은 mediaType을 전달하면 Promise는 거부된다. 접근 요청이 거부된 후 시스템 설정에서 변경한 경우, 새로운 권한이 적용되려면 앱을 재시작해야 한다. 이미 접근 요청이 거부된 상태라면, 시스템 설정을 통해 변경해야 한다. 이 경우 알림이 표시되지 않으며, Promise는 기존 접근 상태로 이행된다.

중요: 이 API를 올바르게 사용하려면 앱의 Info.plist 파일에 NSMicrophoneUsageDescription과 NSCameraUsageDescription 문자열을 반드시 설정해야 한다. 이 키들의 값은 권한 요청 대화상자에 표시되어 사용자가 권한 요청의 목적을 정확히 이해할 수 있도록 돕는다. Electron 환경에서 이를 설정하는 방법은 Electron Application Distribution 문서를 참고한다.

macOS 10.14 Mojave 이전 버전에서는 사용자 동의가 필요하지 않았으므로, 시스템이 10.13 High Sierra에서 실행 중인 경우 이 메서드는 항상 true를 반환한다.

systemPreferences.getAnimationSettings()​

Object를 반환한다:

  • shouldRenderRichAnimation boolean - 리치 애니메이션을 렌더링해야 하는지 여부를 나타낸다. 세션 타입(예: 원격 데스크톱)과 접근성 설정을 확인해 무거운 애니메이션에 대한 가이드를 제공한다.
  • scrollAnimationsEnabledBySystem boolean - 플랫폼별로 스크롤 애니메이션(예: 홈/엔드 키로 생성된)을 활성화할지 여부를 결정한다.
  • prefersReducedMotion boolean - 플랫폼 API를 기반으로 사용자가 움직임을 줄이길 원하는지 여부를 판단한다.

시스템 애니메이션 설정을 담은 객체를 반환한다.

속성​

systemPreferences.accessibilityDisplayShouldReduceTransparency macOS 더 이상 사용되지 않음​

앱이 반투명 배경을 사용하지 않도록 설정하는 boolean 타입의 속성이다. 이 속성은 NSWorkspace.accessibilityDisplayShouldReduceTransparency와 매핑된다.

더 이상 사용되지 않음: 새로운 nativeTheme.prefersReducedTransparency API를 사용한다.

systemPreferences.effectiveAppearance macOS 읽기 전용​

이 속성은 string 타입이며 dark, light, 또는 unknown 값을 가질 수 있다.

현재 애플리케이션에 적용된 macOS 외관 설정을 반환한다. 이는 NSApplication.effectiveAppearance에 매핑된다.