SxNavMenu (导航菜单)

用于应用侧边栏的树形导航菜单组件，对齐 Microsoft Fluent UI Blazor NavMenuTree 的结构与行为。

使用场景

  • 应用侧边栏导航
  • 多层级菜单结构
  • 支持折叠与选中态
  • 顶部过滤框（可选）

约束说明

  • SxNavMenu 的 ChildContent 建议只包含 SxNavMenuGroup / SxNavMenuLink。
  • IconName 使用当前项目字体图标名称（FontAwesome）。
  • Collapsed=true 时仅显示图标，不展示文本与分组展开按钮。

行为说明

  • SxNavMenu 提供容器、折叠与动作事件。
  • SxNavMenuGroup 支持折叠分组与嵌套。
  • SxNavMenuLink 提供链接导航与激活态。
  • ReNavigate=false 时，点击已激活项不会再次触发动作。
  • 键盘：分组支持方向键展开/收起（左/右）与 Enter/Space 激活；完整 roving tabindex 尚未实现。
  • ShowIndentLine=true 时显示层级连线（浅色实线）。
  • 一级节点悬停/选中为通栏高亮；子节点悬停为圆角矩形高亮。

折叠模式说明

  • 折叠模式下，菜单变为窄条，仅显示图标。
  • 折叠按钮默认为汉堡图标（三横线），位置可通过 ExpanderPosition 配置为顶部、底部或隐藏。
  • 有子节点的菜单项在折叠模式下，图标右下角会显示小箭头指示器，便于区分。
  • 折叠模式下悬停有子节点的菜单项，子项会以弹出菜单形式显示在侧面。
  • 即使 ExpanderPosition=None（隐藏按钮），仍可通过 ExpandAsync() / CollapseAsync() / ToggleAsync() 方法编程控制。

过滤模式说明

  • ShowFilter=true 时在顶部显示过滤框，用于筛选当前树节点。
  • 输入关键字后，仅显示匹配项；父级节点在匹配子节点时仍会显示。
  • 过滤时分组自动展开，避免匹配项被折叠遮挡。
  • 折叠模式下过滤入口以弹出输入框形式展示，过滤结果仍生效。

视觉规范

  • 折叠模式下图标使用 SxButton（与侧边栏折叠按钮一致尺寸与样式）。
  • 弹出菜单与窄条边缘保持最小间距，不压边线。
  • 弹出菜单标题栏左右内边距使用标准 spacing token。

API

Parameters (SxNavMenu)

状态 参数名 标签 类型 默认值 描述
☑ ChildContent RenderFragment? null 菜单内容。
☑ Collapsible bool false 是否允许折叠。
☑ Collapsed bool false 是否强制折叠。
☑ Expanded bool true 是否展开。
☑ ExpandedChanged EventCallback<bool> - 展开状态变化回调。
☑ InitiallyExpanded bool false 初始展开状态。
☑ ReNavigate bool false 是否允许重复导航。
☑ Width int? null 展开时宽度（像素）。
☑ IndentWidth string? null 子项缩进宽度（默认与图标槽宽度对齐，支持任意 CSS 长度值）。
☑ ShowIndentLine bool false 是否显示层级连线。
☑ ExpanderContent RenderFragment? null 折叠按钮自定义内容。
☑ ExpanderPosition NavMenuExpanderPosition Top 折叠按钮位置（Top/Bottom/None）。
☑ CollapsedWidth string? null 折叠时宽度（支持任意 CSS 长度值，如 48px、3rem）；默认自动计算。
☑ ShowFilter bool true 是否显示顶部过滤框。
☑ FilterPlaceholder string? null 过滤框占位文本（en-US）。
☑ FilterPlaceholderZh string? null 过滤框占位文本（zh-CN）。
☑ FilterAriaLabel string? null 过滤框 aria-label（en-US）。
☑ FilterAriaLabelZh string? null 过滤框 aria-label（zh-CN）。
☑ OnAction EventCallback<SxNavMenuActionArgs> - 触发菜单动作时回调。
☑ Orientation Orientation Vertical 菜单排列方向。
☑ Disabled Inherited bool false 禁用状态。
☑ Loading Inherited bool false 加载中状态。
☑ Id Inherited string? null 组件的物理 Id。
☑ Class Inherited string? null 自定义 CSS 类名。
☑ Style Inherited string? null 自定义样式。
☑ Title Inherited string? null HTML title 属性。
☑ TabIndex Inherited int? null Tab 顺序索引。
☑ AccessKey Inherited string? null 快捷键。
☑ AdditionalAttributes Inherited IEnumerable<KeyValuePair<string, object>>? null 捕获不匹配的 HTML 属性。

Parameters (SxNavMenuGroup)

状态 参数名 标签 类型 默认值 描述
☑ Text string? null 组标题文本。
☑ Href string? null 组标题链接。
☑ IconName string? null 图标名称。
☑ IconStyle IconStyle Regular 图标风格。
☑ Match NavLinkMatch Prefix 路由匹配模式。
☑ Selected bool false 选中状态。
☑ SelectedChanged EventCallback<bool> - 选中状态变化回调。
☑ Expanded bool false 是否展开。
☑ ExpandedChanged EventCallback<bool> - 展开状态变化回调。
☑ InitiallyExpanded bool false 初始展开状态。
☑ Collapsed bool false 是否强制折叠。
☑ ShowIndentLine bool false 是否显示层级连线。
☑ Width int? null 项宽度（像素）。
☑ Value object? null 自定义值。
☑ OnAction EventCallback<SxNavMenuActionArgs> - 触发动作时回调。
☑ TabKey string? null Tab 标识（用于内部导航分组）。
☑ NavigationTarget SxNavMenuNavigationTarget Auto 导航目标（内部 / 外部 / 新标签）。
☑ ChildContent RenderFragment? null 子项内容。
☑ HeaderActions RenderFragment? null 组头右侧动作区内容。
☑ Disabled Inherited bool false 禁用状态。
☑ Loading Inherited bool false 加载中状态。
☑ Id Inherited string? null 组件的物理 Id。
☑ Class Inherited string? null 自定义 CSS 类名。
☑ Style Inherited string? null 自定义样式。
☑ Title Inherited string? null HTML title 属性。
☑ TabIndex Inherited int? null Tab 顺序索引。
☑ AccessKey Inherited string? null 快捷键。
☑ AdditionalAttributes Inherited IEnumerable<KeyValuePair<string, object>>? null 捕获不匹配的 HTML 属性。
状态 参数名 标签 类型 默认值 描述
☑ Text string? null 链接文本。
☑ Href string? null 导航链接。
☑ IconName string? null 图标名称。
☑ IconStyle IconStyle Regular 图标风格。
☑ Match NavLinkMatch Prefix 路由匹配模式。
☑ Selected bool false 选中状态。
☑ SelectedChanged EventCallback<bool> - 选中状态变化回调。
☑ Width int? null 项宽度（像素）。
☑ Value object? null 自定义值。
☑ OnAction EventCallback<SxNavMenuActionArgs> - 触发动作时回调。
☑ TabKey string? null Tab 标识（用于内部导航分组）。
☑ NavigationTarget SxNavMenuNavigationTarget Auto 导航目标（内部 / 外部 / 新标签）。
☑ ChildContent RenderFragment? null 子内容。
☑ Disabled Inherited bool false 禁用状态。
☑ Loading Inherited bool false 加载中状态。
☑ ShowIndentLine bool false 是否显示层级连线。
☑ Id Inherited string? null 组件的物理 Id。
☑ Class Inherited string? null 自定义 CSS 类名。
☑ Style Inherited string? null 自定义样式。
☑ Title Inherited string? null HTML title 属性。
☑ TabIndex Inherited int? null Tab 顺序索引。
☑ AccessKey Inherited string? null 快捷键。
☑ AdditionalAttributes Inherited IEnumerable<KeyValuePair<string, object>>? null 捕获不匹配的 HTML 属性。

Events

状态 事件名 类型 描述
☑ OnAction EventCallback<SxNavMenuActionArgs> 菜单项触发动作回调。
☑ ExpandedChanged EventCallback<bool> 展开状态变化回调。
☑ SelectedChanged EventCallback<bool> 选中状态变化回调（Group/Link）。

Methods (SxNavMenu)

方法名 返回类型 描述
ExpandAsync() Task 展开菜单（编程控制）。
CollapseAsync() Task 收起菜单（编程控制）。
ToggleAsync() Task 切换展开/收起状态（编程控制）。

SxNavMenuActionArgs

字段 类型 描述
ItemKind SxNavMenuItemKind 当前触发项类型（Link/Group）。
ItemId string? 触发项 Id。
Text string? 文本。
Href string? 链接地址。
Value object? 透传值。
Selected bool 当前选中态。
TabKey string? Tab 标识。
Target SxNavMenuNavigationTarget 导航目标。

兼容说明

  • SxNavMenuItem 作为兼容包装存在，建议新代码使用 SxNavMenuLink。

示例

<SxNavMenu Collapsible="true">
    <SxNavMenuGroup Text="应用" IconName="layer-group" InitiallyExpanded="true">
        <SxNavMenuLink Text="首页" IconName="house" Href="/" />
        <SxNavMenuLink Text="仪表盘" IconName="gauge" Href="/dashboard" />
    </SxNavMenuGroup>
    <SxNavMenuGroup Text="支持" IconName="circle-question">
        <SxNavMenuLink Text="设置" IconName="gear" Href="/settings" />
    </SxNavMenuGroup>
</SxNavMenu>

参考设计 (References)

在 Playground 中打开 →