Ant Design Blazor Menu 导航菜单组件完全指南:从基本用法到源码实现
Ant Design Blazor Menu 导航菜单组件完全指南:从基本用法到源码实现
导读
本文围绕 ant-design-blazor 组件库中的 Menu 导航菜单组件文档 展开,系统讲解该组件在 Blazor 应用中实现顶部导航、侧边导航、多级内嵌菜单的完整用法,覆盖 Menu、MenuItem、SubMenu、MenuItemGroup、MenuDivider 五大子组件的全部公开参数,并深入源码(components/menu/ 目录)解析选中态管理、展开/收起控制、路由高亮、图标渲染与手风琴模式等底层实现原理。读完本文,你将能够独立搭建一套支持横向/纵向/内嵌三种模式、可折叠、可路由联动、可动态切换主题的完整导航菜单。
组件定位与适用场景
导航菜单是一个网站的灵魂。用户在站内各页面间的跳转依赖清晰的导航结构,而 Ant Design 提供了两种经典布局思路(见通用布局 Layout 文档):
- 顶部导航(Top Navigation):适合栏目和功能相对扁平、希望一眼呈现全局入口的场景,对应
MenuMode.Horizontal; - 侧边导航(Side Navigation):适合信息架构层级较深、需要收纳和排列多级结构的场景,对应
MenuMode.Vertical与MenuMode.Inline。
在 ant-design-blazor 中,Menu 组件通过 Mode 参数在三种模式间切换,核心骨架代码如下(与文档 API 示例一致,源码类声明见 Menu.razor.cs):
<Menu>
<MenuItem>菜单项</MenuItem>
<SubMenu Title="子菜单">
<MenuItem>子菜单项</MenuItem>
</SubMenu>
</Menu>
Menu 的渲染根节点是一个 <ul role="menu"> 列表,并通过 CascadingValue 把自身实例向下传递给所有子组件(见 Menu.razor)。所有 MenuItem、SubMenu、MenuItemGroup 都通过级联参数 RootMenu 拿到根菜单引用,从而统一协调选中与展开状态。
五种构成组件与最小示例
Menu 组件体系由五个子组件组成,它们之间的层级关系为:Menu → SubMenu / MenuItemGroup / MenuItem / MenuDivider,其中 SubMenu 内可继续嵌套 MenuItem 或更深的 SubMenu。
以官方演示 Inline.razor 为参考,一个含分组、两级子菜单的完整内嵌菜单写法如下:
<Menu Style="width: 256px;"
DefaultSelectedKeys=@(new[] { "1" })
DefaultOpenKeys=@(new[] { "sub1" })
Mode=@MenuMode.Inline>
<SubMenu Key="sub1" TitleTemplate=@sub1Title>
<MenuItemGroup Key="g1" Title="Item 1">
<MenuItem Key="1">Option 1</MenuItem>
<MenuItem Key="2">Option 2</MenuItem>
</MenuItemGroup>
<MenuItemGroup Key="g2" Title="Item 2">
<MenuItem Key="3">Option 3</MenuItem>
<MenuItem Key="4">Option 4</MenuItem>
</MenuItemGroup>
</SubMenu>
<SubMenu Key="sub2" TitleTemplate=@sub2Title>
<MenuItem Key="5">Option 5</MenuItem>
<MenuItem Key="6">Option 6</MenuItem>
<SubMenu Key="sub3" Title="Submenu">
<MenuItem Key="7">Option 7</MenuItem>
<MenuItem Key="8">Option 8</MenuItem>
</SubMenu>
</SubMenu>
</Menu>
各子组件的职责如下表:
| 组件 | 渲染语义 | 核心职责 |
|---|---|---|
Menu |
<ul class="ant-menu ant-menu-root"> |
根容器,负责模式、主题、选中/展开状态、缩进的全局管理 |
MenuItem |
<li class="ant-menu-item"> |
叶子菜单项,可点击、可选中、可关联路由 |
SubMenu |
<li class="ant-menu-submenu"> |
可展开/收起的多级容器,内含子菜单或菜单项 |
MenuItemGroup |
<li class="ant-menu-item-group"> |
纯视觉分组容器,带分组标题,无选中语义 |
MenuDivider |
<li class="ant-menu-item-divider"> |
分隔线,仅用于垂直弹出菜单或 Dropdown 菜单 |
Menu 根组件 API 详解
下表完整继承自官方 API 文档,并补充了源码中的默认值与实现说明:
| 参数 | 说明 | 类型 | 默认值 | 实现状态 |
|---|---|---|---|---|
Accordion |
SubMenu 手风琴模式,开启后同一时间仅允许一个子菜单展开 | boolean | false |
已实现 |
DefaultOpenKeys |
初始展开的 SubMenu 菜单项 key 数组 | string[] | 空数组 | 已实现 |
DefaultSelectedKeys |
初始选中的菜单项 key 数组 | string[] | 空数组 | 已实现 |
ForceSubMenuRender |
在子菜单展示之前就渲染进 DOM | boolean | false |
未实现 |
InlineCollapsed |
inline 模式下菜单是否收起(折叠为图标条) | boolean | false |
已实现 |
InlineIndent |
inline 模式菜单项每级缩进宽度(像素) | number | 24 |
未实现(源码已声明,见下) |
Mode |
菜单类型:MenuMode.Vertical / MenuMode.Horizontal / MenuMode.Inline |
MenuMode | MenuMode.Vertical |
已实现 |
Multiple |
是否允许多选 | boolean | false |
源码已实现多选逻辑 |
OpenKeys |
当前展开的 SubMenu 菜单项 key 数组(受控) | string[] | 空数组 | 已实现 |
OnDeselect |
取消选中时调用,仅 Multiple 模式生效 | EventCallback | - | 部分实现 |
OnOpenChange |
SubMenu 展开/关闭的回调,参数为当前展开 key 数组 | EventCallback<string[]> | noop | 已实现 |
OnSelect |
被选中时调用 | EventCallback | - | 未实现(可用 OnMenuItemClicked) |
OverflowedIndicator |
菜单折叠时的自定义图标 | RenderFragment | - | 未实现 |
Selectable |
是否允许选中;为 false 时点击后不进入选中态 |
boolean | true |
已实现 |
SelectedKeys |
当前选中的菜单项 key 数组(受控) | string[] | 空数组 | 已实现 |
Style |
根节点内联样式(如宽度 width: 256px) |
string | - | 已实现 |
SubMenuCloseDelay |
鼠标离开子菜单后的关闭延时(秒) | number | 0.1 |
未实现 |
SubMenuOpenDelay |
鼠标进入子菜单后的展开延时(秒) | number | 0 |
未实现 |
Theme |
颜色主题:MenuTheme.Light / MenuTheme.Dark |
MenuTheme | MenuTheme.Light |
已实现 |
TriggerSubMenuAction |
SubMenu 展开/关闭的触发行为:hover / click |
Trigger | Trigger.Hover |
已实现 |
说明:文档中标注“(Not implemented)”的参数(如
ForceSubMenuRender、InlineIndent、SubMenuOpenDelay、SubMenuCloseDelay、OverflowedIndicator、OnSelect、OnDeselect)在 Blazor 版本中暂未落地或仅有部分逻辑,使用前应以实际行为为准;下文会详细说明其源码现状。
模式与主题的枚举定义
MenuMode 枚举定义在 MenuMode.cs,包含 Vertical、Horizontal、Inline 三种取值;MenuTheme 定义在 MenuTheme.cs,包含 Light 与 Dark。两者均在 AntDesign 命名空间下,可直接以 MenuMode.Inline、MenuTheme.Dark 的形式在 razor 中使用。
模式切换的内部机制
Menu.Mode 的 setter 在值变化时调用 UpdateMode()(见 Menu.razor.cs)。UpdateMode() 的核心逻辑(Menu.razor.cs)是:
- 当
InlineCollapsed为true时,内部模式强制切换为Vertical(内嵌菜单折叠后以弹出层展示子菜单),并关闭所有已展开的SubMenu; - 否则内部模式始终等于外部传入的
Mode。
这个“内部模式(InternalMode)”是模板渲染的关键依据:SubMenu.razor 中根据 InternalMode 决定走内联展开结构还是弹出层(Overlay)结构(见 SubMenu.razor)。
另外,OnInitialized 中有一段防御性校验(Menu.razor.cs):当 Mode 不是 Inline 却设置了 InlineCollapsed 时会抛出 ArgumentException,提醒开发者该参数只对 inline 模式生效。
选中状态与选择回调
Selectable、SelectedKeys、DefaultSelectedKeys 共同构成选中体系。其工作链路为:
- 初始化时,
MenuItem.OnInitialized检查自己的Key是否在DefaultSelectedKeys中,命中则调用Select(false, true)(见 MenuItem.razor.cs); - 点击时,
MenuItem.HandleOnClick先判断Disabled,再依据RootMenu.Selectable决定是否走SelectItem选中流程,随后触发用户绑定的OnClick与RootMenu.OnMenuItemClicked(见 MenuItem.razor.cs); Menu.SelectItem负责全菜单的选中互斥:非Multiple模式下会先取消其余已选中的MenuItem,再选中当前项,并触发SelectedKeysChanged回调(见 Menu.razor.cs);SelectedKeys作为受控属性,在SetParametersAsync中变化时会同步刷新所有MenuItem的选中态(见 Menu.razor.cs)。
源码中虽然已声明 Multiple 参数并在 SelectItem 中实现了多选分支(Menu.razor.cs),但官方文档将其标注为“Not implemented”,实际以多选场景需要自行验证为准。OnDeselect、OnSelect 在 Blazor 版中未提供对应委托,事件回调应改用 OnMenuItemClicked(EventCallback<MenuItem>)与 OnSubmenuClicked(EventCallback<SubMenu>),两者在 Menu.razor.cs 中声明。
展开状态与手风琴模式
OpenKeys、DefaultOpenKeys、OnOpenChange 构成展开控制体系:
- 初始化时
OpenKeys会回退到DefaultOpenKeys(Menu.razor.cs); - 点击
SubMenu标题时,Menu.SelectSubmenu会先执行手风琴逻辑——当Accordion为true时关闭除当前项及其父级之外的所有子菜单,再根据当前开合状态执行Open()/Close(),最后汇总所有已展开 key 触发OnOpenChange与OpenKeysChanged(Menu.razor.cs); OpenKeys受控变化时,HandleOpenKeySet会遍历全部SubMenu,按 key 是否在数组内统一展开或关闭(Menu.razor.cs)。
手风琴模式的受控写法参考官方演示 SiderCurrent2.razor:
<Menu Mode="MenuMode.Inline"
Accordion
SelectedKeys="@(new[] { "1" })"
OpenKeys="@(new[] { "sub1" })"
Style="width:256px ;">
<!-- SubMenu 定义省略 -->
</Menu>
SubMenu.Open() 内部还做了两件事:Disabled 时直接返回(不可展开),展开成功后递归 Parent?.Open() 确保父级链同步展开(SubMenu.razor.cs);Close() 则在 Animation 开启时触发折叠动画(HandleCollapse),动画通过 ant-motion-collapse-enter/leave 系列 CSS 类配合高度插值实现(SubMenu.razor.cs)。
主题与样式类映射
Theme 通过 SetClass() 映射为 ant-menu-dark / ant-menu-light 前缀类(Menu.razor.cs),Selectable=false 时追加 ant-menu-unselectable。官方演示 Theme.razor 展示了用 Switch 在 Light/Dark 间动态切换主题,并把当前选中项 key 维护在 SelectedKeys 中实现“选中态跟随点击”的效果:
<Menu Theme=theme
Style=" width: 256px "
DefaultOpenKeys=@(new[]{"sub1"})
SelectedKeys=@(new[]{current})
Mode="MenuMode.Inline">
<!-- 菜单项省略 -->
</Menu>
@code {
MenuTheme theme = MenuTheme.Dark;
string current = "1";
void changeTheme(bool value) => this.theme = value ? MenuTheme.Dark : MenuTheme.Light;
void handleClick(MenuItem e) => current = e.Key;
}
主题样式由 style/index.less 及组件整体 less 体系(见 components.less)提供,实际视觉效果与 antd 一致。
MenuItem 参数详解与源码对照
下表完整继承官方文档的 MenuItem API:
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
ChildContent |
菜单项显示内容(当 Title 未设置时渲染) |
RenderFragment | - |
Disabled |
是否禁用该项,禁用后点击无响应 | boolean | false |
Key |
菜单项唯一标识,未指定时自动生成 | string | 自动生成 ID |
OnClick |
点击菜单项时触发 | EventCallback |
- |
RouterLink |
关联的页面路由地址(生成 <a> 链接) |
string | - |
RouterMatch |
控制 NavLink 的 URL 匹配行为 | NavLinkMatch | NavLinkMatch.All |
Style |
附加的内联 CSS 样式 | string | - |
Target |
设置 <a> 标签的 target 属性(配合 RouterLink 使用) |
MenuTarget? | - |
Title |
菜单项标题文本(优先于 ChildContent) |
string | - |
Icon |
菜单项图标(Ant Design 图标类型字符串) | string | - |
IconTemplate |
自定义图标模板,与 Icon 同时设置时优先使用 IconTemplate |
RenderFragment | - |
关键实现细节(MenuItem.razor.cs):
- Key 自动生成:
Key的 getter 返回_key ?? Id,即未显式指定时自动回退到组件自动生成的Id(MenuItem.razor.cs); - 缩进计算:inline 模式下
Padding = (ParentMenu?.Level ?? 0) + 1) * RootMenu.InlineIndent,并通过内联padding-left实现(MenuItem.razor.cs)。这与文档中InlineIndent默认值 24 对应——虽然文档标注该参数“未实现”,但从源码看InlineIndent属性已被读取使用(Menu.razor.cs),缩进实际生效; - 折叠 Tooltip:当菜单折叠为图标条且该项为根菜单项时,自动包裹
Tooltip在右侧悬浮显示完整菜单名(MenuItem.razor),由ShowCollapsedTooltip(默认true)控制(Menu.razor.cs); - 图标渲染优先级:
IconTemplate→Icon→ 无图标(MenuItem.razor); - 选中级联:
Select()时若父级为SubMenu会递归让父级也进入选中态,从而让子菜单高亮(MenuItem.razor.cs)。
图标使用示例
Icon 参数接受 IconType.Outline.* 等内置图标类型字符串,官方演示 InlineCollapsed.razor 中的用法如下:
<MenuItem Key="1" Icon="@IconType.Outline.PieChart">Option 1</MenuItem>
自定义图标时优先使用 IconTemplate:
<MenuItem Key="1">
<IconTemplate>
<IconFont Type="icon-c-sharp-l" />
</IconTemplate>
<ChildContent>
<span>Home</span>
</ChildContent>
</MenuItem>
SubMenu 参数详解
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
ChildContent |
子菜单或子菜单项内容 | RenderFragment | - |
Disabled |
是否禁用该子菜单 | boolean | false |
IsOpen |
子菜单的展开状态(单向初始化用) | bool | false |
Key |
子菜单唯一标识,未指定时自动生成 | string | 自动生成 ID |
OnTitleClick |
点击子菜单标题时触发 | EventCallback |
- |
PopupClassName |
弹出层(Overlay)的自定义类名 | string | - |
Title |
子菜单标题文本 | string | - |
TitleTemplate |
子菜单标题模板(可含图标),优先于 Title |
RenderFragment | - |
两种渲染分支的源码依据(SubMenu.razor):
- Inline 模式:直接内联渲染
<li>标题 +<ul>子列表,展开/收起由IsOpen与ant-menu-hidden类控制(SubMenu.razor); - Vertical / Horizontal 模式:通过
SubMenuTrigger+Overlay弹出层实现,标题与弹出内容分离,弹出层最小宽度会按标题 DOM 宽度对齐(SubMenu.razor、SubMenu.razor.cs)。弹出层默认位置:水平模式根级子菜单为BottomLeft,其余为RightTop(SubMenu.razor)。
IsOpen 参数仅在 OnInitialized 时作为初始展开依据使用(SubMenu.razor.cs),运行时展开状态统一由根菜单的 OpenKeys / DefaultOpenKeys 驱动。
MenuItemGroup 与 MenuDivider
MenuItemGroup
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
ChildContent |
分组内的子菜单项 | RenderFragment | - |
Style |
附加内联样式 | string | - |
Title |
分组标题文本 | string | - |
TitleTemplate |
分组标题模板,优先于 Title |
RenderFragment | - |
MenuItemGroup 渲染为 <li class="ant-menu-item-group">,内部包含标题容器 ant-menu-item-group-title 与列表容器 ant-menu-item-group-list(MenuItemGroup.razor),纯视觉分组,不参与选中与展开状态管理。
MenuDivider
MenuDivider 渲染为 <li class="ant-menu-item-divider"> 空元素(MenuDivider.razor),官方文档说明其“仅用于垂直弹出菜单或 Dropdown 菜单”。在横向菜单演示 Horizontal.razor 中,它作为分组之间的分隔线使用:
<MenuItemGroup Title="Item 1">
<MenuItem Key="setting:1">Option 1</MenuItem>
<MenuItem Key="setting:2">Option 2</MenuItem>
</MenuItemGroup>
<MenuDivider />
<MenuItemGroup Title="Item 2">
<MenuItem Key="setting:3">Option 3</MenuItem>
</MenuItemGroup>
实战场景一:三种模式与动态切换
内嵌模式(Inline)
内嵌模式是最常用的侧边导航形态,子菜单以垂直折叠面板展开,天然支持多级嵌套与缩进层级。参考 Inline.razor 的完整写法见上文最小示例。
水平模式(Horizontal)
水平模式将一级菜单平铺在顶部,子菜单以弹出层展示,参考 Horizontal.razor:
<Menu Mode=MenuMode.Horizontal>
<MenuItem Key="mail">
<Icon Type="@IconType.Outline.Mail" />
Navigation One
</MenuItem>
<MenuItem Key="app" Disabled>
<Icon Type="@IconType.Outline.Appstore" />
Navigation Two
</MenuItem>
<SubMenu TitleTemplate=@sub1Title>
<!-- 分组与多级子菜单省略 -->
</SubMenu>
<MenuItem Key="alipay">
<MenuLink Href="https://ant.design" Target="@MenuTarget.Blank" rel="noopener noreferrer">
Navigation Four - Link
</MenuLink>
</MenuItem>
</Menu>
该示例同时演示了三个要点:Disabled 禁用项、用 MenuLink 直接输出外部链接(支持 Target="@MenuTarget.Blank" 新窗口打开)、以及 SubMenu 内继续嵌套 SubMenu 形成无限层级。
MenuTarget 枚举定义在 MenuTarget.cs,取值 Self、Blank、Parent、Top,在 MenuLink.cs 中映射为 _self、_blank、_parent、_top。
垂直模式(Vertical)
垂直模式参考 Vertical.razor:一级菜单纵向排列,子菜单以右侧弹出层展示,适合侧边栏并支持无限嵌套层级。
运行时动态切换模式
SwitchMode.razor 展示了用 Switch 在 MenuMode.Inline 与 MenuMode.Vertical 间动态切换,并同步切换 Light/Dark 主题:
<Menu Style=" width: 256px ;"
DefaultSelectedKeys=@(new[]{"1"})
DefaultOpenKeys=@(new[]{"sub1"})
Mode=this.mode
Theme=this.theme>
<!-- 菜单项省略 -->
</Menu>
@code {
MenuMode mode = MenuMode.Inline;
MenuTheme theme = MenuTheme.Light;
void changeMode(bool value) => this.mode = value ? MenuMode.Vertical : MenuMode.Inline;
void changeTheme(bool value) => this.theme = value ? MenuTheme.Dark : MenuTheme.Light;
}
因为 Mode 的 setter 会触发 UpdateMode() 并级联刷新内部模式与所有子菜单,所以运行时切换模式无需额外逻辑,组件内部会自动重建渲染结构。
实战场景二:内嵌菜单折叠(InlineCollapsed)
当菜单在 inline 模式且位于侧边栏中时,InlineCollapsed 可把菜单收起为仅图标的窄条,悬浮时弹出完整子菜单并自动显示 Tooltip。官方演示 InlineCollapsed.razor 的核心代码如下:
<Button Type="ButtonType.Primary" OnClick="ToggleCollapsed" Style="margin-bottom: 16px">
@if (collapsed)
{
<Icon Type="@IconType.Outline.MenuUnfold" />
}
else
{
<Icon Type="@IconType.Outline.MenuFold" />
}
</Button>
<Menu DefaultSelectedKeys=@(new[] { "1" })
DefaultOpenKeys=@(new[] { "sub1" })
Mode=MenuMode.Inline
Theme=MenuTheme.Dark
InlineCollapsed=collapsed>
<!-- 菜单项省略 -->
</Menu>
@code {
bool collapsed = false;
void ToggleCollapsed() => collapsed = !collapsed;
}
两个值得注意的联动点:
- 与 Sider 的级联:
Menu声明了级联参数Parent(类型为Sider),InlineCollapsed的 getter 优先读取Parent?.Collapsed ?? _inlineCollapsed(Menu.razor.cs)。也就是说,当Menu放在Layout的Sider中时,侧边栏收起会自动联动菜单折叠,无需手动传参——这是 ant-design-blazor 布局与菜单深度集成的一个体现,完整用法可参考 Layout 组件文档; - 折叠中的内部模式切换:折叠时
UpdateMode()强制InternalMode = Vertical,子菜单转为弹出层渲染;菜单项名称通过Tooltip在右侧悬浮显示(ShowCollapsedTooltip控制,默认开启)。
实战场景三:与路由联动(RouterLink)
MenuItem 的 RouterLink + RouterMatch 让菜单项与 Blazor 路由直接绑定,当前 URL 命中时会自动高亮选中对应菜单项。官方演示 Router.razor:
<Menu Mode="MenuMode.Horizontal">
<MenuItem RouterLink="/en-US/components/menu" RouterMatch="NavLinkMatch.All">English Menu Document</MenuItem>
<MenuItem RouterLink="/zh-CN/components/menu" RouterMatch="NavLinkMatch.All">Chinese Menu Document</MenuItem>
</Menu>
底层实现由 MenuLink.cs 完成:
- 初始化时注册
NavigationManger.LocationChanged事件,每次路由变化都会重新计算匹配(MenuLink.cs); - 匹配算法由 MenuHelper.cs 的
ShouldMatch提供:NavLinkMatch.All要求精确匹配(或忽略尾部斜杠等价),NavLinkMatch.Prefix则要求严格前缀分隔匹配(/abc匹配/abc/def但不匹配/abcdef); - 匹配成功后调用
Menu.SelectItem与Menu.SelectSubmenu自动高亮菜单项与父级子菜单;取消匹配时自动Deselect(MenuLink.cs)。注意:该自动选中仅在MenuItem.FirstRun(首次)时执行,避免覆盖用户手动的SelectedKeys受控状态。
MenuService(MenuService.cs)还利用 RouterLink 匹配结果提供 GetMenuTitle(url) 与 GetBreadcrumbOptions() 两个服务方法,前者按 URL 反查菜单标题,后者沿 ParentMenu 链生成面包屑选项,供 Breadcrumb 组件集成使用。
实战场景四:受控展开与手风琴(OnOpenChange)
当需要精细控制展开行为(例如只允许同时展开一个一级子菜单)时,应使用受控的 OpenKeys + OnOpenChange。官方演示 SiderCurrent.razor 给出了完整实现:
<Menu Mode="MenuMode.Inline"
OpenKeys=this.openKeys
OnOpenChange=this.onOpenChange
Style="width:256px ;">
<!-- 三个一级 SubMenu:sub1 / sub2 / sub4 -->
</Menu>
@code {
string[] rootSubmenuKeys = {"sub1", "sub2", "sub4"};
string[] openKeys = {"sub1"};
void onOpenChange(string[] openKeys)
{
var latestOpenKey = openKeys.FirstOrDefault(key => !this.openKeys.Contains(key));
if (!rootSubmenuKeys.Contains(latestOpenKey))
{
this.openKeys = openKeys;
}
else
{
this.openKeys = !string.IsNullOrEmpty(latestOpenKey)
? new[] {latestOpenKey}
: Array.Empty<string>();
}
}
}
该模式的语义是:当最新展开的是一个一级子菜单时,只保留它(其余自动收起),从而实现“根级手风琴”;当展开的是嵌套子菜单(不在 rootSubmenuKeys 中)时则原样接受全部展开状态。
测试与质量保障
组件行为有自动化测试覆盖,可在 tests/AntDesign.Tests/Menu/ 目录查看:
- Menu.Inline.Tests.razor:覆盖 inline 模式基础渲染、展开/收起状态、
DefaultOpenKeys、DefaultSelectedKeys、选中高亮等场景。例如Basic_inline_menu_renders_correctly断言根节点输出ant-menu ant-menu-root ant-menu-light ant-menu-inline类、子菜单标题带padding-left: 24px缩进、菜单项带ant-menu-item类等(Menu.Inline.Tests.razor); - Menu.Horizontal.Tests.razor:覆盖水平模式根节点输出
ant-menu-horizontal类、多级嵌套菜单渲染与垂直/内嵌模式的对比渲染。
测试基于 bUnit 渲染断言,通过 JSInterop 模拟 DOM 测量与 Overlay 定位(见 Menu.Horizontal.Tests.razor),可作为阅读理解组件渲染输出结构的参考样例。
使用建议与注意事项
综合文档标注与源码现状,给出以下实践建议:
- 事件回调选择:官方 API 中的
OnSelect/OnDeselect在 Blazor 版标注未实现,请使用源码中实际提供的OnMenuItemClicked(EventCallback<MenuItem>)与OnSubmenuClicked(EventCallback<SubMenu>),以及OnOpenChange、SelectedKeysChanged等回调(Menu.razor.cs); - 受控 vs 非受控:需要“选中态跟随页面路由”或“展开态受业务控制”时,优先使用受控的
SelectedKeys/OpenKeys配合对应 Changed 回调;仅需初始状态时使用DefaultSelectedKeys/DefaultOpenKeys; - 折叠联动:将
Menu置于Sider内时无需手动绑定InlineCollapsed,Sider 的收起状态会自动级联(Menu.razor.cs);若独立使用折叠功能,则需手动传入InlineCollapsed且保证Mode为Inline; - 多级嵌套:
SubMenu可无限嵌套,但层级越深越考验信息架构设计;MenuItemGroup适合在子菜单内做视觉分区; - 动态切换:
Mode/Theme支持运行时切换,组件会自动重建渲染结构,无需手动刷新页面。
总结
ant-design-blazor 的 Menu 组件完整复刻了 Ant Design 导航菜单的三种形态(Vertical / Horizontal / Inline)、Light/Dark 双主题、手风琴模式、折叠态与路由高亮联动,并通过 CascadingValue 实现根菜单对全部子组件状态的统一协调。从源码看,其选中态由 MenuItem.Select/Deselect 级联驱动,展开态由 OpenKeys 体系驱动,路由联动由 MenuLink + MenuHelper.ShouldMatch 驱动,三者相互独立又紧密配合。对于官方文档中标注“Not implemented”的参数(ForceSubMenuRender、OverflowedIndicator、OnSelect、OnDeselect、SubMenuOpenDelay、SubMenuCloseDelay 等),建议以源码实际行为为准,优先使用本文介绍的已实现等价能力。相关组件的完整实现与示例均可继续在仓库的 components/menu/ 目录与 官方演示目录 中深入研读。