Skip to main content

트레이

Class: Tray​

시스템 알림 영역에 아이콘과 컨텍스트 메뉴를 추가한다.

프로세스: 메인

Tray는 EventEmitter이다.

const { app, Menu, Tray } = require('electron')

let tray = null
app.whenReady().then(() => {
  tray = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' },
    { label: 'Item3', type: 'radio', checked: true },
    { label: 'Item4', type: 'radio' }
  ])
  tray.setToolTip('This is my application.')
  tray.setContextMenu(contextMenu)
})

플랫폼별 고려사항

리눅스

  • 트레이 아이콘은 기본적으로 StatusNotifierItem을 사용한다. 사용자의 데스크톱 환경에서 이를 사용할 수 없는 경우 GtkStatusIcon이 대신 사용된다.
  • click 이벤트는 사용자가 트레이 아이콘을 활성화할 때 발생한다. 하지만 StatusNotifierItem 명세는 어떤 동작이 활성화를 유발하는지 명시하지 않는다. 어떤 환경에서는 왼쪽 마우스 클릭이지만, 다른 환경에서는 왼쪽 마우스 더블 클릭일 수 있다.
  • 개별 MenuItem에 대한 변경 사항을 적용하려면 setContextMenu를 다시 호출해야 한다. 예를 들어:
const { app, Menu, Tray } = require('electron')

let appIcon = null
app.whenReady().then(() => {
  appIcon = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' }
  ])

  // 컨텍스트 메뉴를 변경한다
  contextMenu.items[1].checked = false

  // 리눅스에서는 컨텍스트 메뉴를 수정했으므로 다시 호출한다
  appIcon.setContextMenu(contextMenu)
})

맥OS

  • Tray 생성자에 전달하는 아이콘은 템플릿 이미지여야 한다.
  • 레티나 디스플레이에서 아이콘이 흐릿하게 보이지 않도록 하려면 @2x 이미지가 144dpi인지 확인한다.
  • 애플리케이션을 번들링할 때(예: 개발을 위해 webpack을 사용할 때), 파일 이름이 변형되거나 해시되지 않도록 주의한다. 파일 이름은 Template로 끝나야 하며, @2x 이미지는 표준 이미지와 동일한 파일 이름을 가져야 한다. 그렇지 않으면 맥OS가 이미지 색상을 자동으로 반전시키거나 고해상도 이미지를 사용하지 않을 수 있다.
  • 대부분의 아이콘에는 16x16 (72dpi)와 32x32@2x (144dpi)가 적합하다.

윈도우

  • 최상의 시각적 효과를 얻으려면 ICO 아이콘을 사용하는 것이 좋다.

new Tray(image, [guid])​

  • image (NativeImage | string)
  • guid string (선택 사항) Windows - 트레이 아이콘에 GUID를 할당한다. 실행 파일이 서명되어 있고, 서명의 주체 줄에 조직 정보가 포함된 경우, GUID는 해당 서명과 영구적으로 연결된다. 실행 파일의 경로가 변경되더라도 시스템 트레이에서의 트레이 아이콘 위치와 같은 운영체제 수준의 설정은 유지된다. 실행 파일이 코드 서명되지 않은 경우, GUID는 실행 파일의 경로와 영구적으로 연결된다. 실행 파일의 경로를 변경하면 트레이 아이콘 생성이 중단되며, 새로운 GUID를 사용해야 한다. 그러나 GUID 매개변수는 코드 서명된 실행 파일과 함께 사용하는 것을 강력히 권장한다. 애플리케이션이 여러 트레이 아이콘을 정의하는 경우, 각 아이콘은 별도의 GUID를 사용해야 한다.

image와 연결된 새로운 트레이 아이콘을 생성한다.

인스턴스 이벤트​

Tray 모듈은 다음과 같은 이벤트를 발생시킨다:

이벤트: 'click'​

반환값:

트레이 아이콘이 클릭될 때 발생하는 이벤트.

리눅스에서는 트레이 아이콘이 활성화될 때 이 이벤트가 발생하며, 반드시 마우스 왼쪽 클릭일 필요는 없음에 유의한다.

이벤트: 'right-click' macOS Windows​

반환값:

트레이 아이콘을 오른쪽 클릭할 때 발생하는 이벤트이다.

이벤트: 'double-click' macOS Windows​

반환값:

트레이 아이콘을 더블 클릭할 때 발생하는 이벤트다.

이벤트: 'middle-click' Windows​

반환값:

트레이 아이콘을 마우스 중간 버튼으로 클릭했을 때 발생한다.

이벤트: 'balloon-show' Windows​

트레이 풍선이 표시될 때 발생한다.

이벤트: 'balloon-click' 윈도우​

트레이 풍선을 클릭할 때 발생하는 이벤트이다.

이벤트: 'balloon-closed' 윈도우​

트레이 풍선이 시간 초과로 인해 자동으로 닫히거나 사용자가 직접 닫을 때 발생하는 이벤트다.

이벤트: 'drop' macOS​

드래그한 아이템이 트레이 아이콘 위에 드롭될 때 발생한다.

이벤트: 'drop-files' macOS​

반환값:

  • event Event
  • files string[] - 드래그한 파일의 경로 목록

트레이 아이콘에 파일을 드래그 앤 드롭했을 때 발생하는 이벤트다.

이벤트: 'drop-text' macOS​

반환값:

  • event Event
  • text string - 드래그한 텍스트 문자열

트레이 아이콘에 드래그한 텍스트를 놓았을 때 발생한다.

이벤트: 'drag-enter' macOS​

드래그 작업이 트레이 아이콘 안으로 들어올 때 발생한다.

이벤트: 'drag-leave' macOS​

트레이 아이콘에서 드래그 작업이 끝날 때 발생한다.

이벤트: 'drag-end' macOS​

트레이에서 드래그 작업이 끝나거나 다른 위치에서 드래그 작업이 종료될 때 발생한다.

이벤트: 'mouse-up' macOS​

반환값:

트레이 아이콘을 클릭한 후 마우스 버튼을 놓을 때 발생한다.

참고: tray.setContextMenu를 사용해 트레이에 컨텍스트 메뉴를 설정한 경우, macOS의 제약으로 인해 이 이벤트가 발생하지 않는다.

이벤트: 'mouse-down' macOS​

반환값:

트레이 아이콘을 마우스로 클릭할 때 발생한다.

이벤트: 'mouse-enter' macOS Windows​

반환값:

트레이 아이콘에 마우스가 진입할 때 발생한다.

이벤트: 'mouse-leave' macOS Windows​

반환값:

트레이 아이콘에서 마우스가 벗어날 때 발생한다.

이벤트: 'mouse-move' macOS Windows​

반환값:

트레이 아이콘 영역에서 마우스가 움직일 때 발생하는 이벤트다.

인스턴스 메서드​

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

tray.destroy()​

트레이 아이콘을 즉시 제거한다.

tray.setImage(image)​

트레이 아이콘에 연결된 image를 설정한다.

tray.setPressedImage(image) macOS​

macOS에서 트레이 아이콘을 눌렀을 때 표시될 이미지를 설정한다.

tray.setToolTip(toolTip)​

  • toolTip string

트레이 아이콘에 마우스를 올렸을 때 표시될 툴팁 텍스트를 설정한다.

tray.setTitle(title[, options]) macOS​

  • title string
  • options Object (선택 사항)
    • fontType string (선택 사항) - 표시할 폰트 패밀리 변형을 지정한다. monospaced 또는 monospacedDigit을 사용할 수 있다. monospaced는 macOS 10.15 이상에서 사용 가능하다. 값을 지정하지 않으면 기본 시스템 폰트를 사용한다.

상태 바에 있는 트레이 아이콘 옆에 표시될 제목을 설정한다. (ANSI 색상 지원)

tray.getTitle() macOS​

string 타입의 값을 반환한다. 이 값은 상태 표시줄의 트레이 아이콘 옆에 표시되는 제목이다.

tray.setIgnoreDoubleClickEvents(ignore) macOS​

  • ignore boolean

더블 클릭 이벤트를 무시할지 여부를 설정한다. 이 기능을 활성화하면 트레이 아이콘의 모든 개별 클릭을 감지할 수 있다.

기본값은 false로 설정되어 있다.

tray.getIgnoreDoubleClickClickEvents() macOS​

boolean 타입을 반환한다. 더블 클릭 이벤트가 무시되는지 여부를 나타낸다.

tray.displayBalloon(options) Windows​

  • options Object
    • icon (NativeImage | string) (선택 사항) - iconType이 custom일 때 사용할 아이콘.
    • iconType string (선택 사항) - none, info, warning, error, custom 중 하나. 기본값은 custom.
    • title string
    • content string
    • largeIcon boolean (선택 사항) - 큰 버전의 아이콘을 사용. 기본값은 true. NIIF_LARGE_ICON에 매핑.
    • noSound boolean (선택 사항) - 관련 소리를 재생하지 않음. 기본값은 false. NIIF_NOSOUND에 매핑.
    • respectQuietTime boolean (선택 사항) - 현재 사용자가 "조용한 시간" 중일 때 풍선 알림을 표시하지 않음. 기본값은 false. NIIF_RESPECT_QUIET_TIME에 매핑.

트레이 풍선 알림을 표시한다.

tray.removeBalloon() Windows​

트레이 풍선을 제거한다.

tray.focus() Windows​

이 메서드는 작업 표시줄의 알림 영역으로 포커스를 되돌린다. 알림 영역 아이콘은 UI 작업을 마쳤을 때 이 메시지를 사용해야 한다. 예를 들어, 아이콘이 바로가기 메뉴를 표시하고 있지만 사용자가 ESC 키를 눌러 취소한 경우, tray.focus()를 사용해 알림 영역으로 포커스를 돌려야 한다.

tray.popUpContextMenu([menu, position]) macOS Windows​

  • menu Menu (선택 사항)
  • position Point (선택 사항) - 팝업 메뉴의 위치

트레이 아이콘의 컨텍스트 메뉴를 팝업으로 표시한다. menu를 전달하면 트레이 아이콘의 컨텍스트 메뉴 대신 해당 메뉴가 표시된다.

position은 윈도우에서만 사용 가능하며, 기본값은 (0, 0)이다.

tray.closeContextMenu() macOS Windows​

tray.setContextMenu()로 설정한 열려 있는 컨텍스트 메뉴를 닫는다.

tray.setContextMenu(menu)​

  • menu Menu | null

아이콘의 컨텍스트 메뉴를 설정한다.

tray.getBounds() macOS Windows​

Rectangle 타입을 반환한다.

이 트레이 아이콘의 bounds를 객체로 반환한다.

tray.isDestroyed()​

boolean 타입의 값을 반환한다. 트레이 아이콘이 파괴되었는지 여부를 나타낸다.