mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-28 14:20:47 +08:00
241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
# Menu 菜单
|
||
|
||
## 概述
|
||
|
||
菜单（Menu）用于为页面和功能提供导航菜单。AtomUI 的菜单控件家族包括三个核心组件：`Menu`（顶部菜单栏）、`MenuItem`（菜单项）和 `ContextMenu`（右键上下文菜单），以及辅助的 `MenuSeparator`（分隔线）和 `MenuFlyout`（弹出菜单）。
|
||
|
||
AtomUI 的 `Menu` 控件对应 [Ant Design 5.0 Menu](https://ant.design/components/menu-cn) 组件中的水平菜单模式，在 .NET / Avalonia 平台上提供一致的交互体验。
|
||
|
||
> **注意**：Ant Design 的 `Menu` 组件还包含 Inline（内嵌）和 Vertical（垂直弹出）模式，这些在 AtomUI 中由独立的 `NavMenu` 控件实现，详见 `docs/Desktop.Controls/NavMenu/` 文档。
|
||
|
||
---
|
||
|
||
## 设计原理
|
||
|
||
### Ant Design 的 Menu 设计哲学
|
||
|
||
Ant Design 的 Menu 定位为：**应用和页面的功能导航载体**。核心设计目标包括：
|
||
|
||
- **层级嵌套**：支持多级子菜单，通过弹出层展示下级菜单项
|
||
- **多种模式**：水平（horizontal）、垂直弹出（vertical）、内嵌展开（inline）
|
||
- **丰富的菜单项类型**：普通项、分组、分隔线、CheckBox/Radio 切换项
|
||
- **图标支持**：菜单项可包含前置图标
|
||
- **快捷键提示**：显示键盘快捷方式
|
||
|
||
### Avalonia 基础能力
|
||
|
||
AtomUI 的 `Menu`、`MenuItem`、`ContextMenu` 分别继承自 Avalonia 的同名控件，通过别名避免冲突：
|
||
|
||
```csharp
|
||
using AvaloniaMenu = Avalonia.Controls.Menu;
|
||
using AvaloniaMenuItem = Avalonia.Controls.MenuItem;
|
||
using AvaloniaContextMenu = Avalonia.Controls.ContextMenu;
|
||
```
|
||
|
||
**Avalonia Menu 体系的核心能力：**
|
||
|
||
| 能力 | 说明 |
|
||
|---|---|
|
||
| `Menu` | 顶部水平菜单栏，继承自 `MenuBase`，管理顶层菜单项 |
|
||
| `MenuItem` | 菜单项，继承自 `HeaderedSelectingItemsControl`，支持嵌套子项、图标、快捷键 |
|
||
| `ContextMenu` | 右键弹出菜单，绑定到控件的 `ContextMenu` 属性 |
|
||
| `MenuBase.IsOpen` | 菜单是否处于打开状态 |
|
||
| `MenuItem.IsSubMenuOpen` | 子菜单是否打开 |
|
||
| `MenuItem.ToggleType` | 支持 None/CheckBox/Radio 三种切换类型 |
|
||
| `MenuItem.InputGesture` | 快捷键手势绑定 |
|
||
| `MenuItem.Header` | 菜单项标题内容 |
|
||
| `MenuItem.Command` | 点击命令绑定 |
|
||
|
||
### AtomUI 的扩展设计
|
||
|
||
| 扩展能力 | 实现方式 | 设计动机 |
|
||
|---|---|---|
|
||
| **三种尺寸** | `ISizeTypeAware`（Large/Middle/Small） | 菜单栏适配不同布局密度 |
|
||
| **弹出动画** | `IMotionAwareControl` + Popup 动画 | 子菜单弹出/关闭的过渡动画 |
|
||
| **自定义图标** | `PathIcon` 类型的 `Icon` 属性（重写基类） | 使用 Ant Design 图标集 |
|
||
| **数据驱动** | `IMenuItemData` / `MenuItemData` / `MenuSeparatorData` | 支持通过数据模型和 `ItemsSource` 生成菜单结构 |
|
||
| **可滚动子菜单** | `DisplayPageSize` + `ScrollViewer` | 子菜单项过多时自动出现滚动 |
|
||
| **分隔线** | `MenuSeparator` + `MenuSeparatorData` | 自定义分隔线控件，从 Token 系统获取样式 |
|
||
| **CheckBox/Radio** | `ToggleType` + `IsCheckStateChanged` 事件 | 菜单项支持选中/取消选中交互 |
|
||
| **Design Token** | `MenuToken` + `RegisterTokenResourceScope` | 所有视觉值从 Token 系统派生 |
|
||
| **OverlayLayer** | `ShouldUseOverlayLayer` 属性 | 支持使用 OverlayLayer 作为 Popup 宿主 |
|
||
|
||
---
|
||
|
||
## 功能详解
|
||
|
||
### Menu（顶部菜单栏）
|
||
|
||
`Menu` 是水平排列的顶部菜单栏，包含多个顶层 `MenuItem`。每个顶层项可有子菜单，点击后以 Popup 弹出展示。
|
||
|
||
**关键行为：**
|
||
- 顶层菜单项使用 `TopLevelMenuItemTheme` 主题，样式与子菜单项不同
|
||
- 使用自定义 `DefaultMenuInteractionHandler` 处理菜单交互
|
||
- 关闭时支持动画（`IsMotionEnabled`），逐级关闭子菜单的 Popup
|
||
|
||
### MenuItem（菜单项）
|
||
|
||
`MenuItem` 是菜单的基本构建块。支持以下特性：
|
||
|
||
| 特性 | 说明 |
|
||
|---|---|
|
||
| 嵌套子菜单 | `MenuItem` 可包含子 `MenuItem`，子菜单以 Popup 弹出 |
|
||
| 图标 | `Icon` 属性（`PathIcon?`），与 Ant Design 图标集配合 |
|
||
| 快捷键 | `InputGesture` 属性，显示在菜单项右侧 |
|
||
| CheckBox/Radio 切换 | `ToggleType` 属性，支持 None/CheckBox/Radio |
|
||
| 分组 | `GroupName` 属性，用于 Radio 类型的互斥分组 |
|
||
| 禁用 | `IsEnabled = false`，灰色调显示 |
|
||
| 危险样式 | 通过 Token 支持危险色（`DangerItemColor`） |
|
||
|
||
### ContextMenu（右键菜单）
|
||
|
||
`ContextMenu` 通过右键触发弹出的浮动菜单。与 `Menu` 共享 `MenuToken`，使用相同的菜单项样式。
|
||
|
||
**关键行为：**
|
||
- 自动管理 Popup 生命周期
|
||
- 支持窗口失活时自动关闭
|
||
- 支持检测外部点击关闭
|
||
- 支持动画开关
|
||
|
||
### MenuSeparator（分隔线）
|
||
|
||
自定义分隔线控件，继承自 Avalonia `Separator`。在菜单中水平显示，用于分组菜单项。
|
||
|
||
### 数据驱动模式
|
||
|
||
通过 `IMenuItemData` 接口和 `MenuItemData` 类，支持使用数据模型 + `ItemTemplate` 生成菜单结构：
|
||
|
||
```csharp
|
||
public interface IMenuItemData : ITreeNode<IMenuItemData>
|
||
{
|
||
KeyGesture? InputGesture { get; }
|
||
}
|
||
```
|
||
|
||
`MenuSeparatorData` 继承自 `MenuItemData`，当数据项为 `MenuSeparatorData` 类型时，自动创建 `MenuSeparator` 容器。
|
||
|
||
---
|
||
|
||
## 与 Ant Design 规范的对齐程度
|
||
|
||
| 特性 | Ant Design (React) | AtomUI (Avalonia) | 对齐情况 |
|
||
|---|---|---|---|
|
||
| 水平顶部菜单 | ✅ `mode="horizontal"` | ✅ `Menu`（水平菜单栏） | ✅ 对齐 |
|
||
| 垂直弹出菜单 | ✅ `mode="vertical"` | ✅ `NavMenu Mode="Vertical"` | ✅ 对齐（独立控件） |
|
||
| 内嵌展开菜单 | ✅ `mode="inline"` | ✅ `NavMenu Mode="Inline"` | ✅ 对齐（独立控件） |
|
||
| 子菜单嵌套 | ✅ `children` 属性 | ✅ `MenuItem` 嵌套子项 | ✅ 对齐 |
|
||
| 图标 | ✅ `icon` 属性 | ✅ `Icon`（`PathIcon`） | ✅ 对齐 |
|
||
| 禁用 | ✅ `disabled` | ✅ `IsEnabled` | ✅ 对齐 |
|
||
| 分隔线 | ✅ `type: "divider"` | ✅ `MenuSeparator` / `MenuSeparatorData` | ✅ 对齐 |
|
||
| 选中状态 | ✅ `selectedKeys` | ✅ `ToggleType` + `IsChecked` | ✅ 对齐 |
|
||
| 快捷键提示 | ❌ 无原生支持 | ✅ `InputGesture` | ✅ 超集 |
|
||
| CheckBox/Radio | ❌ 无原生支持 | ✅ `ToggleType` | ✅ 超集 |
|
||
| 数据驱动 | ✅ `items` 属性 | ✅ `ItemsSource` + `IMenuItemData` | ✅ 对齐 |
|
||
| 右键菜单 | ❌（使用 Dropdown） | ✅ `ContextMenu` | ✅ 扩展 |
|
||
| 弹出动画 | ✅ 内置动画 | ✅ `IsMotionEnabled` | ✅ 对齐 |
|
||
| 危险菜单项 | ✅ `danger` 属性 | ✅ `DangerItemColor` Token | ✅ 对齐 |
|
||
|
||
---
|
||
|
||
## 继承关系
|
||
|
||
### Menu
|
||
|
||
```
|
||
Avalonia.Controls.MenuBase
|
||
└── Avalonia.Controls.Menu
|
||
└── AtomUI.Desktop.Controls.Menu
|
||
├── implements ISizeTypeAware
|
||
└── implements IMotionAwareControl
|
||
```
|
||
|
||
### MenuItem
|
||
|
||
```
|
||
Avalonia.Controls.HeaderedSelectingItemsControl
|
||
└── Avalonia.Controls.MenuItem
|
||
└── AtomUI.Desktop.Controls.MenuItem
|
||
└── implements IMenuItemData
|
||
```
|
||
|
||
### ContextMenu
|
||
|
||
```
|
||
Avalonia.Controls.MenuBase
|
||
└── Avalonia.Controls.ContextMenu
|
||
└── AtomUI.Desktop.Controls.ContextMenu
|
||
├── implements ISizeTypeAware
|
||
└── implements IMotionAwareControl
|
||
```
|
||
|
||
### MenuSeparator
|
||
|
||
```
|
||
Avalonia.Controls.Separator
|
||
└── AtomUI.Desktop.Controls.MenuSeparator
|
||
```
|
||
|
||
---
|
||
|
||
## 源码位置
|
||
|
||
| 层级 | 文件路径 | 说明 |
|
||
|---|---|---|
|
||
| Menu | `src/AtomUI.Desktop.Controls/Menu/Menu.cs` | 顶部菜单栏 |
|
||
| MenuItem | `src/AtomUI.Desktop.Controls/Menu/MenuItem.cs` | 菜单项 |
|
||
| ContextMenu | `src/AtomUI.Desktop.Controls/Menu/ContextMenu.cs` | 右键上下文菜单 |
|
||
| MenuSeparator | `src/AtomUI.Desktop.Controls/Menu/MenuSeparator.cs` | 菜单分隔线 |
|
||
| MenuItemData | `src/AtomUI.Desktop.Controls/Menu/MenuItemData.cs` | 数据模型接口和类 |
|
||
| MenuSeparatorData | `src/AtomUI.Desktop.Controls/Menu/MenuSeparatorData.cs` | 分隔线数据模型 |
|
||
| MenuItemPseudoClass | `src/AtomUI.Desktop.Controls/Menu/MenuItemPseudoClass.cs` | 伪类常量 |
|
||
| Token 定义 | `src/AtomUI.Desktop.Controls/Menu/MenuToken.cs` | 组件级 Design Token（40+ 属性） |
|
||
| Menu 主题 | `src/AtomUI.Desktop.Controls/Menu/Themes/MenuTheme.axaml` | Menu ControlTheme |
|
||
| MenuItem 主题 | `src/AtomUI.Desktop.Controls/Menu/Themes/MenuItemTheme.axaml` | MenuItem ControlTheme |
|
||
| ContextMenu 主题 | `src/AtomUI.Desktop.Controls/Menu/Themes/ContextMenuTheme.axaml` | ContextMenu ControlTheme |
|
||
| TopLevelMenuItem 主题 | `src/AtomUI.Desktop.Controls/Menu/Themes/TopLevelMenuItemTheme.axaml` | 顶层菜单项 ControlTheme |
|
||
| MenuSeparator 主题 | `src/AtomUI.Desktop.Controls/Menu/Themes/MenuSeparatorTheme.axaml` | 分隔线 ControlTheme |
|
||
| 模板常量 | `src/AtomUI.Desktop.Controls/Menu/Themes/MenuThemeConstants.cs` | 模板部件常量 |
|
||
| Gallery 示例 | `controlgallery/AtomUIGallery/ShowCases/Views/Navigation/MenuShowCase.axaml` | 使用范例 |
|
||
|
||
---
|
||
|
||
## 模板结构
|
||
|
||
### Menu 模板
|
||
|
||
```
|
||
Border (背景、边框、圆角)
|
||
└── ItemsPresenter (PART_ItemsPresenter)
|
||
└── StackPanel (Horizontal) ← 水平排列顶层菜单项
|
||
```
|
||
|
||
### MenuItem 模板
|
||
|
||
```
|
||
Panel
|
||
├── Border#Frame (背景、圆角、内间距)
|
||
│ └── Grid (5 列)
|
||
│ ├── Panel#ToggleItemsLayout ← CheckBox/Radio 切换控件
|
||
│ │ ├── CheckBox (PART_ToggleCheckbox)
|
||
│ │ └── RadioButton (PART_ToggleRadio)
|
||
│ ├── IconPresenter#ItemIconPresenter ← 图标
|
||
│ ├── ContentPresenter#ItemTextPresenter ← 标题文本
|
||
│ ├── TextBlock#InputGestureText ← 快捷键提示
|
||
│ └── RightOutlined#MenuIndicatorIcon ← 子菜单箭头
|
||
└── Popup (PART_Popup) ← 子菜单弹窗
|
||
└── Border#PopupFrame
|
||
└── ScrollViewer
|
||
└── ItemsPresenter (PART_ItemsPresenter)
|
||
```
|
||
|
||
### 模板部件常量
|
||
|
||
| 类 | 常量名 | 值 | 说明 |
|
||
|---|---|---|---|
|
||
| `MenuThemeConstants` | `ItemsPresenterPart` | `"PART_ItemsPresenter"` | Menu 项列表 |
|
||
| `MenuItemThemeConstants` | `ToggleCheckboxPart` | `"PART_ToggleCheckbox"` | CheckBox 切换 |
|
||
| `MenuItemThemeConstants` | `ToggleRadioPart` | `"PART_ToggleRadio"` | Radio 切换 |
|
||
| `MenuItemThemeConstants` | `ItemsPresenterPart` | `"PART_ItemsPresenter"` | 子菜单项列表 |
|
||
| `ContextMenuThemeConstants` | `ItemsPresenterPart` | `"PART_ItemsPresenter"` | ContextMenu 项列表 |
|
||
| `TopLevelMenuItemThemeConstants` | `ItemsPresenterPart` | `"PART_ItemsPresenter"` | 顶层菜单项子菜单 |
|