5ea05ddee7
This PR includes stricter testing for empty objects so that false context menus are not created along with the tests to ensure future compatibility.
134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
## Class: MenuItem
|
|
|
|
> Add items to native application menus and context menus.
|
|
|
|
Process: [Main](../glossary.md#main-process)
|
|
|
|
See [`Menu`](menu.md) for examples.
|
|
|
|
### `new MenuItem(options)`
|
|
|
|
* `options` Object
|
|
* `click` Function (optional) - Will be called with
|
|
`click(menuItem, browserWindow, event)` when the menu item is clicked.
|
|
* `menuItem` MenuItem
|
|
* `browserWindow` [BrowserWindow](browser-window.md)
|
|
* `event` Event
|
|
* `role` String (optional) - Define the action of the menu item, when specified the
|
|
`click` property will be ignored. See [roles](#roles).
|
|
* `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
|
|
`radio`.
|
|
* `label` String (optional)
|
|
* `sublabel` String (optional)
|
|
* `accelerator` [Accelerator](accelerator.md) (optional)
|
|
* `icon` ([NativeImage](native-image.md) | String) (optional)
|
|
* `enabled` Boolean (optional) - If false, the menu item will be greyed out and
|
|
unclickable.
|
|
* `visible` Boolean (optional) - If false, the menu item will be entirely hidden.
|
|
* `checked` Boolean (optional) - Should only be specified for `checkbox` or `radio` type
|
|
menu items.
|
|
* `submenu` (MenuItemConstructorOptions[] | [Menu](menu.md)) (optional) - Should be specified for `submenu` type menu items. If
|
|
`submenu` is specified, the `type: 'submenu'` can be omitted. If the value
|
|
is not a [`Menu`](menu.md) then it will be automatically converted to one using
|
|
`Menu.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.
|
|
* `position` String (optional) - This field allows fine-grained definition of the
|
|
specific location within a given menu.
|
|
|
|
### 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`
|
|
* `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%.
|
|
* `editMenu` - Whole default "Edit" menu (Undo, Copy, etc.).
|
|
* `windowMenu` - Whole default "Window" menu (Minimize, Close, etc.).
|
|
|
|
The following additional roles are available on _macOS_:
|
|
|
|
* `about` - Map to the `orderFrontStandardAboutPanel` action.
|
|
* `hide` - Map to the `hide` action.
|
|
* `hideOthers` - Map to the `hideOtherApplications` action.
|
|
* `unhide` - Map to the `unhideAllApplications` action.
|
|
* `startSpeaking` - Map to the `startSpeaking` action.
|
|
* `stopSpeaking` - Map to the `stopSpeaking` action.
|
|
* `front` - Map to the `arrangeInFront` action.
|
|
* `zoom` - Map to the `performZoom` action.
|
|
* `toggleTabBar` - Map to the `toggleTabBar` action.
|
|
* `selectNextTab` - Map to the `selectNextTab` action.
|
|
* `selectPreviousTab` - Map to the `selectPreviousTab` action.
|
|
* `mergeAllWindows` - Map to the `mergeAllWindows` action.
|
|
* `moveTabToNewWindow` - Map to the `moveTabToNewWindow` action.
|
|
* `window` - The submenu is a "Window" menu.
|
|
* `help` - The submenu is a "Help" menu.
|
|
* `services` - The submenu is a "Services" menu.
|
|
* `recentDocuments` - The submenu is an "Open Recent" menu.
|
|
* `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
|
|
|
|
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.
|
|
|
|
### Instance Properties
|
|
|
|
The following properties are available on instances of `MenuItem`:
|
|
|
|
#### `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.label`
|
|
|
|
A `String` representing the menu items visible label.
|
|
|
|
#### `menuItem.click`
|
|
|
|
A `Function` that is fired when the MenuItem receives a click event.
|