Skip to main content

类：MenuItem

类：MenuItem​

¥Class: MenuItem

将项目添加到原生应用菜单和上下文菜单。

¥Add items to native application menus and context menus.

进程：主进程

¥Process: Main

示例请参见 Menu。

¥See Menu for examples.

new MenuItem(options)​

  • options 对象

    ¥options Object

    • click 功能（可选） - 单击菜单项时将使用 click(menuItem, window, event) 进行调用。

      ¥click Function (optional) - Will be called with click(menuItem, window, event) when the menu item is clicked.

      • menuItem MenuItem

      • window BaseWindow | 不明确的 - 如果没有打开窗口，则不会定义此值。

        ¥window BaseWindow | undefined - This will not be defined if no window is open.

      • event KeyboardEvent

    • 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、showSubstitutions、toggleSmartQuotes、toggleSmartDashes、toggleTextReplacement、startSpeaking、stopSpeaking、zoom、front、appMenu、fileMenu、editMenu、viewMenu、shareMenu、recentDocuments、toggleTabBar、selectNextTab、selectPreviousTab、showAllTabs、mergeAllWindows、clearRecentDocuments、moveTabToNewWindow 或 windowMenu - 定义菜单项的操作，指定时 click 属性将被忽略。参见 roles。

      ¥role string (optional) - 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, showSubstitutions, toggleSmartQuotes, toggleSmartDashes, toggleTextReplacement, startSpeaking, stopSpeaking, zoom, front, appMenu, fileMenu, editMenu, viewMenu, shareMenu, recentDocuments, toggleTabBar, selectNextTab, selectPreviousTab, showAllTabs, mergeAllWindows, clearRecentDocuments, moveTabToNewWindow or windowMenu - Define the action of the menu item, when specified the click property will be ignored. See roles.

    • type 字符串（可选） - 可以是 normal、separator、submenu、checkbox 或 radio。

      ¥type string (optional) - Can be normal, separator, submenu, checkbox or radio.

    • label 字符串（可选）

      ¥label string (optional)

    • sublabel 字符串（可选）

      ¥sublabel string (optional)

    • toolTip 字符串（可选）macOS - 悬停此菜单项的文本。

      ¥toolTip string (optional) macOS - Hover text for this menu item.

    • accelerator 加速器（可选）

      ¥accelerator Accelerator (optional)

    • icon（NativeImage | 字符串）（可选）

      ¥icon (NativeImage | string) (optional)

    • enabled 布尔值（可选） - 如果为 false，菜单项将显示为灰色且不可单击。

      ¥enabled boolean (optional) - If false, the menu item will be greyed out and unclickable.

    • acceleratorWorksWhenHidden 布尔值（可选）macOS - 默认为 true，当 false 时，如果项目不可见，将阻止加速器触发该项目。

      ¥acceleratorWorksWhenHidden boolean (optional) macOS - default is true, and when false will prevent the accelerator from triggering the item if the item is not visible.

    • visible 布尔值（可选） - 如果为 false，则菜单项将完全隐藏。

      ¥visible boolean (optional) - If false, the menu item will be entirely hidden.

    • checked 布尔值（可选） - 只能为 checkbox 或 radio 类型的菜单项指定。

      ¥checked boolean (optional) - Should only be specified for checkbox or radio type menu items.

    • registerAccelerator 布尔值（可选） Linux Windows - 如果为 false，则加速器不会在系统中注册，但仍会显示。默认为 true。

      ¥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 共享项目（可选）macOS - 当 role 为 shareMenu 时要共享的项目。

      ¥sharingItem SharingItem (optional) macOS - The item to share when the role is shareMenu.

    • submenu (MenuItemConstructorOptions[] | Menu)（可选） - 应为 submenu 类型菜单项指定。如果指定了 submenu，则可以省略 type: 'submenu'。如果该值不是 Menu，则会使用 Menu.buildFromTemplate 自动转换为值。

      ¥submenu (MenuItemConstructorOptions[] | Menu) (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 then it will be automatically converted to one using Menu.buildFromTemplate.

    • id 字符串（可选） - 在单一菜单中独一无二。如果定义了，则可以通过位置属性将其用作对此项目的引用。

      ¥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 字符串[]（可选） - 将此项目插入到具有指定 id 的项目之前。如果引用的项目不存在，该项目将被插入到菜单的末尾。还意味着相关菜单项应放置在与该项目相同的“组”中。

      ¥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 字符串[]（可选） - 将此项目插入到具有指定 id 的项目之后。如果引用的项目不存在，该项目将被插入到菜单的末尾。

      ¥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 字符串[]（可选） - 为单个上下文菜单提供一种方法，以声明其包含组位于具有指定 id 的项目的包含组之前。

      ¥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 字符串[]（可选） - 为单个上下文菜单提供一种方法，以声明其包含组在具有指定 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.

注意：acceleratorWorksWhenHidden 被指定为仅限 macOS，因为当 Windows 和 Linux 上的项目隐藏时，加速器始终起作用。该选项向用户公开，让他们可以选择关闭它，因为这在原生 macOS 开发中是可能的。

¥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.

最好为与标准角色匹配的任何菜单项指定 role，而不是尝试在 click 函数中手动实现该行为。内置的 role 行为将提供最佳的原生体验。

¥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.

使用 role 时，label 和 accelerator 值是可选的，并且将默认为每个平台的适当值。

¥The label and accelerator values are optional when using a role and will default to appropriate values for each platform.

每个菜单项必须有 role、label，或者在有分隔符的情况下有 type。

¥Every menu item must have either a role, label, or in the case of a separator a type.

role 属性可以具有以下值：

¥The role property can have following values:

  • undo

  • about - 触发原生关于面板（Window 上的自定义消息框，它不提供自己的消息框）。

    ¥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 - Minimize current window.

  • close - 关闭当前窗口。

    ¥close - Close current window.

  • quit - 退出应用。

    ¥quit - Quit the application.

  • reload - 重新加载当前窗口。

    ¥reload - Reload the current window.

  • forceReload - 重新加载当前窗口，忽略缓存。

    ¥forceReload - Reload the current window ignoring the cache.

  • toggleDevTools - 在当前窗口中切换开发者工具。

    ¥toggleDevTools - Toggle developer tools in the current window.

  • togglefullscreen - 在当前窗口上切换全屏模式。

    ¥togglefullscreen - Toggle full screen mode on the current window.

  • resetZoom - 将焦点页面的缩放级别重置为原始大小。

    ¥resetZoom - Reset the focused page's zoom level to the original size.

  • zoomIn - 将焦点页面放大 10%。

    ¥zoomIn - Zoom in the focused page by 10%.

  • zoomOut - 将焦点页面缩小 10%。

    ¥zoomOut - Zoom out the focused page by 10%.

  • toggleSpellChecker - 启用/禁用内置拼写检查器。

    ¥toggleSpellChecker - Enable/disable builtin spell checker.

  • fileMenu - 整个默认 "文件" 菜单（关闭/退出）

    ¥fileMenu - Whole default "File" menu (Close / Quit)

  • editMenu - 整个默认 "编辑" 菜单（撤消、复制等）。

    ¥editMenu - Whole default "Edit" menu (Undo, Copy, etc.).

  • viewMenu - 整个默认 "View" 菜单（重新加载、切换开发者工具等）

    ¥viewMenu - Whole default "View" menu (Reload, Toggle Developer Tools, etc.)

  • windowMenu - 整个默认 "窗户" 菜单（最小化、缩放等）。

    ¥windowMenu - Whole default "Window" menu (Minimize, Zoom, etc.).

macOS 上还提供以下附加角色：

¥The following additional roles are available on macOS:

  • appMenu - 整个默认 "应用" 菜单（关于、服务等）

    ¥appMenu - Whole default "App" menu (About, Services, etc.)

  • hide - 映射到 hide 操作。

    ¥hide - Map to the hide action.

  • hideOthers - 映射到 hideOtherApplications 操作。

    ¥hideOthers - Map to the hideOtherApplications action.

  • unhide - 映射到 unhideAllApplications 操作。

    ¥unhide - Map to the unhideAllApplications action.

  • showSubstitutions - 映射到 orderFrontSubstitutionsPanel 操作。

    ¥showSubstitutions - Map to the orderFrontSubstitutionsPanel action.

  • toggleSmartQuotes - 映射到 toggleAutomaticQuoteSubstitution 操作。

    ¥toggleSmartQuotes - Map to the toggleAutomaticQuoteSubstitution action.

  • toggleSmartDashes - 映射到 toggleAutomaticDashSubstitution 操作。

    ¥toggleSmartDashes - Map to the toggleAutomaticDashSubstitution action.

  • toggleTextReplacement - 映射到 toggleAutomaticTextReplacement 操作。

    ¥toggleTextReplacement - Map to the toggleAutomaticTextReplacement action.

  • startSpeaking - 映射到 startSpeaking 操作。

    ¥startSpeaking - Map to the startSpeaking action.

  • stopSpeaking - 映射到 stopSpeaking 操作。

    ¥stopSpeaking - Map to the stopSpeaking action.

  • front - 映射到 arrangeInFront 操作。

    ¥front - Map to the arrangeInFront action.

  • zoom - 映射到 performZoom 操作。

    ¥zoom - Map to the performZoom action.

  • toggleTabBar - 映射到 toggleTabBar 操作。

    ¥toggleTabBar - Map to the toggleTabBar action.

  • selectNextTab - 映射到 selectNextTab 操作。

    ¥selectNextTab - Map to the selectNextTab action.

  • selectPreviousTab - 映射到 selectPreviousTab 操作。

    ¥selectPreviousTab - Map to the selectPreviousTab action.

  • showAllTabs - 映射到 showAllTabs 操作。

    ¥showAllTabs - Map to the showAllTabs action.

  • mergeAllWindows - 映射到 mergeAllWindows 操作。

    ¥mergeAllWindows - Map to the mergeAllWindows action.

  • moveTabToNewWindow - 映射到 moveTabToNewWindow 操作。

    ¥moveTabToNewWindow - Map to the moveTabToNewWindow action.

  • window - 子菜单是 "窗户" 菜单。

    ¥window - The submenu is a "Window" menu.

  • help - 子菜单是 "帮助" 菜单。

    ¥help - The submenu is a "Help" menu.

  • services - 子菜单是 "服务" 菜单。这仅适用于应用菜单，与 macOS 应用上下文菜单中使用的 "服务" 子菜单不同，后者未在 Electron 中实现。

    ¥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 - 子菜单是 "最近打开" 菜单。

    ¥recentDocuments - The submenu is an "Open Recent" menu.

  • clearRecentDocuments - 映射到 clearRecentDocuments 操作。

    ¥clearRecentDocuments - Map to the clearRecentDocuments action.

  • shareMenu - 子菜单是 分享菜单。还必须设置 sharingItem 属性以指示要共享的项目。

    ¥shareMenu - The submenu is share menu. The sharingItem property must also be set to indicate the item to share.

在 macOS 上指定 role 时，label 和 accelerator 是唯一会影响菜单项的选项。所有其他选项将被忽略。小写 role，例如 toggledevtools，仍然支持。

¥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.

注意：enabled 和 visibility 属性不可用于 macOS 托盘中的顶层菜单项。

¥Note: The enabled and visibility properties are not available for top-level menu items in the tray on macOS.

实例属性​

¥Instance Properties

以下属性在 MenuItem 的实例上可用：

¥The following properties are available on instances of MenuItem:

string 表示该项目的唯一 id，该属性可以动态更改。

¥A string indicating the item's unique id, this property can be dynamically changed.

string 表示该项目的可见标签。

¥A string indicating the item's visible label.

当 MenuItem 收到单击事件时触发的 Function。可以用 menuItem.click(event, focusedWindow, focusedWebContents) 来调用。

¥A Function that is fired when the MenuItem receives a click event. It can be called with menuItem.click(event, focusedWindow, focusedWebContents).

包含菜单项的子菜单（如果存在）的 Menu（可选）。

¥A Menu (optional) containing the menu item's submenu, if present.

string 指示项目的类型。可以是 normal、separator、submenu、checkbox 或 radio。

¥A string indicating the type of the item. Can be normal, separator, submenu, checkbox or radio.

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、startSpeaking、stopSpeaking、zoom、front、appMenu、fileMenu、editMenu、viewMenu、shareMenu、recentDocuments、toggleTabBar、selectNextTab、selectPreviousTab、showAllTabs、mergeAllWindows、clearRecentDocuments、moveTabToNewWindow 或 windowMenu

¥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

Accelerator（可选）指示项目的加速器（如果已设置）。

¥An Accelerator (optional) indicating the item's accelerator, if set.

¥menuItem.userAccelerator Readonly macOS

Accelerator | null 指示菜单项的 用户指定的加速器。

¥An Accelerator | null indicating the item's user-assigned accelerator for the menu item.

注意：该属性仅在 MenuItem 添加到 Menu 后才会初始化。通过 Menu.buildFromTemplate 或通过 Menu.append()/insert()。初始化之前访问只会返回 null。

¥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.

NativeImage | string（可选）指示项目的图标（如果已设置）。

¥A NativeImage | string (optional) indicating the item's icon, if set.

string 表示该项目的子标签。

¥A string indicating the item's sublabel.

string 指示项目的悬停文本。

¥A string indicating the item's hover text.

一个 boolean 表示该项是否启用，这个属性可以动态改变。

¥A boolean indicating whether the item is enabled, this property can be dynamically changed.

boolean 指示该项是否可见，该属性可以动态更改。

¥A boolean indicating whether the item is visible, this property can be dynamically changed.

一个 boolean 表示该项是否被选中，这个属性可以动态改变。

¥A boolean indicating whether the item is checked, this property can be dynamically changed.

选中 checkbox 菜单项后，将打开和关闭 checked 属性。

¥A checkbox menu item will toggle the checked property on and off when selected.

单击 radio 菜单项将打开其 checked 属性，并将关闭同一菜单中所有相邻项的该属性。

¥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.

你可以添加 click 函数以实现其他行为。

¥You can add a click function for additional behavior.

boolean 指示加速器是否应在系统中注册或仅显示。

¥A boolean indicating if the accelerator should be registered with the system or just displayed.

该属性可以动态更改。

¥This property can be dynamically changed.

SharingItem 表示当 role 为 shareMenu 时要共享的项目。

¥A SharingItem indicating the item to share when the role is shareMenu.

该属性可以动态更改。

¥This property can be dynamically changed.

number 指示项目的连续唯一 ID。

¥A number indicating an item's sequential unique id.

该项目所属的 Menu。

¥A Menu that the item is a part of.