Electron.NET 菜单 API 实战指南:使用 Electron.Menu 构建原生应用菜单与上下文菜单
Electron.NET 菜单 API 实战指南:使用 Electron.Menu 构建原生应用菜单与上下文菜单
导读
Electron.Menu 是 Electron.NET 框架中负责创建原生菜单的核心 API,它允许 .NET 开发者完全用 C# 定义应用菜单(Application Menu)、上下文菜单(Context Menu)以及带完整键盘快捷键支持的菜单项,无需编写任何 JavaScript 代码。读完本文,你将掌握应用菜单、上下文菜单、快捷键、角色菜单(Role)、动态更新与平台差异化菜单的完整实战方案,并能从源码层面理解菜单点击事件在 .NET 与 Electron 主进程之间是如何串联的。
Electron.Menu 概览
在 Electron.NET 中,Electron.Menu 以单例形式暴露在静态类 Electron 上(见 Electron.cs),是构建原生菜单的唯一入口。它支持:
- 原生平台菜单(Application Menu),如 Windows/Linux 的窗口顶部菜单栏、macOS 的系统菜单栏;
- 自定义菜单项、子菜单(Submenu)与分隔符(Separator);
- 键盘快捷键(Accelerator);
- 基于角色(Role)的菜单项,让系统自动完成撤销、复制、粘贴、缩放等标准操作;
- 针对具体浏览器窗口(BrowserWindow)的上下文菜单。
从源码结构看,Menu 类被设计为 sealed 且构造器为 internal,通过 Menu.Instance 单例访问,因此你始终应该通过 Electron.Menu 静态属性使用它,而不是自行 new Menu()(见 Menu.cs)。
Menu 类的属性与方法
属性
IReadOnlyDictionary<int, ReadOnlyCollection<MenuItem>> ContextMenuItems
获取当前所有上下文菜单项的只读字典,键为浏览器窗口 ID(BrowserWindow.Id),值为该窗口对应的 MenuItem 只读集合。在调用 SetContextMenu 后,该属性才会填充对应窗口的数据。
IReadOnlyCollection<MenuItem> MenuItems
获取当前应用菜单项的只读集合。每次调用 SetApplicationMenu 会先清空再重新填充该集合,因此它始终反映最近一次设置的应用菜单结构。动态更新菜单时(见下文示例)正是通过读取该集合定位目标菜单项的。
方法
void SetApplicationMenu(MenuItem[] menuItems)
为整个应用程序设置应用菜单。这是唯一需要调用一次就能覆盖全局菜单栏的方法:在 Windows/Linux 上表现为窗口顶部菜单,在 macOS 上表现为系统菜单栏。实现上,该方法会为每个带 Click 回调的菜单项自动生成唯一 Id、为含子菜单的菜单项补全 submenu 类型,然后通过 Socket 桥发给 Electron 主进程(见 Menu.cs 中 SetApplicationMenu 实现)。
void SetContextMenu(BrowserWindow browserWindow, MenuItem[] menuItems)
为指定的浏览器窗口设置上下文菜单(右键菜单)。同一个窗口再次调用会覆盖旧的菜单,不同窗口各自维护独立的上下文菜单。传入的 browserWindow 也可以是应用主窗口。
void ContextMenuPopup(BrowserWindow browserWindow)
在指定浏览器窗口上以编程方式弹出之前设置好的上下文菜单。一般配合 IpcMain 或渲染进程事件使用,例如收到渲染进程发来的"show-context-menu"消息后触发弹出(见 MenusController.cs 中的真实用法)。
MenuItem:菜单项实体详解
所有菜单结构都由 MenuItem 实体构建,该类与 Electron API 39.2 保持同步(见 MenuItem.cs)。核心属性如下:
| 属性 | 类型 | 说明 |
|---|---|---|
Label |
string |
菜单项显示文本 |
Sublabel |
string |
副标签(仅 macOS) |
ToolTip |
string |
悬停提示文本(仅 macOS) |
Type |
MenuType |
菜单项类型:normal、separator、submenu、checkbox、radio,以及 macOS 14+ 的 header、palette |
Role |
MenuRole |
角色菜单项;一旦指定,Click 将被忽略 |
Accelerator |
string |
键盘快捷键,如 "CmdOrCtrl+N" |
Click |
Action |
点击回调(C# 委托),通过桥接机制被触发 |
Enabled |
bool |
是否可用,默认 true;为 false 时置灰且不可点击 |
Visible |
bool |
是否可见,默认 true;为 false 时完全隐藏 |
Checked |
bool |
是否勾选,仅用于 checkbox / radio 类型 |
Icon |
string |
图标路径 |
Submenu |
MenuItem[] |
子菜单数组;指定后 Type 会自动视为 submenu |
Id |
string |
菜单内唯一 ID,由框架自动生成 |
Position |
string |
细粒度定位插入位置 |
Before / After |
string[] |
按目标 ID 插到指定菜单项前/后 |
BeforeGroupContaining / AfterGroupContaining |
string[] |
将所在分组整体移动到指定分组之前/之后 |
AcceleratorWorksWhenHidden |
bool? |
隐藏时快捷键是否仍生效(仅 macOS,默认 true) |
RegisterAccelerator |
bool? |
快捷键是否注册到系统(仅 Windows/Linux,默认 true) |
SharingItem |
SharingItem |
shareMenu 角色要共享的内容(仅 macOS) |
从源码可以看到,Click 属性带有 [JsonIgnore] 标记——它不会随菜单模板序列化到 Electron 进程,而是靠框架为带回调的菜单项生成 GUID 形式的 Id,再通过事件桥接回 C# 端调用委托。因此同一个菜单项上 Role 与 Click 不要同时设置,否则 Click 会被忽略。
MenuType 与 MenuRole 枚举
MenuType(见 MenuType.cs)覆盖 normal、separator、submenu、checkbox、radio 及 macOS 14+ 的 header/palette。
MenuRole(见 MenuRole.cs)则提供了丰富的标准角色,常见的有:
- 编辑类:
undo、redo、cut、copy、paste、pasteAndMatchStyle、selectAll、delete; - 窗口/视图类:
minimize、close、quit、reload、forceReload、toggleDevTools、togglefullscreen、resetZoom、zoomIn、zoomOut、toggleSpellChecker; - 整组默认菜单:
editMenu、windowMenu、fileMenu、viewMenu、appMenu、shareMenu; - macOS 专属:
about、hide、hideOthers、unhide、services、startSpeaking、stopSpeaking、front、zoom、window、help、recentDocuments、clearRecentDocuments、toggleTabBar、selectNextTab等。
枚举中还保留了一批小写形式的向后兼容别名(如 pasteandmatchstyle、selectall、forcereload、toggledevtools、resetzoom 等),确保旧代码无需改动即可编译运行。
创建应用菜单:完整示例
这是文档给出的标准应用菜单结构,包含 File、Edit、View、Window 四个顶级菜单。其中 Edit/View 大量使用 Role,让 Electron 自动完成标准交互:
// Create application menu
var menuItems = new[]
{
new MenuItem
{
Label = "File",
Submenu = new[]
{
new MenuItem { Label = "New", Click = () => CreateNewDocument() },
new MenuItem { Label = "Open", Click = () => OpenDocument() },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Label = "Exit", Click = () => Electron.App.Quit() }
}
},
new MenuItem
{
Label = "Edit",
Submenu = new[]
{
new MenuItem { Role = MenuRole.Undo },
new MenuItem { Role = MenuRole.Redo },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Role = MenuRole.Cut },
new MenuItem { Role = MenuRole.Copy },
new MenuItem { Role = MenuRole.Paste }
}
},
new MenuItem
{
Label = "View",
Submenu = new[]
{
new MenuItem { Role = MenuRole.Reload },
new MenuItem { Role = MenuRole.ForceReload },
new MenuItem { Role = MenuRole.ToggleDevTools },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Role = MenuRole.ResetZoom },
new MenuItem { Role = MenuRole.ZoomIn },
new MenuItem { Role = MenuRole.ZoomOut }
}
},
new MenuItem
{
Label = "Window",
Submenu = new[]
{
new MenuItem { Role = MenuRole.Minimize },
new MenuItem { Role = MenuRole.Close }
}
}
};
// Set application menu
Electron.Menu.SetApplicationMenu(menuItems);
在仓库自带的演示应用中,MenusController.cs 给出了一个更贴近真实产品的版本:菜单包含 Edit(Undo/Redo/Cut/Copy/Paste/Select All)、View(Reload、Toggle Full Screen、Open Developer Tools、App Menu Demo)、Window(Minimize/Close)和 Help(Learn More),其中"Reload"菜单项会遍历 Electron.WindowManager.BrowserWindows 关闭次要窗口并重载主窗口,"Toggle Full Screen"则通过 SetFullScreen 切换全屏——这就是把真实业务逻辑直接绑定到菜单 Click 回调的标准做法。
创建上下文菜单:完整示例
上下文菜单挂在具体窗口上,通常由渲染进程右键事件触发弹出。文档示例:
// Create context menu for specific window
var contextMenuItems = new[]
{
new MenuItem { Label = "Copy", Click = () => CopySelectedText() },
new MenuItem { Label = "Paste", Click = () => PasteText() },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Label = "Inspect Element", Click = () => InspectElement() }
};
// Set context menu for window
Electron.Menu.SetContextMenu(mainWindow, contextMenuItems);
// Show context menu programmatically
Electron.Menu.ContextMenuPopup(mainWindow);
在演示应用中,上下文菜单还演示了 checkbox 类型与 Checked 属性的用法(见 MenusController.cs 的 CreateContextMenu 方法):
var menu = new MenuItem[]
{
new MenuItem
{
Label = "Hello",
Click = async () => await Electron.Dialog.ShowMessageBoxAsync("Electron.NET rocks!")
},
new MenuItem { Type = MenuType.separator },
new MenuItem { Label = "Electron.NET", Type = MenuType.checkbox, Checked = true }
};
var mainWindow = Electron.WindowManager.BrowserWindows.FirstOrDefault();
Electron.Menu.SetContextMenu(mainWindow, menu);
Electron.IpcMain.On("show-context-menu", (args) =>
{
Electron.Menu.ContextMenuPopup(mainWindow);
});
这里的思路很清晰:菜单先设置好,渲染进程通过 IpcMain 发送 "show-context-menu" 消息,主进程再调用 ContextMenuPopup 弹出。右键时机完全由你的渲染层决定。
键盘快捷键(Accelerator)
Accelerator 字符串使用 Electron 的快捷键语法,CmdOrCtrl 会在 macOS 上自动映射为 Cmd、在其他平台映射为 Ctrl。文档示例:
// Create menu with keyboard shortcuts
var menuItems = new[]
{
new MenuItem
{
Label = "File",
Submenu = new[]
{
new MenuItem
{
Label = "New",
Accelerator = "CmdOrCtrl+N",
Click = () => CreateNewDocument()
},
new MenuItem
{
Label = "Open",
Accelerator = "CmdOrCtrl+O",
Click = () => OpenDocument()
},
new MenuItem
{
Label = "Save",
Accelerator = "CmdOrCtrl+S",
Click = () => SaveDocument()
}
}
}
};
Electron.Menu.SetApplicationMenu(menuItems);
演示应用还展示了组合键写法:"Shift+CmdOrCtrl+Z"(Redo)、"CmdOrCtrl+X"(Cut)、"CmdOrCtrl+A"(Select All)、"CmdOrCtrl+F"(Toggle Full Screen)、"CmdOrCtrl+I"(Developer Tools)、"CmdOrCtrl+M"(Minimize)、"CmdOrCtrl+W"(Close)。
需要注意的两个平台差异参数(见 MenuItem.cs):
- macOS 上
AcceleratorWorksWhenHidden控制菜单项隐藏时快捷键是否依然生效(默认true); - Windows/Linux 上
RegisterAccelerator控制快捷键是否注册进系统(默认true),设为false时仅作为菜单上的显示文本而不实际拦截按键。
此外,若某菜单项只希望快捷键生效而菜单本身不可见,可以结合 Visible = false 与上述参数来实现。
动态更新菜单项
应用运行期间可以直接读取 MenuItems 属性并修改 MenuItem 的属性(如 Enabled、Visible、Label),改动会即时反映到原生菜单上。文档示例根据是否有未保存更改来切换"Save"菜单项的可用状态:
// Update menu items dynamically
var fileMenu = Electron.Menu.MenuItems.FirstOrDefault(m => m.Label == "File");
if (fileMenu?.Submenu != null)
{
var saveItem = fileMenu.Submenu.FirstOrDefault(m => m.Label == "Save");
if (saveItem != null)
{
saveItem.Enabled = HasUnsavedChanges;
}
}
注意:由于 SetApplicationMenu 每次都会清空并重建菜单,动态更新应基于当前已设置的菜单结构进行,避免在设置菜单后又重新传入一套全新数组而丢失对原菜单项对象引用。
平台差异化菜单(macOS)
macOS 的应用菜单栏与 Windows/Linux 差别很大:第一个菜单通常是应用名菜单,且包含 About、Services、Hide、Quit 等系统角色项。文档推荐的做法是用 RuntimeInformation.IsOSPlatform 判断平台,把 macOS 专用菜单插到最前面:
// macOS specific menu items
if (RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
{
var macMenuItems = new[]
{
new MenuItem
{
Label = "MyApp",
Submenu = new[]
{
new MenuItem { Role = MenuRole.About },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Role = MenuRole.Services },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Role = MenuRole.Hide },
new MenuItem { Role = MenuRole.HideOthers },
new MenuItem { Role = MenuRole.Unhide },
new MenuItem { Type = MenuType.Separator },
new MenuItem { Role = MenuRole.Quit }
}
}
};
// Insert before File menu
var allMenus = new List<MenuItem>(macMenuItems);
allMenus.AddRange(menuItems);
Electron.Menu.SetApplicationMenu(allMenus.ToArray());
}
这段代码几乎逐项对应 Electron 官方推荐的 macOS 应用菜单模板,About、Services、Hide、HideOthers、Unhide、Quit 均只对 macOS 生效(见 MenuRole.cs 中这些枚举的注释)。如果你的应用面向多平台,建议始终保留这样一份平台分支。
底层原理:菜单事件如何从 Electron 回到 C#
从源码看,Electron.Menu 并没有直接操作原生菜单,而是走"桥接"架构:
- C# 端(Menu.cs):
SetApplicationMenu/SetContextMenu先调用 MenuItemExtensions.cs 中的AddMenuItemsId为每个带Click的菜单项递归生成 GUIDId(若用户未显式指定),并用AddSubmenuTypes把含子菜单且Type仍为normal的菜单项自动改为submenu;随后通过BridgeConnector.Socket.Emit把整个菜单模板序列化发送给 Electron 主进程。 - Electron 主进程(menu.ts):收到
"menu-setApplicationMenu"事件后用Menu.buildFromTemplate(menuItems)构建原生菜单,再递归遍历所有菜单项为每个带id的项注入click处理器,点击时通过 Socket 把菜单项id发回 C#("menuItemClicked"事件);上下文菜单同理,回调里额外带上browserWindowId。 - C# 端回调:
SetApplicationMenu中订阅"menuItemClicked",用 MenuItemExtensions.cs 的GetMenuItem按id递归找到目标MenuItem(含子菜单层级),然后调用menuItem.Click?.Invoke()。上下文菜单则从_contextMenuItems[browserWindowId]中查找并触发回调。
这意味着 Click 委托默认在 Socket 事件处理线程上执行,属于异步回调;演示应用中大量使用 async () => await ... 的写法即是为此设计的。
测试验证:集成测试如何覆盖菜单功能
仓库中的集成测试直接验证了这套桥接机制(见 MenuTests.cs):
ApplicationMenu_click_invokes_handler:设置应用菜单后,通过ExecuteJavaScriptAsync让渲染进程用ipcRenderer.send模拟点击"integration-click-application-menu"事件,断言Click委托确实被调用;ContextMenu_popup_registers_items:设置上下文菜单、调用ContextMenuPopup,再模拟点击"integration-click-context-menu"事件,断言上下文菜单项的Click回调生效。
这两条用例是"菜单点击链路"最直接的验证,也可以作为你调试菜单不响应时排查思路的参考:先确认菜单已设置(MenuItems/ContextMenuItems 有数据),再确认事件名与 Id 传递是否一致。
关联 API 与延伸阅读
- Electron.WindowManager:菜单所挂载窗口的创建与管理,
SetContextMenu/ContextMenuPopup都需要BrowserWindow实例; - Electron.App:应用生命周期事件,如示例中的
Electron.App.Quit()、Electron.App.Ready; - Electron.GlobalShortcut:全局键盘快捷键,适用于应用失去焦点时仍需响应的场景,与菜单
Accelerator形成互补。
Electron.NET 的菜单 API 与 Electron 官方 Menu API 语义一一对应,.csproj 层面的约束是:所有示例代码应运行在 HybridSupport.IsElectronActive 为 true 的 Electron 宿主环境中(演示应用的写法可参考 MenusController.cs),在纯浏览器模式下请用条件判断保护菜单相关调用,避免无宿主时抛错。