跳到主要内容

类: MenuItem

类: MenuItem​

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

进程: 主进程

有关示例，请参见 Menu。

警告

Electron 的内置类不能在用户代码中被继承。 有关更多信息，请参见 常见问题解答。

new MenuItem(options)​

  • options 对象
    • 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
      • header - 仅在 macOS 14 及更高版本上可用。
      • palette - 仅在 macOS 14 及更高版本上可用。
    • label string (可选)
    • sublabel string (可选) macOS - 在 macOS >= 14.4 中可用
    • 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，而不是尝试在 click 函数中手动实现该行为。 内置的 role 行为将提供最佳的本机体验。

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

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

role 属性可以具有以下值

  • undo
  • about - 触发本机关于面板 (Windows 上的自定义消息框，不提供自己的消息框)。
  • 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。

注意

enabled 和 visibility 属性对于 macOS 托盘中的顶级菜单项不可用。

实例属性​

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

一个 string，指示项目的唯一 ID，此属性可以动态更改。

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

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

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

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

注意

header 和 palette 仅在 macOS 14 及更高版本上可用。

一个 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

一个 Accelerator (可选)，指示项目的快捷键（如果已设置）。

一个 Accelerator | null，指示菜单项的 用户分配的快捷键。

注意

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

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

一个 string，指示项目的子标签。

一个 string，指示项目的悬停文本。

一个 boolean，指示项目是否已启用，此属性可以动态更改。

一个 boolean，指示项目是否可见，此属性可以动态更改。

一个 boolean，指示项目是否已选中，此属性可以动态更改。

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

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

您可以添加一个 click 函数以获得其他行为。

一个 boolean，指示是否应在系统中注册快捷键或仅显示快捷键。

此属性可以动态更改。

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

此属性可以动态更改。

一个 number，指示项目的顺序唯一 ID。

项目所属的 Menu。