Skip to main content

Class: MenuItem

Class: MenuItem​

네이티브 애플리케이션 메뉴와 컨텍스트 메뉴에 항목을 추가한다.

프로세스: Main

예제는 Menu를 참고한다.

new MenuItem(options)​

  • options Object
    • click Function (선택 사항) - 메뉴 항목을 클릭할 때 click(menuItem, window, event) 형태로 호출된다.
      • menuItem MenuItem
      • window BaseWindow | undefined - 윈도우가 열려 있지 않으면 정의되지 않는다.
      • event KeyboardEvent
    • role string (선택 사항) - undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, showSubstitutions, toggleSmartQuotes, toggleSmartDashes, toggleTextReplacement, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, showAllTabs, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow 또는 windowMenu 중 하나로 설정할 수 있다. 이 속성이 지정되면 click 속성은 무시된다. roles를 참고한다.
    • type string (선택 사항) - normal, separator, submenu, checkbox 또는 radio 중 하나로 설정할 수 있다.
    • label string (선택 사항)
    • sublabel string (선택 사항)
    • toolTip string (선택 사항) macOS - 이 메뉴 항목에 대한 호버 텍스트.
    • accelerator Accelerator (선택 사항)
    • icon (NativeImage | string) (선택 사항)
    • enabled boolean (선택 사항) - false로 설정하면 메뉴 항목이 회색으로 표시되고 클릭할 수 없게 된다.
    • acceleratorWorksWhenHidden boolean (선택 사항) macOS - 기본값은 true이며, false로 설정하면 항목이 보이지 않을 때 액셀러레이터가 동작하지 않는다.
    • visible boolean (선택 사항) - false로 설정하면 메뉴 항목이 완전히 숨겨진다.
    • checked boolean (선택 사항) - checkbox 또는 radio 타입 메뉴 항목에만 지정해야 한다.
    • registerAccelerator boolean (선택 사항) Linux Windows - false로 설정하면 액셀러레이터가 시스템에 등록되지 않지만, 여전히 표시된다. 기본값은 true이다.
    • sharingItem SharingItem (선택 사항) macOS - role이 shareMenu일 때 공유할 항목.
    • submenu (MenuItemConstructorOptions[] | Menu) (선택 사항) - submenu 타입 메뉴 항목에 지정해야 한다. submenu가 지정되면 type: 'submenu'는 생략할 수 있다. 값이 Menu가 아니면 Menu.buildFromTemplate을 사용해 자동으로 변환된다.
    • id string (선택 사항) - 단일 메뉴 내에서 고유한 값. 정의되면 position 속성에서 이 항목을 참조할 수 있다.
    • before string[] (선택 사항) - 지정된 id를 가진 항목 앞에 이 항목을 삽입한다. 참조된 항목이 존재하지 않으면 메뉴 끝에 삽입된다. 또한 이 항목은 참조된 항목과 같은 "그룹"에 배치된다.
    • after string[] (선택 사항) - 지정된 id를 가진 항목 뒤에 이 항목을 삽입한다. 참조된 항목이 존재하지 않으면 메뉴 끝에 삽입된다.
    • beforeGroupContaining string[] (선택 사항) - 단일 컨텍스트 메뉴가 지정된 id를 가진 항목의 그룹 앞에 자신의 그룹을 배치할 수 있도록 한다.
    • afterGroupContaining string[] (선택 사항) - 단일 컨텍스트 메뉴가 지정된 id를 가진 항목의 그룹 뒤에 자신의 그룹을 배치할 수 있도록 한다.

참고: acceleratorWorksWhenHidden은 macOS 전용으로 지정되었다. Windows와 Linux에서는 항목이 숨겨져 있을 때도 액셀러레이터가 항상 동작하기 때문이다. 이 옵션은 사용자가 이를 끌 수 있도록 제공되며, macOS 네이티브 개발에서도 가능한 기능이다.

역할(Role) 설정​

역할(Role)은 메뉴 아이템에 미리 정의된 동작을 부여한다.

표준 역할과 일치하는 메뉴 아이템에는 click 함수를 통해 수동으로 동작을 구현하기보다 role을 지정하는 것이 좋다. 내장된 role 동작은 각 플랫폼에 최적화된 네이티브 경험을 제공한다.

role을 사용할 때 label과 accelerator 값은 선택 사항이며, 각 플랫폼에 맞는 기본값이 자동으로 설정된다.

모든 메뉴 아이템은 role, label 또는 구분자(separator)인 경우 type 중 하나를 반드시 가져야 한다.

role 속성은 다음과 같은 값을 가질 수 있다:

  • undo
  • about - 네이티브 about 패널을 실행한다. (윈도우에서는 커스텀 메시지 박스를 사용한다.)
  • redo
  • cut
  • copy
  • paste
  • pasteAndMatchStyle
  • selectAll
  • delete
  • minimize - 현재 윈도우를 최소화한다.
  • close - 현재 윈도우를 닫는다.
  • quit - 애플리케이션을 종료한다.
  • reload - 현재 윈도우를 다시 로드한다.
  • forceReload - 캐시를 무시하고 현재 윈도우를 다시 로드한다.
  • toggleDevTools - 현재 윈도우에서 개발자 도구를 토글한다.
  • togglefullscreen - 현재 윈도우의 전체 화면 모드를 토글한다.
  • resetZoom - 포커스된 페이지의 확대/축소 수준을 원래 크기로 재설정한다.
  • zoomIn - 포커스된 페이지를 10% 확대한다.
  • zoomOut - 포커스된 페이지를 10% 축소한다.
  • toggleSpellChecker - 내장 맞춤법 검사기를 활성화/비활성화한다.
  • fileMenu - 기본 "파일" 메뉴 전체 (닫기 / 종료)
  • editMenu - 기본 "편집" 메뉴 전체 (실행 취소, 복사 등)
  • viewMenu - 기본 "보기" 메뉴 전체 (다시 로드, 개발자 도구 토글 등)
  • windowMenu - 기본 "윈도우" 메뉴 전체 (최소화, 확대 등)

다음 역할은 _macOS_에서만 사용 가능하다:

  • appMenu - 기본 "앱" 메뉴 전체 (정보, 서비스 등)
  • hide - hide 동작에 매핑한다.
  • hideOthers - hideOtherApplications 동작에 매핑한다.
  • unhide - unhideAllApplications 동작에 매핑한다.
  • showSubstitutions - orderFrontSubstitutionsPanel 동작에 매핑한다.
  • toggleSmartQuotes - toggleAutomaticQuoteSubstitution 동작에 매핑한다.
  • toggleSmartDashes - toggleAutomaticDashSubstitution 동작에 매핑한다.
  • toggleTextReplacement - toggleAutomaticTextReplacement 동작에 매핑한다.
  • startSpeaking - startSpeaking 동작에 매핑한다.
  • stopSpeaking - stopSpeaking 동작에 매핑한다.
  • front - arrangeInFront 동작에 매핑한다.
  • zoom - performZoom 동작에 매핑한다.
  • toggleTabBar - toggleTabBar 동작에 매핑한다.
  • selectNextTab - selectNextTab 동작에 매핑한다.
  • selectPreviousTab - selectPreviousTab 동작에 매핑한다.
  • showAllTabs - showAllTabs 동작에 매핑한다.
  • mergeAllWindows - mergeAllWindows 동작에 매핑한다.
  • moveTabToNewWindow - moveTabToNewWindow 동작에 매핑한다.
  • window - 서브메뉴는 "윈도우" 메뉴이다.
  • help - 서브메뉴는 "도움말" 메뉴이다.
  • services - 서브메뉴는 "서비스" 메뉴이다. 이는 애플리케이션 메뉴에서만 사용되며, macOS 앱의 컨텍스트 메뉴에서 사용되는 "서비스" 서브메뉴와는 다르다. 후자는 Electron에서 구현되지 않는다.
  • recentDocuments - 서브메뉴는 "최근 문서 열기" 메뉴이다.
  • clearRecentDocuments - clearRecentDocuments 동작에 매핑한다.
  • shareMenu - 서브메뉴는 공유 메뉴이다. 공유할 아이템을 지정하기 위해 sharingItem 속성도 설정해야 한다.

macOS에서 role을 지정할 때, label과 accelerator만 메뉴 아이템에 영향을 미친다. 다른 모든 옵션은 무시된다. 소문자 role(예: toggledevtools)도 여전히 지원된다.

참고: macOS 트레이의 최상위 메뉴 아이템에는 enabled와 visibility 속성을 사용할 수 없다.

인스턴스 속성​

MenuItem 인스턴스에서 사용할 수 있는 속성은 다음과 같다:

menuItem.id는 해당 항목의 고유 식별자를 나타내는 문자열이다. 이 속성은 동적으로 변경할 수 있다.

menuItem.label은 아이템의 보이는 레이블을 나타내는 문자열이다.

MenuItem이 클릭 이벤트를 받았을 때 실행되는 함수다. menuItem.click(event, focusedWindow, focusedWebContents)와 같은 형식으로 호출할 수 있다.

menuItem.submenu

해당 메뉴 항목에 하위 메뉴가 존재하는 경우, 이를 포함하는 Menu (선택적) 객체를 나타낸다.

menuItem.type은 아이템의 타입을 나타내는 문자열이다. normal, separator, submenu, checkbox, radio 중 하나의 값을 가질 수 있다.

menuItem.role은 선택적으로 설정할 수 있는 문자열이다. 이 값은 해당 아이템의 역할을 나타내며, 다음과 같은 값들 중 하나를 가질 수 있다: undo, redo, cut, copy, paste, pasteAndMatchStyle, delete, selectAll, reload, forceReload, toggleDevTools, resetZoom, zoomIn, zoomOut, toggleSpellChecker, togglefullscreen, window, minimize, close, help, about, services, hide, hideOthers, unhide, quit, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, showAllTabs, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow, windowMenu.

menuItem.accelerator는 해당 메뉴 아이템의 단축키를 나타내는 Accelerator 타입의 옵셔널 값이다. 단축키가 설정되어 있을 경우에만 존재한다.

이 속성은 메뉴 항목에 사용자가 할당한 단축키(user-assigned accelerator)를 나타내는 Accelerator | null 타입의 값이다.

참고: 이 속성은 MenuItem이 Menu에 추가된 후에만 초기화된다. 즉, Menu.buildFromTemplate를 통해 추가하거나 Menu.append()/insert()를 통해 추가한 이후에 접근해야 한다. 초기화 전에 접근하면 null을 반환한다.

menuItem.icon은 선택적으로 설정할 수 있는 속성으로, NativeImage 또는 string 타입의 값을 가진다. 이 속성은 해당 메뉴 항목의 아이콘을 나타낸다.

아이템의 부제목을 나타내는 string 타입의 값이다.

아이템의 호버 텍스트를 나타내는 string 타입의 값이다.

이 속성은 해당 메뉴 아이템이 활성화되어 있는지 여부를 나타내는 불리언 값이다. 이 값은 동적으로 변경할 수 있다.

해당 항목이 보이는지 여부를 나타내는 boolean 값이다. 이 속성은 동적으로 변경할 수 있다.

이 속성은 메뉴 아이템이 선택되었는지 여부를 나타내는 boolean 값이다. 이 속성은 동적으로 변경할 수 있다.

checkbox 메뉴 아이템을 선택하면 checked 속성이 켜지거나 꺼진다.

radio 메뉴 아이템을 클릭하면 해당 아이템의 checked 속성이 켜지고, 동일한 메뉴에 있는 인접한 모든 아이템의 checked 속성은 꺼진다.

추가 동작을 위해 click 함수를 추가할 수 있다.

시스템에 액셀러레이터를 실제로 등록할지, 아니면 단순히 표시만 할지를 나타내는 boolean 값이다.

이 속성은 동적으로 변경할 수 있다.

role이 shareMenu일 때 공유할 항목을 나타내는 SharingItem이다.

이 속성은 동적으로 변경할 수 있다.

menuItem.commandId는 각 아이템의 순차적 고유 식별자를 나타내는 number 타입의 값이다.

해당 아이템이 속한 Menu를 나타낸다.