AtomUI/docs/Desktop.Controls/DropdownButton/DropdownButton.md

# DropdownButton 下拉按钮

## 概述

下拉按钮（DropdownButton）是一个附带下拉菜单的按钮控件。点击或悬浮按钮后，会弹出一个菜单列表供用户选择操作。它将按钮的触发交互和菜单的选项展示结合在一起，是 Ant Design [Dropdown](https://ant.design/components/dropdown-cn) 组件的 AtomUI 实现。

DropdownButton 继承自 `Button`（AtomUI 的桌面端 Button 控件），因此完整具备 Button 的所有能力（按钮类型、尺寸、危险样式、图标、加载状态、波纹效果等），同时额外提供了弹出菜单的管理能力。

---

## 设计原理

### Ant Design 的下拉菜单设计哲学

Ant Design 中 `Dropdown` 是一个独立的行为组件，包裹在任意触发元素外层，为其附加下拉菜单弹出功能。`Dropdown.Button` 则是其带按钮外观的变体——一个将「按钮」与「下拉菜单」融合的复合控件，用户既能直接点击按钮执行主操作，又能通过下拉箭头访问更多操作。

核心设计思想：

| 设计维度 | 设计意图 |
|---|---|
| **操作聚合** | 将多个相关操作收纳到一个下拉菜单中，减少界面上的按钮数量 |
| **触发灵活** | 支持点击（Click）和悬浮（Hover）两种触发方式，适应不同场景 |
| **位置可控** | 弹出菜单支持多种方位（上下 × 左中右），自动适应可用空间 |
| **视觉一致** | 按钮部分与 Button 组件保持一致的视觉体系 |

### Avalonia Button 基础能力

DropdownButton 的继承链经过 AtomUI Button → Avalonia Button，因此天然具备 Avalonia Button 的全部基础能力：

- `Content` / `ContentTemplate` — 任意内容承载
- `Command` / `CommandParameter` — MVVM 命令绑定
- `HotKey` — 键盘快捷键
- `Click` 事件 — 按钮点击语义事件
- `IsEnabled` — 启用/禁用

同时也继承了 AtomUI Button 的全部扩展能力：五种按钮类型、三种形状、三种尺寸、危险/幽灵样式、加载状态、波纹效果、Design Token 集成等。

### AtomUI 的扩展设计

AtomUI 将 Ant Design 的 `Dropdown` 和 `Dropdown.Button` 统一为 `DropdownButton`：它本身就是一个 Button，同时内置了 Flyout 弹出管理机制。弹出的菜单通过 `DropdownFlyout` 属性（类型为 `MenuFlyout`）配置。

| 扩展能力 | 实现方式 | 设计动机 |
|---|---|---|
| **弹出菜单** | `DropdownFlyout` 属性（`MenuFlyout`） | 声明式配置下拉菜单内容 |
| **触发方式** | `TriggerType` 枚举（Click / Hover） | 对齐 Ant Design 的 `trigger` 属性 |
| **弹出位置** | `Placement` / `PlacementAnchor` / `PlacementGravity` | 精细控制弹出方位 |
| **箭头指示** | `IsShowArrow` / `IsPointAtCenter` | 弹出菜单上显示指向触发元素的箭头 |
| **延迟策略** | `MouseEnterDelay` / `MouseLeaveDelay` | 控制悬浮触发的进入/离开延迟 |
| **下拉指示器** | `OpenIndicator` / `IsShowOpenIndicator` | 按钮右侧的下拉箭头图标（默认 `DownOutlined`） |
| **菜单项事件** | `MenuItemClicked` 路由事件 | 统一监听弹出菜单中任意菜单项的点击 |

---

## 功能详解

### 弹出机制

DropdownButton 内部使用 `FlyoutStateHelper` 来管理弹出状态。`FlyoutStateHelper` 是 AtomUI 封装的 Flyout 生命周期管理器，负责：

1. **触发方式管理**：根据 `TriggerType` 决定是 Click 还是 Hover 触发弹出
2. **延迟控制**：`MouseEnterDelay` / `MouseLeaveDelay` 控制 Hover 模式下的弹出/关闭延迟
3. **生命周期**：在控件 Attach/Detach 到可视化树时自动管理弹出层的注册与销毁
4. **属性中继**：DropdownButton 上设置的 `Placement`、`IsShowArrow`、`IsPointAtCenter`、`MarginToAnchor`、`IsMotionEnabled` 等属性自动中继（Relay Bind）到 `MenuFlyout`

### 下拉指示器

DropdownButton 默认在按钮内容右侧显示一个下拉箭头图标（`DownOutlined`），初始化时自动设置。通过 `OpenIndicator` 属性可自定义图标，通过 `IsShowOpenIndicator` 可隐藏。

当按钮没有 Content、ContentTemplate、Icon 且不处于 Loading 状态时，内容区域自动隐藏，仅显示下拉指示器。这由内部的 `IsContentVisible` 属性智能控制。

### 菜单项点击事件

DropdownButton 提供了 `MenuItemClicked` 路由事件（`RoutingStrategies.Bubble`），当用户点击弹出菜单中的某个菜单项时触发。事件参数 `FlyoutMenuItemClickedEventArgs` 包含被点击的 `MenuItem` 引用，避免了手动为每个 `MenuItem` 单独注册 Click 事件。

### 弹出位置

支持 6 种标准弹出位置（对齐 Ant Design 的 `placement` 属性），默认为 `BottomEdgeAlignedLeft`：

| Placement 值 | 说明 | 对应 Ant Design |
|---|---|---|
| `BottomEdgeAlignedLeft` | 底部左对齐（默认） | `bottomLeft` |
| `Bottom` | 底部居中 | `bottom` |
| `BottomEdgeAlignedRight` | 底部右对齐 | `bottomRight` |
| `TopEdgeAlignedLeft` | 顶部左对齐 | `topLeft` |
| `Top` | 顶部居中 | `top` |
| `TopEdgeAlignedRight` | 顶部右对齐 | `topRight` |

### 点击隐藏策略

当 `TriggerType` 为 `Click` 时，点击弹出层外部即关闭菜单。当 `TriggerType` 为 `Hover` 时，仅当点击位置不在按钮区域内才关闭菜单。这确保了 Hover 模式下不会因误触按钮区域而关闭菜单。

---

## 与 Ant Design 规范的对齐程度

| 特性 | Ant Design (React) | AtomUI (Avalonia) | 对齐情况 |
|---|---|---|---|
| 触发方式 `trigger` | ✅ `click` / `hover` / `contextMenu` | ✅ `TriggerType`（Click / Hover） | ⚠️ 不支持右键触发 |
| 菜单弹出位置 `placement` | ✅ 6 个方向 | ✅ `Placement`（6 个方向 + 更多） | ✅ 完全对齐 |
| 箭头指示 `arrow` | ✅ 布尔/对象 | ✅ `IsShowArrow` + `IsPointAtCenter` | ✅ 完全对齐 |
| 按钮类型 `type` | ✅ `type` prop | ✅ `ButtonType`（继承 Button） | ✅ 完全对齐 |
| 菜单项点击 `onMenuClick` | ✅ 回调函数 | ✅ `MenuItemClicked` 路由事件 | ✅ 完全对齐 |
| 悬浮延迟 | ✅ `mouseEnterDelay` / `mouseLeaveDelay` | ✅ `MouseEnterDelay` / `MouseLeaveDelay` | ✅ 完全对齐 |
| 禁用 `disabled` | ✅ 布尔 | ✅ `IsEnabled`（继承 Button） | ✅ 完全对齐 |
| 按钮尺寸 `size` | ✅ `large / middle / small` | ✅ `SizeType`（继承 Button） | ✅ 完全对齐 |
| 按钮危险样式 `danger` | ✅ 布尔 | ✅ `IsDanger`（继承 Button） | ✅ 完全对齐 |
| 加载状态 `loading` | ✅ 布尔 | ✅ `IsLoading`（继承 Button） | ✅ 完全对齐 |
| 受控弹出 `open` / `onOpenChange` | ✅ 受控模式 | ❌ 暂未提供 | ⚠️ 待支持 |

---

## 继承关系

```
Avalonia.Controls.Primitives.TemplatedControl
  └── Avalonia.Controls.ContentControl
        └── Avalonia.Controls.Button (ICommandSource, IClickableControl)
              └── AtomUI.Desktop.Controls.Button
                    ├── implements ISizeTypeAware
                    ├── implements IWaveSpiritAwareControl
                    ├── implements ICompactSpaceAware
                    └── implements IFormItemAware
                          └── AtomUI.Desktop.Controls.DropdownButton
                                └── + DropdownFlyout / TriggerType / Placement / 箭头 / 菜单项事件
```

**各层级职责划分：**

| 层级 | 提供的能力 |
|---|---|
| `Avalonia.Controls.Button` | 指针交互 → Click 事件、`ICommand` 绑定、`IsPressed` 状态、`HotKey` 快捷键、`Flyout` 弹出 |
| `AtomUI.Desktop.Controls.Button` | Ant Design 视觉体系（五种类型/三种形状/三种尺寸）、Design Token 集成、WaveSpirit 波纹、加载状态、危险/幽灵样式、紧凑空间适配、表单集成 |
| `AtomUI.Desktop.Controls.DropdownButton` | DropdownFlyout 管理、TriggerType、Placement、箭头指示、菜单项事件、下拉指示器 |

---

## 源码位置

| 层级 | 文件路径 | 说明 |
|---|---|---|
| 控件类 | `src/AtomUI.Desktop.Controls/Buttons/DropdownButton.cs` | 桌面端下拉按钮实现 |
| 主题模板 | `src/AtomUI.Desktop.Controls/Buttons/Themes/DropdownButtonTheme.axaml` | ControlTheme AXAML |
| 主题代码 | `src/AtomUI.Desktop.Controls/Buttons/Themes/DropdownButtonTheme.cs` | 主题 code-behind |
| 模板常量 | `src/AtomUI.Desktop.Controls/Buttons/Themes/DropdownButtonThemeConstants.cs` | 模板部件名称常量 |
| Gallery 示例 | `controlgallery/AtomUIGallery/ShowCases/Views/Navigation/DropdownButtonShowCase.axaml` | 使用范例 |

---

## 模板结构

DropdownButton 的模板继承自 Button 模板（通过 `ControlTheme.BasedOn`），为每种 `ButtonType`（Default / Primary / Link / Text）分别定义了独立的模板变体。核心差异在于：在 Button 模板的内容区域右侧增加了一个下拉指示器 `IconPresenter`，使用 `DockPanel` 布局使指示器固定在右侧。

```
Panel
├── WaveSpiritDecorator (PART_WaveSpirit)           ← 点击波纹效果层（仅 Default / Primary 类型）
├── Border#ShadowsFrame                              ← 阴影层（仅 Default 类型）
├── Border#Frame (主框架)                            ← 背景、边框、圆角
│   └── DockPanel (PART_RootLayout)                  ← 内容布局容器
│       ├── IconPresenter (PART_DropdownIndicator)   ← 下拉指示器（DockPanel.Dock="Right"）
│       └── StackPanel (PART_MainInfoLayout)         ← 内容区域（填充剩余空间）
│           ├── LoadingOutlined (PART_LoadingIcon)    ← 加载旋转图标
│           ├── IconPresenter (PART_ButtonIcon)       ← 按钮图标
│           └── ContentPresenter (PART_ContentPresenter) ← 文本/自定义内容
```

**模板变体差异：**

| ButtonType | 波纹效果 | 阴影层 | 说明 |
|---|---|---|---|
| `Default` | ✅ WaveSpiritDecorator | ✅ Border#ShadowsFrame | 白色背景 + 边框 + 阴影 |
| `Primary` | ✅ WaveSpiritDecorator | ❌ | 主色调填充 |
| `Link` | ❌ | ❌ | 无边框无背景 |
| `Text` | ❌ | ❌ | 无边框无背景 |

### 模板部件常量

| 常量名 | 值 | 说明 |
|---|---|---|
| `DropdownButtonThemeConstants.DropdownIndicatorPart` | `"PART_DropdownIndicator"` | 下拉指示器图标 |
| `ButtonThemeConstants.WaveSpiritPart` | `"PART_WaveSpirit"` | 波纹动画装饰器 |
| `ButtonThemeConstants.RootLayoutPart` | `"PART_RootLayout"` | 根布局面板 |
| `ButtonThemeConstants.MainInfoLayoutPart` | `"PART_MainInfoLayout"` | 主信息布局面板 |
| `ButtonThemeConstants.LoadingIconPart` | `"PART_LoadingIcon"` | 加载旋转图标 |
| `ButtonThemeConstants.ButtonIconPart` | `"PART_ButtonIcon"` | 按钮图标展示器 |
| `ButtonThemeConstants.ContentPresenterPart` | `"PART_ContentPresenter"` | 内容展示器 |