SxMenu (基础菜单)

Implemented

基础菜单容器，用于承载具体的菜单项（SxMenuItem）。对齐 Microsoft Fluent UI Blazor Menu (v4.13.2) 的 API 结构，并说明 NextUI 当前实现状态。

使用场景

自定义触发器菜单
右键或快捷操作菜单
复杂菜单组合展示

约束说明

需要通过 AnchorId 或 AnchorElement 定位。
IsOpen 控制菜单显示状态。

行为说明

UseMenuService 为真时由服务统一管理。
位置计算完成前菜单保持隐藏以避免闪烁。

API

Parameters (参数)

状态	参数名	类型	默认值	描述
Implemented	`ChildContent`	`RenderFragment?`	`null`	菜单内容。
Implemented	`IsOpen`	`bool`	`false`	菜单是否打开（支持双向绑定）。
Implemented	`Placement`	`MenuPlacement`	`Auto`	菜单弹出位置。
Implemented	`Alignment`	`MenuAlignment`	`Start`	菜单对齐方式。
Implemented	`AnchorId`	`string?`	`null`	锚点元素 ID。
Implemented	`AnchorElement`	`ElementReference?`	`null`	锚点元素引用。
Implemented	`UseMenuService`	`bool`	`true`	是否使用 MenuService。
Implemented	`OnMenuChanged`	`EventCallback<MenuChangeEventArgs>`	`null`	菜单项选择回调。
Implemented	`Disabled` (继承)	`bool`	`false`	禁用状态。
Implemented	`Loading` (继承)	`bool`	`false`	加载状态。
Implemented	`Id` (继承)	`string?`	`null`	组件的物理 Id。
Implemented	`Class` (继承)	`string?`	`null`	自定义 CSS 类名。
Implemented	`Style` (继承)	`string?`	`null`	自定义样式。
Implemented	`Title` (继承)	`string?`	`null`	HTML `title` 属性。
Implemented	`AdditionalAttributes` (继承)	`IEnumerable<KeyValuePair<string, object>>?`	`null`	捕获不匹配的 HTML 属性。

Events (事件)

状态	事件名	类型	描述
Implemented	`OnClose`	`EventCallback`	菜单关闭时触发。
Implemented	`OnOpen`	`EventCallback`	菜单弹出时触发。
Implemented	`IsOpenChanged`	`EventCallback<bool>`	打开状态改变时触发。
Implemented	`OnMenuChanged`	`EventCallback<MenuChangeEventArgs>`	菜单项选择时触发。

Methods (方法)

状态	方法名	返回类型	描述
Implemented	`Open()`	`Task`	打开菜单。
Implemented	`Close()`	`Task`	关闭菜单。
Implemented	`Toggle()`	`Task`	切换菜单的打开/关闭状态。

示例

<SxMenu @bind-IsOpen="_isOpen" AnchorId="menu-anchor">
    <SxMenuItem Text="选项 1" />
</SxMenu>

MenuService 功能

当 UseMenuService 为 true 且 MenuService 已注册时，菜单将获得以下增强功能：

统一管理：所有菜单由服务统一管理，避免冲突
自动 z-index：自动管理层级，确保正确的显示顺序
ESC 键处理：按 ESC 键自动关闭当前活动的菜单
性能优化：共享事件监听器，减少资源消耗

使用 MenuService

// 在 Program.cs 或 Startup.cs 中注册服务
services.AddNextDesignSystem(); // 自动注册 MenuService

<!-- 使用 MenuService（默认） -->
<SxMenu @bind-IsOpen="_isOpen">
    <SxMenuItem Text="选项 1" />
</SxMenu>

<!-- 不使用 MenuService -->
<SxMenu @bind-IsOpen="_isOpen" UseMenuService="false">
    <SxMenuItem Text="选项 1" />
</SxMenu>

自动定位功能

菜单支持自动定位和边界检测：

自动方向调整：当空间不足时，自动切换弹出方向（上下左右）
边界检测：确保菜单不会超出视口边界
对齐控制：支持左对齐、居中、右对齐
避免被切掉：使用 position: fixed 避免被父容器的 overflow: hidden 切掉
实现说明：定位算法会返回最终采用的 actualPlacement（用于动画方向与调试），并会持续清理历史遗留的重复返回等死代码，确保逻辑单一且可维护。

弹出逻辑与对齐规范

为了确保最佳的用户体验，不同弹出位置（Placement）下的默认对齐行为如下：

弹出位置 (Placement)	默认对齐 (Alignment: Start)	居中对齐 (Alignment: Center)	末尾对齐 (Alignment: End)
`Bottom` (下方)	菜单左上角对齐锚点左下角	菜单水平中心对齐锚点水平中心	菜单右上角对齐锚点右下角
`Top` (上方)	菜单左下角对齐锚点左上角	菜单水平中心对齐锚点水平中心	菜单右下角对齐锚点右上角
`Left` (左侧)	菜单右上角对齐锚点左上角	菜单垂直中心对齐锚点垂直中心	菜单右下角对齐锚点左下角
`Right` (右侧)	菜单左上角对齐锚点右上角	菜单垂直中心对齐锚点垂直中心	菜单左下角对齐锚点右下角

防闪烁机制：菜单在初次弹出时，会先进行隐形位置计算。在计算完成前，菜单处于 visibility: hidden 状态，计算完成后一次性显示，消除位置跳动感。

参考设计 (References)

Microsoft Fluent UI Blazor - Menu API (v4.13.2)

在 Playground 中打开 →