Ant Design Blazor Menu 导航菜单组件完全指南:从基本用法到源码实现

原创2026-10-11 09:22:281,649 阅读
文章标签:前端UI组件设计系统WebAssembly

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 共同构成选中体系。其工作链路为:

  1. 初始化时,MenuItem.OnInitialized 检查自己的 Key 是否在 DefaultSelectedKeys 中,命中则调用 Select(false, true)(见 MenuItem.razor.cs);
  2. 点击时,MenuItem.HandleOnClick 先判断 Disabled,再依据 RootMenu.Selectable 决定是否走 SelectItem 选中流程,随后触发用户绑定的 OnClick 与 RootMenu.OnMenuItemClicked(见 MenuItem.razor.cs);
  3. Menu.SelectItem 负责全菜单的选中互斥:非 Multiple 模式下会先取消其余已选中的 MenuItem,再选中当前项,并触发 SelectedKeysChanged 回调(见 Menu.razor.cs);
  4. 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;
}

两个值得注意的联动点:

  1. 与 Sider 的级联:Menu 声明了级联参数 Parent(类型为 Sider),InlineCollapsed 的 getter 优先读取 Parent?.Collapsed ?? _inlineCollapsed(Menu.razor.cs)。也就是说,当 Menu 放在 Layout 的 Sider 中时,侧边栏收起会自动联动菜单折叠,无需手动传参——这是 ant-design-blazor 布局与菜单深度集成的一个体现,完整用法可参考 Layout 组件文档;
  2. 折叠中的内部模式切换:折叠时 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),可作为阅读理解组件渲染输出结构的参考样例。

使用建议与注意事项

综合文档标注与源码现状,给出以下实践建议:

  1. 事件回调选择:官方 API 中的 OnSelect / OnDeselect 在 Blazor 版标注未实现,请使用源码中实际提供的 OnMenuItemClicked(EventCallback<MenuItem>)与 OnSubmenuClicked(EventCallback<SubMenu>),以及 OnOpenChange、SelectedKeysChanged 等回调(Menu.razor.cs);
  2. 受控 vs 非受控:需要“选中态跟随页面路由”或“展开态受业务控制”时,优先使用受控的 SelectedKeys / OpenKeys 配合对应 Changed 回调;仅需初始状态时使用 DefaultSelectedKeys / DefaultOpenKeys;
  3. 折叠联动:将 Menu 置于 Sider 内时无需手动绑定 InlineCollapsed,Sider 的收起状态会自动级联(Menu.razor.cs);若独立使用折叠功能,则需手动传入 InlineCollapsed 且保证 Mode 为 Inline;
  4. 多级嵌套:SubMenu 可无限嵌套,但层级越深越考验信息架构设计;MenuItemGroup 适合在子菜单内做视觉分区;
  5. 动态切换: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/ 目录与 官方演示目录 中深入研读。

登录后查看全文
ant-design-blazor