docs(Button): add comprehensive design, API, styling, token and usage documentation

docs/Desktop.Controls/Button/Button.md

@@ -0,0 +1,256 @@
+# Button 按钮
+
+## 概述
+
+按钮（Button）是图形界面中最基础、最常见的交互控件，用于触发一个即时操作。用户通过点击按钮来启动业务逻辑，如提交表单、打开对话框、执行删除等。按钮是用户意图到应用响应之间的桥梁——它既承载视觉提示（告诉用户「这里可以点击」），又承载交互反馈（告诉用户「你的操作已被接受」）。
+
+AtomUI 的 `Button` 控件完整复刻了 [Ant Design 5.0 Button](https://ant.design/components/button-cn) 的设计规范，在 .NET / Avalonia 平台上提供与 Ant Design React 版一致的视觉体验和交互行为。
+
+---
+
+## 设计原理
+
+### Ant Design 的按钮设计哲学
+
+Ant Design 对按钮的定位是：**「标记一个（或封装一组）操作命令，响应用户点击行为，触发相应的业务逻辑」**。为了帮助用户在不同场景中快速识别操作的优先级和性质，Ant Design 建立了一套完整的按钮分类体系：
+
+**五种按钮类型**（按视觉权重从高到低排列）：
+
+| 类型 | 设计意图 | 典型用途 |
+|---|---|---|
+| 🔵 **主按钮（Primary）** | 视觉权重最高，实心填充主色调。一个操作区域**只应有一个**主按钮，引导用户完成核心操作 | 「提交」「确认」「保存」 |
+| ⚪️ **默认按钮（Default）** | 中等视觉权重，白色背景 + 边框。用于同一区域中**无主次之分**的多个操作 | 「取消」「重置」「上一步」 |
+| 😶 **虚线按钮（Dashed）** | 虚线边框传达「未完成 / 可添加」语义，暗示用户此处可以补充内容 | 「+ 添加条目」「上传文件」 |
+| 🔤 **文本按钮（Text）** | 最低视觉权重，无边框无背景，仅保留文字。用于最次级操作，减少视觉干扰 | 「编辑」「更多」内联操作 |
+| 🔗 **链接按钮（Link）** | 外观类似超链接，暗示"导航"而非"操作"。适合跳转类交互 | 「查看详情」「忘记密码？」 |
+
+**四种状态修饰**（可与上述五种类型自由组合）：
+
+| 状态 | 设计意图 |
+|---|---|
+| ⚠️ **危险（Danger）** | 使用红色系警示用户该操作具有破坏性（删除、移动、修改权限），通常配合二次确认 |
+| 👻 **幽灵（Ghost）** | 背景透明，文字/边框使用浅色或主题色。专为复杂背景场景设计（首页横幅、产品展示页） |
+| 🚫 **禁用（Disabled）** | 降低不透明度 + 灰色调，告诉用户该操作当前不可用，通常需配合提示文案说明原因 |
+| 🔃 **加载中（Loading）** | 显示旋转图标 + 降低不透明度，用于异步操作的等待反馈，同时防止用户重复提交 |
+
+### Avalonia Button 基础能力
+
+AtomUI 的 `Button` 继承自 Avalonia 框架的 `Avalonia.Controls.Button`。理解 Avalonia Button 的基础能力有助于理解 AtomUI 在其之上做了哪些扩展。
+
+**Avalonia Button 的核心职责：**
+
+Avalonia 的 `Button` 是一个标准的 `ContentControl`（内容控件），它实现了 `ICommandSource` 和 `IClickableControl` 接口。其核心行为是：**响应指针操作，在指针按下时提供视觉按压反馈（`:pressed` 伪类），在指针释放时触发 `Click` 事件**。它的继承链为：
+
+```
+Control → TemplatedControl → ContentControl → Button
+```
+
+作为 `ContentControl`，Button 能容纳任意内容（文本、图标、甚至复杂布局），并通过 `ContentPresenter` 在模板中呈现。Button 还提供了完整的命令绑定（MVVM `Command` / `CommandParameter`）、键盘快捷键（`HotKey`）、`IsDefault` / `IsCancel` 键盘激活、以及 `Flyout` 弹出等基础设施。
+
+**Avalonia Button 提供的基础属性：**
+
+| 属性 | 说明 |
+|---|---|
+| `Content` | 按钮内容，可以是文本字符串，也可以是任意控件 |
+| `Command` / `CommandParameter` | MVVM 命令绑定，按钮点击时调用 `ICommand.Execute`；当 `CanExecute` 返回 `false` 时自动禁用按钮 |
+| `ClickMode` | 控制 `Click` 事件的触发时机：`Release`（指针释放时，默认）或 `Press`（指针按下时） |
+| `HotKey` | 键盘快捷键（`KeyGesture`），注册后按下对应组合键等同于点击按钮 |
+| `IsDefault` | 设为 `true` 时，用户按 **Enter** 键等同于点击该按钮（常用于对话框「确认」按钮） |
+| `IsCancel` | 设为 `true` 时，用户按 **Escape** 键等同于点击该按钮（常用于对话框「取消」按钮） |
+| `IsPressed` | 只读属性，指示按钮当前是否处于按压状态 |
+| `Flyout` | 附加弹出层，点击按钮时自动展开 `Flyout` / `MenuFlyout` |
+
+**Avalonia Button 提供的基础伪类：**
+
+| 伪类 | 说明 |
+|---|---|
+| `:pointerover` | 鼠标悬浮在按钮上 |
+| `:pressed` | 按钮被按下 |
+| `:disabled` | `IsEnabled == false` |
+| `:focus` | 按钮获得焦点 |
+| `:focus-visible` | 通过键盘（Tab）获得焦点 |
+| `:flyout-open` | 附加的 Flyout 处于打开状态 |
+
+> **重要提示**：应始终使用 `Click` 事件而非 `PointerPressed` 来处理按钮点击。`Click` 是 Button 专属的高级语义事件；而 `PointerPressed` 是底层输入事件，Button 内部会将其标记为 `IsHandled = true`，外部通常无法接收到。
+
+### AtomUI 的扩展设计
+
+AtomUI `Button` 在 Avalonia Button 的基础上，遵循 Ant Design 5.0 规范做了以下扩展：
+
+| 扩展能力 | 实现方式 | 设计动机 |
+|---|---|---|
+| **五种按钮类型** | `ButtonType` 枚举 + 伪类驱动样式 | 对齐 Ant Design 的 `type` 属性，支持 Primary / Default / Dashed / Text / Link |
+| **三种按钮形状** | `ButtonShape` 枚举 + `MeasureOverride` 动态计算 | 对齐 Ant Design 的 `shape`，在布局阶段自动调整尺寸和圆角 |
+| **三种尺寸** | `ISizeTypeAware` 接口 + `SizeType` 共享属性 | 全局统一的 Large / Middle / Small 尺寸系统 |
+| **危险/幽灵状态** | `IsDanger` / `IsGhost` 属性 + 主题样式变体 | 通过 Token 系统自动切换颜色方案 |
+| **加载状态** | `IsLoading` 属性 + 模板内 `LoadingOutlined` 图标 | 旋转加载图标 + 降低不透明度，防止重复操作 |
+| **图标支持** | `Icon` 属性（`PathIcon` 类型）+ `IconPresenter` | 内置图标栏位，无需手动组装 StackPanel + Icon |
+| **点击波纹** | `IWaveSpiritAwareControl` + `WaveSpiritDecorator` | 复刻 Ant Design 的 Wave 点击涟漪效果 |
+| **过渡动画** | `IsMotionEnabled` + `Transitions` 动态配置 | 背景色、前景色、边框色平滑过渡 |
+| **紧凑空间** | `ICompactSpaceAware` 接口 | 在 `Space.Compact` 容器中自动调整圆角和边框 |
+| **表单集成** | `IFormItemAware` 接口 | 可参与 FormItem 验证流程 |
+| **Design Token** | `ButtonToken` + `RegisterTokenResourceScope` | 所有视觉值从全局/组件级 Token 派生，支持主题切换 |
+
+---
+
+## 功能详解
+
+### 按钮类型（ButtonType）
+
+按钮类型通过 `ButtonType` 属性设置，每种类型对应不同的伪类（`:primary`、`:default`、`:dashed`、`:text`、`:link`），ControlTheme 通过这些伪类应用不同的视觉样式。
+
+不同类型的模板差异：
+- **Default / Primary / Link / Text**：使用标准 `Border` 作为主框架。
+- **Dashed**：使用自定义 `DashedBorder` 控件绘制虚线边框，通过 `StrokeDashArray = [4, 2]` 实现虚线效果。
+
+不同类型的阴影差异：
+- **Default / Dashed**：有 `DefaultShadow` 底部微阴影，增强立体感。
+- **Primary**：有 `PrimaryShadow` 底部微阴影。
+- **Text / Link**：无阴影，保持轻量感。
+
+不同类型的波纹差异：
+- **Primary / Default / Dashed**：按下释放时触发 WaveSpirit 波纹动画。
+- **Text / Link**：不触发波纹（这两种类型视觉权重低，波纹会造成过度干扰）。
+
+### 按钮形状（ButtonShape）
+
+形状通过 `MeasureOverride` 在布局阶段动态计算：
+
+| 形状 | 布局行为 | 圆角计算 |
+|---|---|---|
+| `Default` | 宽度 = `max(内容宽度, 高度)`，保证最小正方形 | 由 Token 中 `BorderRadius` / `BorderRadiusSM` / `BorderRadiusLG` 控制 |
+| `Circle` | 强制 `宽度 = 高度`，呈正圆形 | `CornerRadius = 高度`（完全圆角） |
+| `Round` | 宽度 = `max(内容宽度, 高度 × 1.5)`，呈胶囊形 | `CornerRadius = 高度`（两端完全圆角） |
+
+形状还影响波纹类型：`Default` → `RoundRectWave`，`Round` → `PillWave`，`Circle` → `CircleWave`。
+
+### 加载状态（IsLoading）
+
+当 `IsLoading = true` 时：
+1. `:loading` 伪类被激活
+2. 按钮图标（`PART_ButtonIcon`）隐藏，替换为旋转的 `LoadingOutlined` 图标
+3. 整体不透明度降至 `SharedToken.OpacityLoading`
+4. 波纹效果被禁止（`IsPressed` 变化时检查 `IsLoading`）
+
+### 过渡动画（Transitions）
+
+动画在 `OnLoaded` 时配置，`OnUnloaded` 时清除（避免不可见控件消耗资源）。不同 `ButtonType` 配置不同的过渡属性组合：
+
+| ButtonType | 过渡属性 |
+|---|---|
+| Primary（非 Ghost） | `Background` |
+| Primary（Ghost） | `Background` + `BorderBrush` + `Foreground` |
+| Default / Dashed | `Background` + `BorderBrush` + `Foreground` |
+| Link | `Background` + `Foreground` |
+| Text | `Background` |
+
+### 紧凑空间（Compact Space）
+
+当 Button 放置在 `Space.Compact` 容器中时：
+- 容器通知每个按钮其 `CompactSpaceItemPosition`（First / Middle / Last / OnlyOne）和 `CompactSpaceOrientation`（Horizontal / Vertical）
+- Button 根据位置自动裁剪圆角（例如水平排列的中间按钮圆角为 0）
+- Primary 类型按钮始终处于活跃 ZIndex 层，确保边框不被相邻按钮遮挡
+
+---
+
+## 与 Ant Design 规范的对齐程度
+
+| 特性 | Ant Design (React) | AtomUI (Avalonia) | 对齐情况 |
+|---|---|---|---|
+| 五种类型 `type` | ✅ `primary / default / dashed / text / link` | ✅ `ButtonType` 枚举 | ✅ 完全对齐 |
+| 三种形状 `shape` | ✅ `default / circle / round` | ✅ `ButtonShape` 枚举 | ✅ 完全对齐 |
+| 三种尺寸 `size` | ✅ `large / medium / small` | ✅ `SizeType` 属性 | ✅ 完全对齐 |
+| 危险 `danger` | ✅ 布尔属性 | ✅ `IsDanger` 属性 | ✅ 完全对齐 |
+| 幽灵 `ghost` | ✅ 布尔属性 | ✅ `IsGhost` 属性 | ✅ 完全对齐 |
+| 加载中 `loading` | ✅ 布尔/对象 | ✅ `IsLoading` 布尔 | ⚠️ 不支持延迟加载（`{ delay }` 语法） |
+| 图标 `icon` | ✅ ReactNode | ✅ `PathIcon` 属性 | ✅ 对齐（类型不同，语义一致） |
+| Block 模式 | ✅ `block` 属性 | ✅ `HorizontalAlignment="Stretch"` | ✅ 通过 Avalonia 原生布局实现 |
+| 点击波纹 | ✅ Wave 组件 | ✅ `WaveSpiritDecorator` | ✅ 完全对齐 |
+| 颜色+变体 `color` / `variant` | ✅ 5.21.0 新增 | ❌ 暂未支持 | ⚠️ 通过 `ButtonType` 覆盖主要场景 |
+| 图标位置 `iconPlacement` | ✅ `start / end` | ❌ 暂仅支持左侧 | ⚠️ 待支持 |
+| `href` / `target` | ✅ 链接跳转 | ❌ 不适用 | — 桌面端无需 HTML 超链接语义 |
+| `htmlType` | ✅ 原生表单提交 | ❌ 不适用 | — 非 Web 平台 |
+
+---
+
+## 继承关系
+
+```
+Avalonia.Controls.Primitives.TemplatedControl
+  └── Avalonia.Controls.ContentControl
+        └── Avalonia.Controls.Button (ICommandSource, IClickableControl)
+              └── AtomUI.Desktop.Controls.Button
+                    ├── implements ISizeTypeAware
+                    ├── implements IWaveSpiritAwareControl
+                    ├── implements ICompactSpaceAware
+                    └── implements IFormItemAware
+```
+
+`Button` 通过 `using AvaloniaButton = Avalonia.Controls.Button;` 别名引用 Avalonia 原生 Button，避免类名冲突。
+
+**各层级职责划分：**
+
+| 层级 | 提供的能力 |
+|---|---|
+| `ContentControl` | 任意内容容纳、`Content` / `ContentTemplate`、`ContentPresenter` 模板化呈现 |
+| `Avalonia.Controls.Button` | 指针交互 → Click 事件、`ICommand` 绑定、`IsPressed` 状态、`HotKey` 快捷键、`Flyout` 弹出、`IsDefault` / `IsCancel` 键盘激活、无障碍支持 |
+| `AtomUI.Desktop.Controls.Button` | Ant Design 视觉体系（五种类型/三种形状/三种尺寸）、Design Token 集成、WaveSpirit 波纹、加载状态、危险/幽灵样式、紧凑空间适配、表单集成 |
+
+**实现的共享接口：**
+
+| 接口 | 定义位置 | 作用 |
+|---|---|---|
+| `ISizeTypeAware` | `AtomUI.Controls.Shared` | 支持 `SizeType`（Small / Middle / Large）三种尺寸切换 |
+| `IWaveSpiritAwareControl` | `AtomUI.Controls.Shared` | 支持点击涟漪（Wave）动画效果 |
+| `ICompactSpaceAware` | `AtomUI.Controls.Shared` | 在 `Space.Compact` 中使用时自动调整圆角和边框 |
+| `IFormItemAware` | `AtomUI.Controls.Shared` | 可作为 `FormItem` 的子控件参与表单验证 |
+
+---
+
+## 源码位置
+
+| 层级 | 文件路径 | 说明 |
+|---|---|---|
+| 控件类 | `src/AtomUI.Desktop.Controls/Buttons/Button.cs` | 桌面端 Button 具体实现 |
+| 伪类常量 | `src/AtomUI.Controls/Buttons/ButtonPseudoClass.cs` | 共享伪类定义（跨平台） |
+| Token 定义 | `src/AtomUI.Desktop.Controls/Buttons/ButtonToken.cs` | 组件级 Design Token |
+| 主题模板 | `src/AtomUI.Desktop.Controls/Buttons/Themes/ButtonTheme.axaml` | ControlTheme AXAML |
+| 主题代码 | `src/AtomUI.Desktop.Controls/Buttons/Themes/ButtonTheme.cs` | 主题 code-behind |
+| 模板常量 | `src/AtomUI.Desktop.Controls/Buttons/Themes/ButtonThemeConstants.cs` | 模板部件名称常量 |
+| Gallery 示例 | `controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` | 使用范例 |
+
+---
+
+## 模板结构
+
+Button 的 ControlTemplate 采用分层 Panel 布局，每一层各司其职：
+
+```
+Panel
+├── WaveSpiritDecorator (PART_WaveSpirit)     ← 点击波纹效果层（最底层，不影响内容）
+├── Border#ShadowsFrame                       ← 阴影层（独立于主框架，避免 BoxShadow 被裁剪）
+├── Border#Frame (或 DashedBorder#Frame)      ← 主框架（承载背景、边框和全部内容）
+│   └── DockPanel (PART_RootLayout)           ← 内容布局容器
+│       ├── LoadingOutlined (PART_LoadingIcon) ← 加载旋转图标（DockPanel.Dock="Left"）
+│       ├── IconPresenter (PART_ButtonIcon)    ← 按钮图标展示器（DockPanel.Dock="Left"）
+│       └── ContentPresenter (PART_ContentPresenter) ← 文本/自定义内容（填充剩余空间）
+└── Border#FocusVisual                        ← 焦点指示器（最顶层，仅键盘焦点时可见，ZIndex=1）
+```
+
+**分层设计理由：**
+- **波纹层独立**：`WaveSpiritDecorator` 位于最底层，波纹动画在按钮边界外扩散时不会被主框架裁剪。
+- **阴影层独立**：`BoxShadow` 放在单独的 `Border#ShadowsFrame` 上，避免阴影与虚线边框（Dashed 类型）冲突。
+- **焦点层独立**：`Border#FocusVisual` 使用 `ZIndex=1` 和负 `Margin` 绘制在按钮外围，仅在 `:focus-visible` 时显示。
+
+> 注意：当 `ButtonType=Dashed` 时，主框架使用 `DashedBorder` 代替标准 `Border`，通过 `StrokeDashArray = [4, 2]` 绘制虚线边框效果。
+
+### 模板部件常量
+
+| 常量名 | 值 | 说明 |
+|---|---|---|
+| `ButtonThemeConstants.WaveSpiritPart` | `"PART_WaveSpirit"` | 波纹动画装饰器 |
+| `ButtonThemeConstants.RootLayoutPart` | `"PART_RootLayout"` | 根布局面板 |
+| `ButtonThemeConstants.LoadingIconPart` | `"PART_LoadingIcon"` | 加载旋转图标 |
+| `ButtonThemeConstants.ButtonIconPart` | `"PART_ButtonIcon"` | 按钮图标展示器 |
+| `ButtonThemeConstants.ContentPresenterPart` | `"PART_ContentPresenter"` | 内容展示器 |
+

docs/Desktop.Controls/Button/ButtonAPI.md

@@ -0,0 +1,145 @@
+# Button API 参考
+
+## 命名空间
+
+```csharp
+namespace AtomUI.Desktop.Controls;
+```
+
+AXAML 命名空间前缀：`atom`（`xmlns:atom="https://atomui.net"`）
+
+---
+
+## 枚举类型
+
+### ButtonType
+
+按钮类型枚举，定义按钮的视觉风格。
+
+| 值 | 说明 |
+|---|---|
+| `Default` | 默认按钮，白色背景 + 边框 |
+| `Dashed` | 虚线按钮，虚线边框 |
+| `Primary` | 主按钮，主色调填充背景 |
+| `Link` | 链接按钮，无边框无背景，文字呈链接色 |
+| `Text` | 文本按钮，无边框无背景，文字为默认色 |
+
+### ButtonShape
+
+按钮形状枚举。
+
+| 值 | 说明 |
+|---|---|
+| `Default` | 默认矩形（带圆角） |
+| `Circle` | 圆形按钮 |
+| `Round` | 胶囊形（圆角等于高度一半） |
+
+### SizeType（来自 `AtomUI.Controls`）
+
+尺寸类型枚举。
+
+| 值 | 说明 |
+|---|---|
+| `Small` | 小号 |
+| `Middle` | 中号（默认） |
+| `Large` | 大号 |
+
+---
+
+## 公共属性（StyledProperty）
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `ButtonType` | `ButtonType` | `ButtonType.Default` | 按钮类型，控制视觉风格 |
+| `Shape` | `ButtonShape` | `ButtonShape.Default` | 按钮形状 |
+| `IsDanger` | `bool` | `false` | 是否为危险按钮，启用后按钮使用红色系 |
+| `IsGhost` | `bool` | `false` | 幽灵模式，背景透明，文字和边框使用容器色/主题色 |
+| `IsLoading` | `bool` | `false` | 加载中状态，显示旋转加载图标并降低不透明度 |
+| `SizeType` | `SizeType` | `SizeType.Middle` | 按钮尺寸（共享属性，通过 `AddOwner` 注册） |
+| `Icon` | `PathIcon?` | `null` | 按钮图标，使用 Ant Design 图标集 |
+| `IsMotionEnabled` | `bool` | 跟随全局 Token | 是否启用过渡动画（共享属性） |
+| `IsWaveSpiritEnabled` | `bool` | 跟随全局 Token | 是否启用点击波纹效果（共享属性） |
+
+### 继承自 Avalonia.Controls.Button 的常用属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `Content` | `object?` | `null` | 按钮文本内容 |
+| `ContentTemplate` | `IDataTemplate?` | `null` | 内容模板 |
+| `Command` | `ICommand?` | `null` | 点击命令 |
+| `CommandParameter` | `object?` | `null` | 命令参数 |
+| `HorizontalAlignment` | `HorizontalAlignment` | `Left` | 水平对齐（设为 `Stretch` 实现 Block 模式） |
+| `HorizontalContentAlignment` | `HorizontalAlignment` | `Center` | 内容水平对齐 |
+| `VerticalContentAlignment` | `VerticalAlignment` | `Center` | 内容垂直对齐 |
+| `IsEnabled` | `bool` | `true` | 是否启用 |
+| `Foreground` | `IBrush?` | 由主题控制 | 前景色（文本颜色） |
+| `Background` | `IBrush?` | 由主题控制 | 背景色 |
+| `BorderBrush` | `IBrush?` | 由主题控制 | 边框颜色 |
+| `BorderThickness` | `Thickness` | 由 Token 控制 | 边框粗细 |
+| `CornerRadius` | `CornerRadius` | 由 Token 控制 | 圆角半径 |
+| `FontSize` | `double` | 由 Token 控制 | 字体大小 |
+| `Padding` | `Thickness` | 由 Token 控制 | 内间距 |
+| `Cursor` | `Cursor` | `Hand` | 鼠标光标 |
+
+---
+
+## 事件
+
+| 事件名 | 类型 | 说明 |
+|---|---|---|
+| `Click` | `EventHandler<RoutedEventArgs>` | 按钮点击事件（继承自 `Avalonia.Controls.Button`） |
+
+---
+
+## 伪类（Pseudo-Classes）
+
+Button 支持以下伪类，可在样式选择器中使用：
+
+| 伪类 | 常量 | 触发条件 |
+|---|---|---|
+| `:icononly` | `ButtonPseudoClass.IconOnly` | Icon 不为 null 且 Content 为 null |
+| `:loading` | `ButtonPseudoClass.Loading` | `IsLoading == true` |
+| `:danger` | `ButtonPseudoClass.IsDanger` | `IsDanger == true` |
+| `:default` | `ButtonPseudoClass.DefaultType` | `ButtonType == Default` |
+| `:dashed` | `ButtonPseudoClass.DashedType` | `ButtonType == Dashed` |
+| `:primary` | `ButtonPseudoClass.PrimaryType` | `ButtonType == Primary` |
+| `:link` | `ButtonPseudoClass.LinkType` | `ButtonType == Link` |
+| `:text` | `ButtonPseudoClass.TextType` | `ButtonType == Text` |
+
+### 继承的标准伪类
+
+| 伪类 | 触发条件 |
+|---|---|
+| `:pointerover` | 鼠标悬浮 |
+| `:pressed` | 按钮按下 |
+| `:disabled` | `IsEnabled == false` |
+| `:focus` | 获得焦点 |
+| `:focus-visible` | 通过键盘获得焦点（显示焦点框） |
+
+---
+
+## 实现的接口
+
+### ISizeTypeAware
+
+```csharp
+public SizeType SizeType { get; set; }
+```
+
+### IWaveSpiritAwareControl
+
+```csharp
+public bool IsWaveSpiritEnabled { get; set; }
+```
+
+### ICompactSpaceAware
+
+在 `Space.Compact` 容器中使用时自动调整圆角。Button 提供以下行为：
+
+- 根据在紧凑空间中的位置自动裁剪圆角
+- `ButtonType == Primary` 时始终处于活跃 ZIndex 层
+
+### IFormItemAware
+
+可作为 `FormItem` 的子控件参与表单验证流程。
+

docs/Desktop.Controls/Button/ButtonStyling.md

@@ -0,0 +1,273 @@
+# Button 自定义样式指南
+
+Button 的视觉表现通过 `ControlTheme` + Design Token 系统控制。以下介绍几种常见的自定义方式。
+
+---
+
+## 1. 使用属性直接控制
+
+最简单的方式是通过 Button 的公共属性来控制外观：
+
+```xml
+<!-- 不同类型 -->
+<atom:Button ButtonType="Primary">主按钮</atom:Button>
+<atom:Button ButtonType="Dashed">虚线按钮</atom:Button>
+<atom:Button ButtonType="Text">文本按钮</atom:Button>
+<atom:Button ButtonType="Link">链接按钮</atom:Button>
+
+<!-- 不同形状 -->
+<atom:Button ButtonType="Primary" Shape="Round">胶囊按钮</atom:Button>
+<atom:Button ButtonType="Primary" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}" />
+
+<!-- 不同尺寸 -->
+<atom:Button ButtonType="Primary" SizeType="Large">大按钮</atom:Button>
+<atom:Button ButtonType="Primary" SizeType="Small">小按钮</atom:Button>
+
+<!-- 危险 + 幽灵 -->
+<atom:Button ButtonType="Primary" IsDanger="True" IsGhost="True">危险幽灵</atom:Button>
+
+<!-- 带图标 -->
+<atom:Button ButtonType="Primary"
+             Icon="{antdicons:AntDesignIconProvider Kind=DownloadOutlined}">
+    Download
+</atom:Button>
+```
+
+> 📖 完整示例参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml`
+
+---
+
+## 2. 通过 Style 覆盖样式
+
+可以在 AXAML 中使用 `Style` 对 Button 进行全局或局部样式覆盖：
+
+### 全局统一间距
+
+```xml
+<Window.Styles>
+    <Style Selector="atom|Button">
+        <Setter Property="Margin" Value="5" />
+    </Style>
+</Window.Styles>
+```
+
+### 按类型定制颜色
+
+```xml
+<Style Selector="atom|Button[ButtonType=Primary]:not(:disabled)">
+    <Setter Property="Background" Value="#722ed1" />
+</Style>
+<Style Selector="atom|Button[ButtonType=Primary]:not(:disabled):pointerover">
+    <Setter Property="Background" Value="#9254de" />
+</Style>
+<Style Selector="atom|Button[ButtonType=Primary]:not(:disabled):pressed">
+    <Setter Property="Background" Value="#531dab" />
+</Style>
+```
+
+### 使用伪类选择器
+
+```xml
+<!-- 仅图标按钮添加额外内边距 -->
+<Style Selector="atom|Button:icononly">
+    <Setter Property="Padding" Value="8" />
+</Style>
+
+<!-- 加载中时隐藏特定内容 -->
+<Style Selector="atom|Button:loading">
+    <Setter Property="Opacity" Value="0.65" />
+</Style>
+
+<!-- 危险按钮的自定义样式 -->
+<Style Selector="atom|Button:danger:not(:disabled)">
+    <Setter Property="FontWeight" Value="Bold" />
+</Style>
+```
+
+### 通过属性选择器定制形状
+
+```xml
+<!-- 所有圆形按钮的额外样式 -->
+<Style Selector="atom|Button[Shape=Circle]">
+    <Setter Property="MinWidth" Value="40" />
+</Style>
+
+<!-- 所有大号按钮使用粗体 -->
+<Style Selector="atom|Button[SizeType=Large]">
+    <Setter Property="FontWeight" Value="SemiBold" />
+</Style>
+```
+
+---
+
+## 3. 通过 ControlTheme 完全替换主题
+
+如果需要彻底替换 Button 的模板和样式，可以定义自定义 `ControlTheme`：
+
+```xml
+<ControlTheme x:Key="MyCustomButton" TargetType="atom:Button">
+    <Setter Property="Template">
+        <ControlTemplate>
+            <Border Background="{TemplateBinding Background}"
+                    CornerRadius="{TemplateBinding CornerRadius}"
+                    Padding="{TemplateBinding Padding}">
+                <ContentPresenter Content="{TemplateBinding Content}"
+                                  HorizontalAlignment="Center"
+                                  VerticalAlignment="Center" />
+            </Border>
+        </ControlTemplate>
+    </Setter>
+    <!-- 自定义样式... -->
+</ControlTheme>
+
+<!-- 使用 -->
+<atom:Button Theme="{StaticResource MyCustomButton}">自定义按钮</atom:Button>
+```
+
+> ⚠️ 注意：完全替换 ControlTheme 将丢失内置的波纹效果、加载图标等功能。建议优先使用 Style 覆盖。
+
+---
+
+## 4. Block 按钮（撑满父容器）
+
+Ant Design 的 `block` 属性在 AtomUI 中通过 Avalonia 原生布局属性实现：
+
+```xml
+<StackPanel>
+    <atom:Button ButtonType="Primary" HorizontalAlignment="Stretch">
+        Primary Block
+    </atom:Button>
+    <atom:Button ButtonType="Default" HorizontalAlignment="Stretch">
+        Default Block
+    </atom:Button>
+    <atom:Button ButtonType="Dashed" HorizontalAlignment="Stretch">
+        Dashed Block
+    </atom:Button>
+</StackPanel>
+```
+
+> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` 中 "Block Button" 示例。
+
+---
+
+## 5. 加载状态交互示例
+
+```xml
+<atom:Button ButtonType="Primary"
+             Click="HandleLoadingBtnClick"
+             Icon="{antdicons:AntDesignIconProvider Kind=PoweroffOutlined}">
+    Click me!
+</atom:Button>
+```
+
+```csharp
+public void HandleLoadingBtnClick(object? sender, RoutedEventArgs args)
+{
+    if (sender is Button button)
+    {
+        button.IsLoading = true;
+        Dispatcher.UIThread.InvokeAsync(async () =>
+        {
+            await Task.Delay(TimeSpan.FromSeconds(3));
+            button.IsLoading = false;
+        });
+    }
+}
+```
+
+> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml.cs`
+
+---
+
+## 6. 幽灵按钮（Ghost）使用场景
+
+幽灵按钮常用于有色背景上：
+
+```xml
+<Border Background="rgb(190, 200, 200)" Padding="10">
+    <WrapPanel>
+        <atom:Button ButtonType="Primary" IsGhost="True">Primary</atom:Button>
+        <atom:Button ButtonType="Default" IsGhost="True">Default</atom:Button>
+        <atom:Button ButtonType="Dashed" IsGhost="True">Dashed</atom:Button>
+        <atom:Button ButtonType="Primary" IsDanger="True" IsGhost="True">Danger</atom:Button>
+    </WrapPanel>
+</Border>
+```
+
+> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` 中 "Ghost Button" 示例。
+
+---
+
+## 7. 控制动画行为
+
+```xml
+<!-- 禁用过渡动画 -->
+<atom:Button ButtonType="Primary" IsMotionEnabled="False">无动画</atom:Button>
+
+<!-- 禁用点击波纹 -->
+<atom:Button ButtonType="Primary" IsWaveSpiritEnabled="False">无波纹</atom:Button>
+```
+
+---
+
+## 样式选择器速查
+
+> 说明：Avalonia 样式选择器中使用 `atom|Button` 语法引用 `atom` XML 命名空间下的 `Button` 类型，其中 `|` 是命名空间分隔符。
+
+### 按类型选择
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button` | 匹配所有 AtomUI Button 实例，用于设置全局通用样式（如统一 Margin、Cursor 等） |
+| `atom\|Button[ButtonType=Primary]` | 匹配主按钮（实心填充主色调背景），可定制主按钮的背景色、文字色等 |
+| `atom\|Button[ButtonType=Default]` | 匹配默认按钮（白色背景 + 实线边框），最常见的次级操作按钮 |
+| `atom\|Button[ButtonType=Dashed]` | 匹配虚线按钮（虚线边框），通常用于「添加」类操作 |
+| `atom\|Button[ButtonType=Text]` | 匹配文本按钮（无边框无背景），适用于最次级的内联操作 |
+| `atom\|Button[ButtonType=Link]` | 匹配链接按钮（文字呈链接色，无边框），用于导航类操作 |
+
+### 按形状选择
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button[Shape=Circle]` | 匹配圆形按钮（宽 = 高，完全圆角），通常仅含图标 |
+| `atom\|Button[Shape=Round]` | 匹配胶囊形按钮（两端完全圆角，宽度 ≥ 高度 × 1.5） |
+
+### 按尺寸选择
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button[SizeType=Large]` | 匹配大号按钮（高度 = `ControlHeightLG`，字号 = `ContentFontSizeLG`） |
+| `atom\|Button[SizeType=Middle]` | 匹配中号按钮（默认尺寸，通常无需单独匹配） |
+| `atom\|Button[SizeType=Small]` | 匹配小号按钮（高度 = `ControlHeightSM`，字号 = `ContentFontSizeSM`） |
+
+### 按状态属性选择
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button[IsDanger=True]` | 匹配危险按钮（红色系样式），可结合类型如 `atom\|Button[ButtonType=Primary][IsDanger=True]` |
+| `atom\|Button[IsGhost=True]` | 匹配幽灵按钮（背景透明），常用于有色背景场景 |
+
+### 按伪类选择
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button:icononly` | 匹配仅含图标的按钮（`Icon` 不为 null 且 `Content` 为 null），可用于调整仅图标模式下的内间距和图标尺寸 |
+| `atom\|Button:loading` | 匹配处于加载中状态的按钮（`IsLoading == true`），此时加载旋转图标可见、原图标隐藏 |
+| `atom\|Button:danger` | 匹配标记为危险的按钮（`IsDanger == true`），与 `[IsDanger=True]` 属性选择器等效 |
+| `atom\|Button:pointerover` | 匹配鼠标悬浮状态，用于定制 hover 时的背景色、文字色、边框色变化 |
+| `atom\|Button:pressed` | 匹配按下状态（鼠标按住未释放），用于定制 active 时的视觉反馈 |
+| `atom\|Button:disabled` | 匹配禁用状态（`IsEnabled == false`），此时按钮不响应交互，使用灰色调 |
+| `atom\|Button:focus-visible` | 匹配通过键盘（Tab 键）获得焦点的状态，显示外围焦点指示框 |
+| `atom\|Button:focus` | 匹配获得焦点的状态（包含鼠标点击和键盘），通常优先使用 `:focus-visible` |
+
+### 组合选择器示例
+
+| 选择器 | 说明 |
+|---|---|
+| `atom\|Button[ButtonType=Primary]:not(:disabled)` | 非禁用状态的主按钮，用于定制可交互态的样式 |
+| `atom\|Button[ButtonType=Default]:danger:pointerover` | 悬浮状态的危险默认按钮 |
+| `atom\|Button[SizeType=Large]:icononly` | 大号仅图标按钮 |
+| `atom\|Button /template/ Border#Frame` | 访问按钮模板内名为 `Frame` 的 Border 部件 |
+| `atom\|Button /template/ atom\|IconPresenter#PART_ButtonIcon` | 访问模板内的图标展示器部件 |
+

docs/Desktop.Controls/Button/ButtonToken.md

@@ -0,0 +1,180 @@
+# Button Design Token
+
+Button 控件使用 `ButtonToken`（Token ID: `"Button"`）作为组件级 Design Token，所有视觉属性均从全局 `SharedToken` 派生，不硬编码任何具体值。
+
+---
+
+## Token 资源访问方式
+
+在 AXAML 中使用组件级 Token：
+
+```xml
+{atom:ButtonTokenResource PrimaryColor}
+{atom:ButtonTokenResource DefaultBg}
+{atom:ButtonTokenResource Padding}
+```
+
+在 AXAML 中使用全局共享 Token：
+
+```xml
+{atom:SharedTokenResource ColorPrimary}
+{atom:SharedTokenResource ControlHeight}
+{atom:SharedTokenResource BorderThickness}
+```
+
+---
+
+## 组件级 Token 一览
+
+以下是 `ButtonToken` 定义的全部组件级 Token，按功能分组说明。
+
+### 颜色 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `PrimaryColor` | `Color` | `SharedToken.ColorTextLightSolid` | 主按钮文本颜色（通常为白色） |
+| `DefaultColor` | `Color` | `SharedToken.ColorText` | 默认按钮文本颜色 |
+| `DefaultBg` | `Color` | `SharedToken.ColorBgContainer` | 默认按钮背景色 |
+| `DefaultBorderColor` | `Color` | `SharedToken.ColorBorder` | 默认按钮边框颜色 |
+| `DefaultBorderColorDisabled` | `Color` | `SharedToken.ColorBorder` | 禁用态默认边框颜色 |
+| `DangerColor` | `Color` | `SharedToken.ColorTextLightSolid` | 危险按钮文本颜色 |
+| `BorderColorDisabled` | `Color` | `SharedToken.ColorBorder` | 禁用态边框颜色 |
+| `DefaultGhostColor` | `Color` | `SharedToken.ColorBgContainer` | 默认幽灵按钮文本颜色 |
+| `GhostBg` | `Color` | `Colors.Transparent` | 幽灵按钮背景色（透明） |
+| `DefaultGhostBorderColor` | `Color` | `SharedToken.ColorBgContainer` | 默认幽灵按钮边框颜色 |
+| `GroupBorderColor` | `Color` | `SharedToken.ColorPrimaryHover` | 按钮组边框颜色 |
+| `SolidTextColor` | `Color` | 基于 `SharedToken.ColorBgSolid` 亮度计算 | 实心按钮文本色（自动适配深浅背景） |
+| `TextTextColor` | `Color` | `SharedToken.ColorText` | 文本按钮文本颜色 |
+| `TextTextHoverColor` | `Color` | `SharedToken.ColorText` | 文本按钮悬浮文本颜色 |
+| `TextTextActiveColor` | `Color` | `SharedToken.ColorText` | 文本按钮激活文本颜色 |
+
+### 悬浮/激活态颜色 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `DefaultHoverBg` | `Color` | `SharedToken.ColorBgContainer` | 默认按钮悬浮背景色 |
+| `DefaultHoverColor` | `Color` | `SharedToken.ColorPrimaryHover` | 默认按钮悬浮文本颜色 |
+| `DefaultHoverBorderColor` | `Color` | `SharedToken.ColorPrimaryHover` | 默认按钮悬浮边框颜色 |
+| `DefaultActiveBg` | `Color` | `SharedToken.ColorBgContainer` | 默认按钮激活背景色 |
+| `DefaultActiveColor` | `Color` | `SharedToken.ColorPrimaryActive` | 默认按钮激活文本颜色 |
+| `DefaultActiveBorderColor` | `Color` | `SharedToken.ColorPrimaryActive` | 默认按钮激活边框颜色 |
+| `LinkHoverBg` | `Color` | `Colors.Transparent` | 链接按钮悬浮背景色 |
+| `TextHoverBg` | `Color` | `SharedToken.ColorBgTextHover` | 文本按钮悬浮背景色 |
+
+### 阴影 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `DefaultShadow` | `BoxShadows` | 基于 `SharedToken.ColorControlOutline` | 默认按钮阴影 |
+| `PrimaryShadow` | `BoxShadows` | 基于 `SharedToken.ColorControlOutline` | 主按钮阴影 |
+| `DangerShadow` | `BoxShadows` | 基于 `SharedToken.ColorErrorOutline` | 危险按钮阴影 |
+
+### 内间距 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `Padding` | `Thickness` | 基于 `SharedToken.PaddingContentHorizontal`、`SharedToken.ControlHeight` | 中号按钮内间距 |
+| `PaddingLG` | `Thickness` | 基于 `SharedToken.PaddingContentHorizontal`、`SharedToken.ControlHeightLG` | 大号按钮内间距 |
+| `PaddingSM` | `Thickness` | 基于 `SharedToken.ControlHeightSM` | 小号按钮内间距 |
+| `CirclePadding` | `Thickness` | `PaddingSM.Left / 2` | 圆形按钮内间距 |
+| `IconOnyPadding` | `Thickness` | 基于 `SharedToken.ControlHeight` | 仅图标按钮中号内间距 |
+| `IconOnyPaddingLG` | `Thickness` | 基于 `SharedToken.ControlHeightLG` | 仅图标按钮大号内间距 |
+| `IconOnyPaddingSM` | `Thickness` | 基于 `SharedToken.ControlHeightSM` | 仅图标按钮小号内间距 |
+
+### 图标 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `IconSize` | `double` | `SharedToken.IconSize` | 中号按钮图标尺寸 |
+| `IconSizeLG` | `double` | `SharedToken.IconSize` | 大号按钮图标尺寸 |
+| `IconSizeSM` | `double` | `SharedToken.IconSizeSM` | 小号按钮图标尺寸 |
+| `OnlyIconSize` | `double` | `SharedToken.IconSizeLG` | 仅图标中号按钮图标尺寸 |
+| `OnlyIconSizeLG` | `double` | `SharedToken.IconSizeLG` | 仅图标大号按钮图标尺寸 |
+| `OnlyIconSizeSM` | `double` | `SharedToken.IconSize` | 仅图标小号按钮图标尺寸 |
+| `IconMargin` | `Thickness` | `SharedToken.UniformlyPaddingXXS` | 图标与文本之间的间距 |
+
+### 字体 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `FontWeight` | `double` | 固定 `400` | 按钮文字字重 |
+| `ContentFontSize` | `double` | `SharedToken.FontSize` | 中号按钮字体大小 |
+| `ContentFontSizeLG` | `double` | `SharedToken.FontSizeLG` | 大号按钮字体大小 |
+| `ContentFontSizeSM` | `double` | `SharedToken.FontSize` | 小号按钮字体大小 |
+| `ContentLineHeight` | `double` | 基于 `ContentFontSize` 计算 | 中号按钮行高 |
+| `ContentLineHeightLG` | `double` | 基于 `ContentFontSizeLG` 计算 | 大号按钮行高 |
+| `ContentLineHeightSM` | `double` | 基于 `ContentFontSizeSM` 计算 | 小号按钮行高 |
+
+### 额外区域 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `ExtraContentItemSpacing` | `double` | `SharedToken.UniformlyMarginXXS / 2` | 额外内容区域子项间距 |
+| `ExtraContentMargin` | `Thickness` | `Padding.Left / 2` | 中号额外内容区域外边距 |
+| `ExtraContentMarginLG` | `Thickness` | `PaddingLG.Left / 2` | 大号额外内容区域外边距 |
+| `ExtraContentMarginSM` | `Thickness` | `PaddingSM.Left / 2` | 小号额外内容区域外边距 |
+
+### 其他 Token
+
+| Token 名 | 类型 | 来源 | 说明 |
+|---|---|---|---|
+| `GutterToFlyout` | `double` | `SharedToken.UniformlyMarginXXS` | 下拉菜单与按钮之间的间距 |
+
+---
+
+## 主题中使用的全局 SharedToken
+
+除组件级 Token 外，Button 的 ControlTheme 还直接引用了以下全局 `SharedToken`：
+
+| Token 资源键 | 使用场景 |
+|---|---|
+| `BorderThickness` | 按钮默认边框厚度 |
+| `EnableMotion` | 全局动画开关 |
+| `EnableWaveSpirit` | 全局波纹开关 |
+| `ControlHeight` / `ControlHeightSM` / `ControlHeightLG` | 按钮高度（中/小/大） |
+| `BorderRadius` / `BorderRadiusSM` / `BorderRadiusLG` | 圆角半径（中/小/大） |
+| `ColorPrimary` / `ColorPrimaryHover` / `ColorPrimaryActive` | 主色调及其交互态 |
+| `ColorError` / `ColorErrorHover` / `ColorErrorActive` / `ColorErrorBorderHover` | 错误/危险色系 |
+| `ColorErrorBgHover` / `ColorErrorBgActive` | 错误背景色（用于 Text 类型危险按钮） |
+| `ColorErrorOutline` | 危险阴影颜色 |
+| `ColorLink` / `ColorLinkHover` / `ColorLinkActive` | 链接色系 |
+| `ColorText` / `ColorTextSecondary` / `ColorTextDisabled` / `ColorTextLightSolid` | 文本色系 |
+| `ColorBgContainer` / `ColorBgContainerDisabled` | 容器背景色 |
+| `ColorBgTextHover` / `ColorBgTextActive` | 文本背景交互色 |
+| `ColorBorder` | 边框颜色 |
+| `ColorControlOutline` | 控件外轮廓颜色 |
+| `ColorFocusBorder` | 焦点边框颜色 |
+| `FocusVisualBorderThickness` | 焦点指示器边框厚度 |
+| `OpacityLoading` | 加载态不透明度 |
+| `IconSize` / `IconSizeSM` / `IconSizeLG` | 全局图标尺寸 |
+
+---
+
+## Token 对外观的具体影响
+
+### 按钮类型与 Token 映射
+
+| 按钮类型 | 正常态 | 悬浮态 | 按下态 | 禁用态 |
+|---|---|---|---|---|
+| **Default** | `DefaultColor` / `DefaultBg` / `DefaultBorderColor` | `DefaultHoverColor` / `DefaultHoverBorderColor` | `DefaultActiveColor` / `DefaultActiveBorderColor` | `ColorTextDisabled` / `ColorBgContainerDisabled` |
+| **Primary** | `PrimaryColor` / `ColorPrimary` | - / `ColorPrimaryHover` | - / `ColorPrimaryActive` | `ColorTextDisabled` / `ColorBgContainerDisabled` |
+| **Dashed** | `DefaultColor` / `DefaultBg` / `DefaultBorderColor` | `DefaultHoverColor` / `DefaultHoverBorderColor` | `DefaultActiveColor` / `DefaultActiveBorderColor` | `ColorTextDisabled` / `ColorBgContainerDisabled` |
+| **Link** | `ColorLink` / 透明 | `ColorLinkHover` | `ColorLinkActive` | `ColorTextDisabled` / 透明 |
+| **Text** | `DefaultColor` / 透明 | - / `TextHoverBg` | - / `ColorBgTextActive` | `ColorTextDisabled` / 透明 |
+
+### 危险态下的 Token 覆盖
+
+当 `IsDanger=True` 时，上述色系会被替换为 Error 色系（`ColorError` / `ColorErrorHover` / `ColorErrorActive`），阴影替换为 `DangerShadow`。
+
+### 幽灵态下的 Token 覆盖
+
+当 `IsGhost=True` 时，背景变为透明，文字/边框使用对应类型的主色调（如 Primary 幽灵使用 `ColorPrimary`，Default 幽灵使用 `ColorTextLightSolid`）。
+
+### 尺寸与 Token 映射
+
+| 尺寸 | 高度 | 内间距 | 字号 | 圆角 | 图标大小 |
+|---|---|---|---|---|---|
+| `Large` | `ControlHeightLG` | `PaddingLG` | `ContentFontSizeLG` | `BorderRadiusLG` | `IconSizeLG` |
+| `Middle` | `ControlHeight` | `Padding` | `ContentFontSize` | `BorderRadius` | `IconSize` |
+| `Small` | `ControlHeightSM` | `PaddingSM` | `ContentFontSizeSM` | `BorderRadiusSM` | `IconSizeSM` |
+

docs/Desktop.Controls/Button/ButtonUsage.md

@@ -0,0 +1,497 @@
+# Button 使用文档
+
+本文档介绍 AtomUI Button 控件的各种使用方式，示例代码摘自 Gallery 演示程序。
+
+> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml`
+
+---
+
+## 前置准备
+
+在 AXAML 中使用 Button，需要引入以下命名空间：
+
+```xml
+xmlns:atom="https://atomui.net"
+xmlns:antdicons="https://atomui.net/icons/antdesign"
+```
+
+在 C# 代码中引入：
+
+```csharp
+using AtomUI.Desktop.Controls;   // Button 控件
+using AtomUI.Controls;            // SizeType 等共享类型
+```
+
+---
+
+## 1. 按钮类型
+
+AtomUI 提供五种按钮类型，通过 `ButtonType` 属性设置。不设置时默认为 `Default`。
+
+```xml
+<WrapPanel Orientation="Horizontal">
+    <atom:Button ButtonType="Primary">Primary Button</atom:Button>
+    <atom:Button>Default Button</atom:Button>
+    <atom:Button ButtonType="Dashed">Dashed</atom:Button>
+    <atom:Button ButtonType="Text">Text Button</atom:Button>
+    <atom:Button ButtonType="Link">Link Button</atom:Button>
+</WrapPanel>
+```
+
+**使用场景指引**：
+- 一个操作区域只放一个 **Primary** 按钮，引导用户注意力
+- 多个并列操作使用 **Default** 按钮
+- 添加类操作使用 **Dashed** 按钮
+- 内联次级操作使用 **Text** 按钮
+- 导航跳转使用 **Link** 按钮
+
+---
+
+## 2. 按钮形状
+
+通过 `Shape` 属性设置按钮形状，支持默认矩形、圆形和胶囊形。
+
+```xml
+<!-- 默认矩形（带圆角） -->
+<atom:Button ButtonType="Primary">Primary</atom:Button>
+<atom:Button>Default</atom:Button>
+
+<!-- 胶囊形（Round） -->
+<atom:Button ButtonType="Primary" Shape="Round">Primary</atom:Button>
+<atom:Button Shape="Round">Default</atom:Button>
+
+<!-- 圆形（Circle）— 通常只放图标或极短文字 -->
+<atom:Button ButtonType="Primary" Shape="Circle">AA</atom:Button>
+<atom:Button Shape="Circle">AA</atom:Button>
+```
+
+**提示**：圆形按钮会强制 `宽度 = 高度`，最适合只放一个图标的场景。
+
+---
+
+## 3. 按钮尺寸
+
+通过 `SizeType` 属性设置尺寸，支持 `Large`、`Middle`（默认）、`Small` 三种。
+
+```xml
+<atom:Button ButtonType="Primary" SizeType="Large">Large</atom:Button>
+<atom:Button ButtonType="Primary" SizeType="Middle">Default</atom:Button>
+<atom:Button ButtonType="Primary" SizeType="Small">Small</atom:Button>
+```
+
+尺寸也支持数据绑定，可在运行时动态切换：
+
+```xml
+<!-- AXAML：绑定 ViewModel 的 ButtonSizeType 属性 -->
+<atom:Button ButtonType="Primary" SizeType="{Binding ButtonSizeType}">Primary</atom:Button>
+<atom:Button ButtonType="Dashed" SizeType="{Binding ButtonSizeType}">Dashed</atom:Button>
+<atom:Button ButtonType="Default" SizeType="{Binding ButtonSizeType}">Default</atom:Button>
+<atom:Button ButtonType="Link" SizeType="{Binding ButtonSizeType}">Link</atom:Button>
+```
+
+```csharp
+// ViewModel
+public class ButtonViewModel : ReactiveObject
+{
+    private SizeType _buttonSizeType;
+    public SizeType ButtonSizeType
+    {
+        get => _buttonSizeType;
+        set => this.RaiseAndSetIfChanged(ref _buttonSizeType, value);
+    }
+}
+```
+
+尺寸与形状和图标组合使用：
+
+```xml
+<!-- 不同尺寸的纯图标按钮 -->
+<atom:Button ButtonType="Primary" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=DownloadOutlined}"
+             SizeType="Large" />
+<atom:Button ButtonType="Primary" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=DownloadOutlined}"
+             SizeType="Middle" />
+<atom:Button ButtonType="Primary" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=DownloadOutlined}"
+             SizeType="Small" />
+
+<!-- 不同尺寸的图标 + 文字按钮 -->
+<atom:Button ButtonType="Primary" Shape="Round"
+             Icon="{antdicons:AntDesignIconProvider Kind=DownloadOutlined}"
+             SizeType="Large">
+    Download
+</atom:Button>
+```
+
+---
+
+## 4. 图标按钮
+
+通过 `Icon` 属性设置按钮图标，图标使用 Ant Design 图标集提供：
+
+```xml
+<!-- 纯图标按钮（圆形） -->
+<atom:Button ButtonType="Primary" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}" />
+
+<!-- 图标 + 文字按钮 -->
+<atom:Button ButtonType="Primary" Shape="Round"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+
+<!-- 不同类型均支持图标 -->
+<atom:Button ButtonType="Default" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}" />
+<atom:Button ButtonType="Default" Shape="Round"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+<atom:Button ButtonType="Text"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+<atom:Button ButtonType="Link"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+<atom:Button ButtonType="Dashed" Shape="Circle"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}" />
+```
+
+**图标 + 危险样式组合**：
+
+```xml
+<atom:Button ButtonType="Primary" IsDanger="True"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+<atom:Button ButtonType="Default" Shape="Round" IsDanger="True"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+    Search
+</atom:Button>
+<atom:Button ButtonType="Dashed" Shape="Circle" IsDanger="True"
+             Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}" />
+```
+
+---
+
+## 5. 加载中状态
+
+通过设置 `IsLoading` 属性控制按钮加载状态。加载中时按钮显示旋转图标，不透明度降低。
+
+### 静态加载状态
+
+```xml
+<atom:Button ButtonType="Primary" IsLoading="True">Loading</atom:Button>
+<atom:Button ButtonType="Primary" SizeType="Small" IsLoading="True">Loading</atom:Button>
+
+<!-- 纯图标按钮的加载态 -->
+<atom:Button ButtonType="Primary" IsLoading="True"
+             Icon="{antdicons:AntDesignIconProvider Kind=PoweroffOutlined}" />
+```
+
+### 点击后动态进入加载态
+
+这是最常见的使用场景——点击按钮发起异步请求，完成后恢复：
+
+```xml
+<atom:Button ButtonType="Primary"
+             Click="HandleLoadingBtnClick">
+    Click me!
+</atom:Button>
+
+<atom:Button ButtonType="Primary"
+             Click="HandleLoadingBtnClick"
+             Icon="{antdicons:AntDesignIconProvider Kind=PoweroffOutlined}">
+    Click me!
+</atom:Button>
+
+<!-- 纯图标按钮也支持 -->
+<atom:Button ButtonType="Primary"
+             Click="HandleLoadingBtnClick"
+             Icon="{antdicons:AntDesignIconProvider Kind=PoweroffOutlined}" />
+```
+
+```csharp
+// Code-behind
+public void HandleLoadingBtnClick(object? sender, RoutedEventArgs args)
+{
+    if (sender is Button button)
+    {
+        button.IsLoading = true;
+        Dispatcher.UIThread.InvokeAsync(async () =>
+        {
+            await Task.Delay(TimeSpan.FromSeconds(3)); // 模拟异步操作
+            button.IsLoading = false;
+        });
+    }
+}
+```
+
+---
+
+## 6. 危险按钮
+
+通过 `IsDanger="True"` 标记危险操作，所有按钮类型均支持：
+
+```xml
+<atom:Button ButtonType="Primary" IsDanger="True">Primary</atom:Button>
+<atom:Button ButtonType="Default" IsDanger="True">Default</atom:Button>
+<atom:Button ButtonType="Dashed" IsDanger="True">Dashed</atom:Button>
+<atom:Button ButtonType="Text" IsDanger="True">Text</atom:Button>
+<atom:Button ButtonType="Link" IsDanger="True">Link</atom:Button>
+```
+
+**使用场景**：删除、移动、修改权限等不可逆操作，通常需配合二次确认弹窗。
+
+---
+
+## 7. 幽灵按钮
+
+通过 `IsGhost="True"` 使按钮背景透明，适合放置在有色背景上：
+
+```xml
+<Border Background="rgb(190, 200, 200)" Padding="10">
+    <StackPanel Orientation="Vertical">
+        <!-- 纯文字幽灵按钮 -->
+        <WrapPanel>
+            <atom:Button ButtonType="Primary" IsGhost="True">Primary</atom:Button>
+            <atom:Button ButtonType="Default" IsGhost="True">Default</atom:Button>
+            <atom:Button ButtonType="Dashed" IsGhost="True">Dashed</atom:Button>
+            <atom:Button ButtonType="Text" IsGhost="True">Text</atom:Button>
+            <atom:Button ButtonType="Link" IsGhost="True">Link</atom:Button>
+            <atom:Button ButtonType="Primary" IsDanger="True" IsGhost="True">
+                Danger
+            </atom:Button>
+        </WrapPanel>
+
+        <!-- 带图标的幽灵按钮 -->
+        <WrapPanel>
+            <atom:Button ButtonType="Primary" IsGhost="True"
+                         Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+                Primary
+            </atom:Button>
+            <atom:Button ButtonType="Default" IsGhost="True"
+                         Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+                Default
+            </atom:Button>
+            <atom:Button ButtonType="Primary" IsDanger="True" IsGhost="True"
+                         Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+                Danger
+            </atom:Button>
+        </WrapPanel>
+    </StackPanel>
+</Border>
+```
+
+---
+
+## 8. Block 按钮
+
+Ant Design 的 `block` 属性在 AtomUI 中通过 Avalonia 原生布局属性 `HorizontalAlignment="Stretch"` 实现，使按钮撑满父容器宽度：
+
+```xml
+<StackPanel Orientation="Vertical" Margin="10">
+    <atom:Button ButtonType="Primary" HorizontalAlignment="Stretch">
+        Primary
+    </atom:Button>
+    <atom:Button ButtonType="Default" HorizontalAlignment="Stretch">
+        Default
+    </atom:Button>
+    <atom:Button ButtonType="Dashed" HorizontalAlignment="Stretch">
+        Dashed
+    </atom:Button>
+    <atom:Button ButtonType="Text" HorizontalAlignment="Stretch">
+        Text
+    </atom:Button>
+    <atom:Button ButtonType="Link" HorizontalAlignment="Stretch">
+        Link
+    </atom:Button>
+</StackPanel>
+```
+
+---
+
+## 9. 禁用状态
+
+通过 `IsEnabled="False"` 禁用按钮，所有类型均支持：
+
+```xml
+<!-- 正常 vs 禁用对比 -->
+<StackPanel Orientation="Horizontal">
+    <atom:Button ButtonType="Primary"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Primary
+    </atom:Button>
+    <atom:Button ButtonType="Primary" IsEnabled="False"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Primary(disabled)
+    </atom:Button>
+</StackPanel>
+
+<StackPanel Orientation="Horizontal">
+    <atom:Button ButtonType="Default"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Default
+    </atom:Button>
+    <atom:Button ButtonType="Default" IsEnabled="False"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Default(disabled)
+    </atom:Button>
+</StackPanel>
+
+<!-- 危险按钮的禁用 -->
+<StackPanel Orientation="Horizontal">
+    <atom:Button ButtonType="Primary" IsDanger="True"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Danger Primary
+    </atom:Button>
+    <atom:Button ButtonType="Primary" IsDanger="True" IsEnabled="False"
+                 Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+        Danger Primary(disabled)
+    </atom:Button>
+</StackPanel>
+
+<!-- 幽灵按钮的禁用 -->
+<Border Background="rgb(190, 200, 200)">
+    <StackPanel Orientation="Horizontal">
+        <atom:Button IsGhost="True"
+                     Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+            Ghost
+        </atom:Button>
+        <atom:Button IsGhost="True" IsEnabled="False"
+                     Icon="{antdicons:AntDesignIconProvider Kind=SearchOutlined}">
+            Ghost(disabled)
+        </atom:Button>
+    </StackPanel>
+</Border>
+```
+
+---
+
+## 10. MVVM 命令绑定
+
+Button 继承自 Avalonia 的 `Button`，完整支持 `Command` / `CommandParameter` 绑定模式：
+
+```xml
+<atom:Button ButtonType="Primary"
+             Command="{Binding SaveCommand}">
+    Save
+</atom:Button>
+
+<atom:Button ButtonType="Primary" IsDanger="True"
+             Command="{Binding DeleteCommand}"
+             CommandParameter="{Binding SelectedItem}">
+    Delete
+</atom:Button>
+```
+
+```csharp
+// ViewModel（使用 ReactiveUI）
+[Reactive]
+public ReactiveCommand<Unit, Unit> SaveCommand { get; }
+
+public MyViewModel()
+{
+    var canSave = this.WhenAnyValue(x => x.IsValid);
+    SaveCommand = ReactiveCommand.CreateFromTask(
+        async () => { await _repository.SaveAsync(); },
+        canSave);
+}
+```
+
+当 `CanExecute` 返回 `false` 时，按钮会**自动禁用**（灰色调 + 不可点击），无需手动管理 `IsEnabled`。
+
+---
+
+## 11. 键盘快捷键
+
+利用继承自 Avalonia Button 的 `HotKey`、`IsDefault`、`IsCancel` 属性：
+
+```xml
+<!-- Enter 键触发确认 -->
+<atom:Button ButtonType="Primary" IsDefault="True"
+             Command="{Binding ConfirmCommand}">
+    OK
+</atom:Button>
+
+<!-- Escape 键触发取消 -->
+<atom:Button IsCancel="True"
+             Command="{Binding CancelCommand}">
+    Cancel
+</atom:Button>
+
+<!-- 自定义快捷键 -->
+<atom:Button ButtonType="Primary"
+             HotKey="Ctrl+S"
+             Command="{Binding SaveCommand}">
+    Save (Ctrl+S)
+</atom:Button>
+```
+
+---
+
+## 12. 控制动画行为
+
+```xml
+<!-- 禁用过渡动画（背景色、前景色不再渐变过渡） -->
+<atom:Button ButtonType="Primary" IsMotionEnabled="False">
+    No Animation
+</atom:Button>
+
+<!-- 禁用点击波纹效果 -->
+<atom:Button ButtonType="Primary" IsWaveSpiritEnabled="False">
+    No Wave
+</atom:Button>
+```
+
+---
+
+## 常见组合模式
+
+### 操作栏（主 + 次按钮）
+
+```xml
+<StackPanel Orientation="Horizontal" Spacing="8">
+    <atom:Button ButtonType="Primary">Submit</atom:Button>
+    <atom:Button>Cancel</atom:Button>
+</StackPanel>
+```
+
+### 确认/取消对话框
+
+```xml
+<StackPanel Orientation="Horizontal" Spacing="8"
+            HorizontalAlignment="Right">
+    <atom:Button IsCancel="True">Cancel</atom:Button>
+    <atom:Button ButtonType="Primary" IsDefault="True">OK</atom:Button>
+</StackPanel>
+```
+
+### 危险操作确认
+
+```xml
+<StackPanel Orientation="Horizontal" Spacing="8">
+    <atom:Button>Cancel</atom:Button>
+    <atom:Button ButtonType="Primary" IsDanger="True"
+                 Icon="{antdicons:AntDesignIconProvider Kind=DeleteOutlined}">
+        Delete
+    </atom:Button>
+</StackPanel>
+```
+
+### 工具栏（纯图标按钮组）
+
+```xml
+<StackPanel Orientation="Horizontal" Spacing="4">
+    <atom:Button ButtonType="Text"
+                 Icon="{antdicons:AntDesignIconProvider Kind=BoldOutlined}" />
+    <atom:Button ButtonType="Text"
+                 Icon="{antdicons:AntDesignIconProvider Kind=ItalicOutlined}" />
+    <atom:Button ButtonType="Text"
+                 Icon="{antdicons:AntDesignIconProvider Kind=UnderlineOutlined}" />
+</StackPanel>
+```
+