跳转到主要内容

MenuItem

类: MenuItem​

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

进程：主进程

有关示例，请参阅 Menu。

警告

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

new MenuItem(options)​

  • options Object
    • click 函数 (可选) - 当菜单项被点击时，将使用 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 自动将其转换为 Menu。
    • id string (可选) - 在单个菜单中是唯一的。如果已定义，则可以使用此 id 作为对该项的引用。
    • 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，指示项的可见标签。

当 MenuItem 收到点击事件时触发的 Function。它可以被调用为 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。