跳到主内容

类：MenuItem

类：MenuItem​

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

进程：主进程

参阅 Menu 查看示例。

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 属性。参阅 角色。
    • type string (可选) - 可以是 normal, separator, submenu, checkbox 或 radio。
    • label string (可选)
    • sublabel string (可选)
    • 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 (可选) - 在单个菜单中唯一。如果定义，则可以使用位置属性引用此项。
    • 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 上是自定义消息框，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 接收到点击事件时触发。调用时参数为 menuItem.click(event, focusedWindow, focusedWebContents)。

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

一个 string，表示项的类型。可以是 normal, separator, submenu, checkbox 或 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

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