import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import DocCardList from '@theme/DocCardList';

菜单¶

Electron 的 Menu 类提供了一种标准化方式，用于在整个应用程序中创建跨平台原生菜单。

Electron 中可用的菜单¶

相同的菜单 API 用于多种用例：

应用程序菜单是应用程序的顶级菜单。每个应用程序一次只有一个应用程序菜单。
上下文菜单在用户右键单击应用程序界面的某个部分时触发。
托盘菜单是一种特殊的上下文菜单，在右键单击应用程序的 Tray 实例时触发。
在 macOS 上，Dock 菜单是一种特殊的上下文菜单，在右键单击系统 Dock 中应用程序的图标时触发。

要了解您可以创建的各种原生菜单以及如何指定键盘快捷键，请参阅本节中的各个指南：

构建菜单¶

每个 Menu 实例由一个 MenuItem 对象数组组成，可通过 menu.items 实例属性访问。通过将 item.submenu 属性设置为另一个菜单，可以嵌套菜单。

构建菜单有两种方式：直接调用 menu.append 或使用静态 Menu.buildFromTemplate 辅助函数。

辅助函数通过允许你在单个数组中传递一组 MenuItem 构造函数选项（或已实例化的 MenuItem 实例），从而减少样板代码，而无需在单独的函数调用中追加每个项目。

下面是一个最小应用程序菜单的示例：

menu.js

const submenu = new Menu()
submenu.append(new MenuItem({ label: 'Hello' }))
submenu.append(new MenuItem({ type: 'separator' }))
submenu.append(new MenuItem({ label: 'Electron', type: 'checkbox', checked: true }))
const menu = new Menu()
menu.append(new MenuItem({ label: 'Menu', submenu }))
Menu.setApplicationMenu(menu)

menu.js

const menu = Menu.buildFromTemplate([{
  label: 'Menu',
  submenu: [
    { label: 'Hello' },
    { type: 'separator' },
    { label: 'Electron', type: 'checkbox', checked: true }
  ]
}])
Menu.setApplicationMenu(menu)

[!IMPORTANT] 所有菜单项（separator 类型除外）都必须具有标签。标签可以使用 label 属性手动定义，也可以从菜单项的 role 继承。

类型¶

菜单项的类型会赋予其特定的外观和功能。某些类型会根据其他构造函数选项自动分配：

默认情况下，菜单项具有 normal 类型。
包含 submenu 属性的菜单项将被分配 submenu 类型。

其他可用类型在指定时，会为菜单项提供特殊的附加属性：

checkbox - 每当菜单项被点击时切换 checked 属性
radio - 切换 checked 属性，并关闭所有相邻 radio 项的该属性
palette - 创建一个 Palette 子菜单，该子菜单将项目水平对齐（适用于 macOS 14 及以上版本）
header - 创建一个节标题，可以使用标签表示分组（适用于 macOS 14 及以上版本）

[!TIP] 相邻的 radio 项位于同一层级的子菜单中，并且没有被分隔符分开。

[
  { type: 'radio', label: 'Adjacent 1' },
  { type: 'radio', label: 'Adjacent 2' },
  { type: 'separator' },
  { type: 'radio', label: 'Non-adjacent' } // unaffected by the others
]

角色¶

角色为 normal 类型菜单项提供预定义行为。

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

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

[!TIP] 角色字符串不区分大小写。例如，在定义菜单项时，toggleDevTools、toggledevtools 和 TOGGLEDEVTOOLS 都是等效的角色。

编辑角色¶

undo
redo
cut
copy
paste
pasteAndMatchStyle
selectAll
delete

窗口角色¶

about - 触发原生关于面板（在 Window 上为自定义消息框，Window 本身不提供该面板）。
minimize - 最小化当前窗口。
close - 关闭当前窗口。
quit - 退出应用程序。
reload - 重新加载当前窗口。
forceReload - 忽略缓存并重新加载当前窗口。
toggleDevTools - 切换当前窗口中的开发者工具。
togglefullscreen - 切换当前窗口的全屏模式。
resetZoom - 将聚焦页面的缩放级别重置为原始大小。
zoomIn - 将聚焦页面放大 10%。
zoomOut - 将聚焦页面缩小 10%。
toggleSpellChecker - 启用/禁用内置拼写检查器。

fileMenu - 子菜单是“文件”菜单（关闭 / 退出）
editMenu - 子菜单是“编辑”菜单（撤销、复制等）
viewMenu - 子菜单是“查看”菜单（重新加载、切换开发者工具等）
windowMenu - 子菜单是“窗口”菜单（最小化、缩放等）

仅限 macOS 的角色¶

macOS 提供许多平台特定的菜单角色。其中许多映射到底层 AppKit API。

应用管理角色¶

hide - 映射到 hide 操作。
hideOthers - 映射到 hideOtherApplications 操作。
unhide - 映射到 unhideAllApplications 操作。
front - 映射到 arrangeInFront 操作。
zoom - 映射到 performZoom 操作。

编辑角色¶

showSubstitutions - 映射到 orderFrontSubstitutionsPanel 操作。
toggleSmartQuotes - 映射到 toggleAutomaticQuoteSubstitution 操作。
toggleSmartDashes - 映射到 toggleAutomaticDashSubstitution 操作。
toggleTextReplacement - 映射到 toggleAutomaticTextReplacement 操作。

语音角色¶

startSpeaking - 映射到 startSpeaking 操作。
stopSpeaking - 映射到 stopSpeaking 操作。

原生标签页角色¶

toggleTabBar - 映射到 toggleTabBar 操作。
selectNextTab - 映射到 selectNextTab 操作。
selectPreviousTab - 映射到 selectPreviousTab 操作。

mergeAllWindows - 映射到 mergeAllWindows 操作。
moveTabToNewWindow - 映射到 moveTabToNewWindow 操作。

默认菜单角色¶

appMenu - 整个默认的“App”菜单（关于、服务等）。
services - 该子菜单是一个 “服务” 菜单。
window - 该子菜单是一个“窗口”菜单。
help - 该子菜单是一个“帮助”菜单。

其他菜单角色¶

recentDocuments - 该子菜单是一个“打开最近使用的文件”菜单。
clearRecentDocuments - 映射到 clearRecentDocuments 操作。
shareMenu - 该子菜单是共享菜单。还必须设置 sharingItem 属性以指示要共享的项目。

[!IMPORTANT] 在 macOS 上指定 role 时，label 和 accelerator 是仅有的会影响菜单项的选项。所有其他选项都将被忽略。

加速键¶

accelerator 属性允许你定义加速键字符串，将菜单项映射到键盘快捷键。更多细节，请参阅键盘快捷键指南。

高级配置¶

以编程方式定位菜单项¶

你可以使用 before、after、beforeGroupContaining、afterGroupContaining 和 id 属性，在使用 Menu.buildFromTemplate 构建菜单时控制菜单项的放置位置。

before - 将此项目插入到具有指定 id 的项目之前。如果引用的项目不存在，该项目将被插入到菜单末尾。这也意味着该菜单项应与被引用项放在同一个“组”中。
after - 将此项目插入到具有指定 id 的项目之后。如果引用的项目不存在，该项目将被插入到菜单末尾。这也意味着该菜单项应与被引用项放在同一个“组”中。
beforeGroupContaining - 提供一种方式，使单个上下文菜单能够声明其所在组位于具有指定 id 的项所在组之前。
afterGroupContaining - 提供一种方式，使单个上下文菜单能够声明其所在组位于具有指定 id 的项所在组之后。

默认情况下，除非使用了上述定位关键字之一，否则项目将按照模板中出现的顺序插入。

示例¶

模板：

[
  { id: '1', label: 'one' },
  { id: '2', label: 'two' },
  { id: '3', label: 'three' },
  { id: '4', label: 'four' }
]

菜单：

- one
- two
- three
- four

模板：

[
  { id: '1', label: 'one' },
  { type: 'separator' },
  { id: '3', label: 'three', beforeGroupContaining: ['1'] },
  { id: '4', label: 'four', afterGroupContaining: ['2'] },
  { type: 'separator' },
  { id: '2', label: 'two' }
]

菜单：

- three
- four
- ---
- one
- ---
- two

模板：

[
  { id: '1', label: 'one', after: ['3'] },
  { id: '2', label: 'two', before: ['1'] },
  { id: '3', label: 'three' }
]

菜单：

- ---
- three
- two
- one

图标¶

为了给菜单增加视觉辅助，你可以使用 icon 属性为单独的 MenuItem 实例分配图像。

Adding a little green circle to a menu item

const { nativeImage } = require('electron/common')
const { MenuItem } = require('electron/main')

// highlight-next-line
const green = nativeImage.createFromDataURL('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAACOSURBVHgBpZLRDYAgEEOrEzgCozCCGzkCbKArOIlugJvgoRAUNcLRpvGH19TkgFQWkqIohhK8UEaKwKcsOg/+WR1vX+AlA74u6q4FqgCOSzwsGHCwbKliAF89Cv89tWmOT4VaVMoVbOBrdQUz+FrD6XItzh4LzYB1HFJ9yrEkZ4l+wvcid9pTssh4UKbPd+4vED2Nd54iAAAAAElFTkSuQmCC')

const item = new MenuItem({
  label: 'Green Circle',
  // highlight-next-line
  icon: green
})

副标签 macOS¶

在 macOS 14.4 及以上版本中，你可以使用 sublabel 选项为菜单项添加副标签（也称为副标题）。

Adding descriptions via sublabel

const { MenuItem } = require('electron/main')

const item = new MenuItem({
  label: 'Log Message',
  // highlight-next-line
  sublabel: 'This will use the console.log utility',
  click: () => { console.log('Logging via menu...') }
})

工具提示 macOS¶

工具提示是悬停在菜单项上时显示的信息指示器。在 macOS 上，你可以使用 toolTip 选项为菜单项设置工具提示。

Adding additional information via tooltip

const { MenuItem } = require('electron/main')

const item = new MenuItem({
  label: 'Hover Over Me',
  // highlight-next-line
  toolTip: 'This is additional info that appears on hover'
})

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 el/electron