菜单项¶

类：菜单项¶

向原生应用程序菜单和上下文菜单添加菜单项。

进程：主进程

有关示例，请参阅 Menu。

[!WARNING] Electron 的内置类无法在用户代码中被子类化。 更多信息，请参阅常见问题解答。

new MenuItem(options)¶

• options 对象
• click 函数（可选）- 当菜单项被点击时，将以 click(menuItem, window, event) 调用。
  • menuItem MenuItem
  • window BaseWindow | undefined - 如果没有打开窗口，则不会定义此值。
  • 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 属性将被忽略。请参阅角色。
• type 字符串（可选）
  • normal
  • separator
  • submenu
  • checkbox
  • radio
  • header - 仅在 macOS 14 及更高版本上可用。
  • palette - 仅在 macOS 14 及更高版本上可用。
• label 字符串（可选）
• accessibilityLabel 字符串（可选） macOS
• sublabel 字符串（可选） macOS - 在 macOS >= 14.4 中可用
• toolTip 字符串（可选） macOS - 此菜单项的悬停文本。
• accelerator 字符串（可选）- 一个加速器字符串。
• icon (NativeImage | 字符串)（可选）- 可以是 NativeImage 或图标的文件路径。
• enabled 布尔值（可选）- 如果为 false，菜单项将变灰且 不可点击。
• acceleratorWorksWhenHidden 布尔值（可选） macOS - 默认为 true；当为 false 时，如果菜单项不可见，将阻止加速器触发该菜单项。
• visible 布尔值（可选）- 如果为 false，菜单项将完全隐藏。
• checked 布尔值（可选）- 仅应针对 checkbox 或 radio 类型的 菜单项指定。
• registerAccelerator 布尔值（可选） Linux Windows - 如果为 false，加速器不会向系统注册， 但仍会显示。默认为 true。
• sharingItem SharingItem（可选） macOS - 当 role 为 shareMenu 时要共享的项。
• submenu (MenuItemConstructorOptions[] | Menu)（可选）- 应针对 submenu 类型的菜单项指定。如果指定了 submenu，则可以省略 type: 'submenu'。 如果该值不是 Menu，则会使用 Menu.buildFromTemplate 自动将其转换为一个。
• id 字符串（可选）- 在单个菜单内唯一。如果已定义，则位置属性可以使用它 作为对此菜单项的引用。
• before 字符串数组（可选）- 将此菜单项插入到具有指定 id 的菜单项之前。如果 引用的菜单项不存在，则此菜单项将插入到菜单末尾。这也意味着 相关菜单项应与该菜单项位于同一“组”中。
• after 字符串数组（可选）- 将此菜单项插入到具有指定 id 的菜单项之后。如果 引用的菜单项不存在，则此菜单项将插入到菜单末尾。
• beforeGroupContaining 字符串数组（可选）- 为单个上下文菜单提供一种方式，用于声明 其包含组的位置在具有指定 id 的菜单项的包含组之前。
• afterGroupContaining 字符串数组（可选）- 为单个上下文菜单提供一种方式，用于声明 其包含组的位置在具有指定 id 的菜单项的包含组之后。
• badge MenuItemBadge（可选） macOS - 与标签一起显示的徽章， 可以是系统样式的计数（alerts、updates、new-items）或自定义字符串。 仅在 macOS 14 及更高版本上可用。不会在 Dock 菜单 中显示。

[!NOTE] acceleratorWorksWhenHidden 被指定为仅适用于 macOS，因为在 Windows 和 Linux 上，当菜单项隐藏时加速器始终有效。此选项向用户公开，以便他们可以选择将其关闭，因为在原生 macOS 开发中这是可能的。

实例属性¶

以下属性可用于 MenuItem 实例：

menuItem.id¶

一个 string，指示菜单项的唯一 id。

此属性可以动态更改。

menuItem.label¶

一个 string，指示菜单项的可见标签。

此属性可以动态更改。

menuItem.accessibilityLabel macOS¶

一个 string，指示菜单项的无障碍标签（供辅助技术使用），如果已设置。

此属性可以动态更改。

menuItem.click¶

一个 Function，当 MenuItem 接收到点击事件时触发。 可以使用 menuItem.click(event, focusedWindow, focusedWebContents) 调用它。

• event KeyboardEvent
• focusedWindow BaseWindow
• focusedWebContents WebContents

menuItem.submenu¶

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

menuItem.type¶

一个 string，指示菜单项的类型。可以是 normal、separator、submenu、checkbox、radio、header 或 palette。

[!NOTE] header 和 palette 仅在 macOS 14 及以上版本中可用。

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

menuItem.accelerator¶

一个 Accelerator | null，如果已设置，表示该菜单项的快捷键。

menuItem.userAccelerator 只读 macOS¶

一个 Accelerator | null，表示该菜单项的用户指定快捷键。

[!NOTE] 此属性仅在 MenuItem 被添加到 Menu 之后才会初始化。可以通过 Menu.buildFromTemplate 或 Menu.append()/insert() 添加。在初始化之前访问将只返回 null。

menuItem.icon¶

一个 NativeImage | string（可选），如果已设置，表示该菜单项的图标。

此属性可以动态更改。

menuItem.sublabel¶

一个 string，表示该菜单项的副标签。

此属性可以动态更改。

menuItem.toolTip macOS¶

一个 string，表示该菜单项的悬停文本。

menuItem.enabled¶

一个 boolean，表示该菜单项是否启用。

此属性可以动态更改。

menuItem.visible¶

一个 boolean，表示该菜单项是否可见。

此属性可以动态更改。

menuItem.checked¶

一个 boolean，表示该菜单项是否已勾选。

此属性可以动态更改。

checkbox 菜单项在选中时会切换 checked 属性的开/关状态。

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

你可以添加一个 click 函数以实现额外行为。

menuItem.registerAccelerator Linux Windows¶

一个 boolean，表示是否应将快捷键注册到系统，或仅显示。

此属性可以动态更改。

menuItem.sharingItem macOS¶

一个 SharingItem，当 role 为 shareMenu 时表示要共享的项。

此属性可以动态更改。

menuItem.commandId¶

一个 number，表示菜单项的顺序唯一 ID。

menuItem.menu¶

一个该菜单项所属的 Menu。

menuItem.badge macOS¶

一个 MenuItemBadge（可选），表示菜单项的徽章。

此属性可以动态更改；将其设置为 undefined 会移除徽章。仅在 macOS 14 及以上版本中可用。

徽章不会显示在 Dock 菜单 中，但同一菜单项会在应用程序菜单中显示其徽章。