fix: menu should allow focused BaseWindow
11 KiB
Class: MenuItem
Add items to native application menus and context menus.
Process: Main
See Menu
for examples.
new MenuItem(options)
options
Objectclick
Function (optional) - Will be called withclick(menuItem, window, event)
when the menu item is clicked.menuItem
MenuItemwindow
BaseWindow | undefined - This will not be defined if no window is open.event
KeyboardEvent
role
string (optional) - Can beundo
,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
orwindowMenu
- Define the action of the menu item, when specified theclick
property will be ignored. See roles.type
string (optional) - Can benormal
,separator
,submenu
,checkbox
orradio
.label
string (optional)sublabel
string (optional)toolTip
string (optional) macOS - Hover text for this menu item.accelerator
Accelerator (optional)icon
(NativeImage | string) (optional)enabled
boolean (optional) - If false, the menu item will be greyed out and unclickable.acceleratorWorksWhenHidden
boolean (optional) macOS - default istrue
, and whenfalse
will prevent the accelerator from triggering the item if the item is not visible.visible
boolean (optional) - If false, the menu item will be entirely hidden.checked
boolean (optional) - Should only be specified forcheckbox
orradio
type menu items.registerAccelerator
boolean (optional) Linux Windows - If false, the accelerator won't be registered with the system, but it will still be displayed. Defaults to true.sharingItem
SharingItem (optional) macOS - The item to share when therole
isshareMenu
.submenu
(MenuItemConstructorOptions[] | Menu) (optional) - Should be specified forsubmenu
type menu items. Ifsubmenu
is specified, thetype: 'submenu'
can be omitted. If the value is not aMenu
then it will be automatically converted to one usingMenu.buildFromTemplate
.id
string (optional) - Unique within a single menu. If defined then it can be used as a reference to this item by the position attribute.before
string[] (optional) - Inserts this item before the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu. Also implies that the menu item in question should be placed in the same “group” as the item.after
string[] (optional) - Inserts this item after the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu.beforeGroupContaining
string[] (optional) - Provides a means for a single context menu to declare the placement of their containing group before the containing group of the item with the specified id.afterGroupContaining
string[] (optional) - Provides a means for a single context menu to declare the placement of their containing group after the containing group of the item with the specified id.
Note: acceleratorWorksWhenHidden
is specified as being macOS-only because accelerators always work when items are hidden on Windows and Linux. The option is exposed to users to give them the option to turn it off, as this is possible in native macOS development.
Roles
Roles allow menu items to have predefined behaviors.
It is best to specify role
for any menu item that matches a standard role,
rather than trying to manually implement the behavior in a click
function.
The built-in role
behavior will give the best native experience.
The label
and accelerator
values are optional when using a role
and will
default to appropriate values for each platform.
Every menu item must have either a role
, label
, or in the case of a separator
a type
.
The role
property can have following values:
undo
about
- Trigger a native about panel (custom message box on Window, which does not provide its own).redo
cut
copy
paste
pasteAndMatchStyle
selectAll
delete
minimize
- Minimize current window.close
- Close current window.quit
- Quit the application.reload
- Reload the current window.forceReload
- Reload the current window ignoring the cache.toggleDevTools
- Toggle developer tools in the current window.togglefullscreen
- Toggle full screen mode on the current window.resetZoom
- Reset the focused page's zoom level to the original size.zoomIn
- Zoom in the focused page by 10%.zoomOut
- Zoom out the focused page by 10%.toggleSpellChecker
- Enable/disable builtin spell checker.fileMenu
- Whole default "File" menu (Close / Quit)editMenu
- Whole default "Edit" menu (Undo, Copy, etc.).viewMenu
- Whole default "View" menu (Reload, Toggle Developer Tools, etc.)windowMenu
- Whole default "Window" menu (Minimize, Zoom, etc.).
The following additional roles are available on macOS:
appMenu
- Whole default "App" menu (About, Services, etc.)hide
- Map to thehide
action.hideOthers
- Map to thehideOtherApplications
action.unhide
- Map to theunhideAllApplications
action.showSubstitutions
- Map to theorderFrontSubstitutionsPanel
action.toggleSmartQuotes
- Map to thetoggleAutomaticQuoteSubstitution
action.toggleSmartDashes
- Map to thetoggleAutomaticDashSubstitution
action.toggleTextReplacement
- Map to thetoggleAutomaticTextReplacement
action.startSpeaking
- Map to thestartSpeaking
action.stopSpeaking
- Map to thestopSpeaking
action.front
- Map to thearrangeInFront
action.zoom
- Map to theperformZoom
action.toggleTabBar
- Map to thetoggleTabBar
action.selectNextTab
- Map to theselectNextTab
action.selectPreviousTab
- Map to theselectPreviousTab
action.showAllTabs
- Map to theshowAllTabs
action.mergeAllWindows
- Map to themergeAllWindows
action.moveTabToNewWindow
- Map to themoveTabToNewWindow
action.window
- The submenu is a "Window" menu.help
- The submenu is a "Help" menu.services
- The submenu is a "Services" menu. This is only intended for use in the Application Menu and is not the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.recentDocuments
- The submenu is an "Open Recent" menu.clearRecentDocuments
- Map to theclearRecentDocuments
action.shareMenu
- The submenu is share menu. ThesharingItem
property must also be set to indicate the item to share.
When specifying a role
on macOS, label
and accelerator
are the only
options that will affect the menu item. All other options will be ignored.
Lowercase role
, e.g. toggledevtools
, is still supported.
Note: The enabled
and visibility
properties are not available for top-level menu items in the tray on macOS.
Instance Properties
The following properties are available on instances of MenuItem
:
menuItem.id
A string
indicating the item's unique id, this property can be
dynamically changed.
menuItem.label
A string
indicating the item's visible label.
menuItem.click
A Function
that is fired when the MenuItem receives a click event.
It can be called with menuItem.click(event, focusedWindow, focusedWebContents)
.
event
KeyboardEventfocusedWindow
BaseWindowfocusedWebContents
WebContents
menuItem.submenu
A Menu
(optional) containing the menu
item's submenu, if present.
menuItem.type
A string
indicating the type of the item. Can be normal
, separator
, submenu
, checkbox
or radio
.
menuItem.role
A string
(optional) indicating the item's role, if set. Can be 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
or windowMenu
menuItem.accelerator
An Accelerator
(optional) indicating the item's accelerator, if set.
menuItem.userAccelerator
Readonly macOS
An Accelerator | null
indicating the item's user-assigned accelerator for the menu item.
Note: This property is only initialized after the MenuItem
has been added to a Menu
. Either via Menu.buildFromTemplate
or via Menu.append()/insert()
. Accessing before initialization will just return null
.
menuItem.icon
A NativeImage | string
(optional) indicating the
item's icon, if set.
menuItem.sublabel
A string
indicating the item's sublabel.
menuItem.toolTip
macOS
A string
indicating the item's hover text.
menuItem.enabled
A boolean
indicating whether the item is enabled, this property can be
dynamically changed.
menuItem.visible
A boolean
indicating whether the item is visible, this property can be
dynamically changed.
menuItem.checked
A boolean
indicating whether the item is checked, this property can be
dynamically changed.
A checkbox
menu item will toggle the checked
property on and off when
selected.
A radio
menu item will turn on its checked
property when clicked, and
will turn off that property for all adjacent items in the same menu.
You can add a click
function for additional behavior.
menuItem.registerAccelerator
A boolean
indicating if the accelerator should be registered with the
system or just displayed.
This property can be dynamically changed.
menuItem.sharingItem
macOS
A SharingItem
indicating the item to share when the role
is shareMenu
.
This property can be dynamically changed.
menuItem.commandId
A number
indicating an item's sequential unique id.
menuItem.menu
A Menu
that the item is a part of.