From ad8b7a4185f4530ff3c703bcaffea1e4df6380bb Mon Sep 17 00:00:00 2001 From: chinboy Date: Sun, 12 Apr 2026 17:06:00 +0800 Subject: [PATCH] docs(Button): add comprehensive design, API, styling, token and usage documentation --- docs/Desktop.Controls/Button/Button.md | 256 +++++++++ docs/Desktop.Controls/Button/ButtonAPI.md | 145 +++++ docs/Desktop.Controls/Button/ButtonStyling.md | 273 ++++++++++ docs/Desktop.Controls/Button/ButtonToken.md | 180 +++++++ docs/Desktop.Controls/Button/ButtonUsage.md | 497 ++++++++++++++++++ 5 files changed, 1351 insertions(+) create mode 100644 docs/Desktop.Controls/Button/Button.md create mode 100644 docs/Desktop.Controls/Button/ButtonAPI.md create mode 100644 docs/Desktop.Controls/Button/ButtonStyling.md create mode 100644 docs/Desktop.Controls/Button/ButtonToken.md create mode 100644 docs/Desktop.Controls/Button/ButtonUsage.md diff --git a/docs/Desktop.Controls/Button/Button.md b/docs/Desktop.Controls/Button/Button.md new file mode 100644 index 000000000..20bb2422d --- /dev/null +++ b/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"` | 内容展示器 | + diff --git a/docs/Desktop.Controls/Button/ButtonAPI.md b/docs/Desktop.Controls/Button/ButtonAPI.md new file mode 100644 index 000000000..f63b4e8a4 --- /dev/null +++ b/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` | 按钮点击事件（继承自 `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` 的子控件参与表单验证流程。 + diff --git a/docs/Desktop.Controls/Button/ButtonStyling.md b/docs/Desktop.Controls/Button/ButtonStyling.md new file mode 100644 index 000000000..b84033aa5 --- /dev/null +++ b/docs/Desktop.Controls/Button/ButtonStyling.md @@ -0,0 +1,273 @@ +# Button 自定义样式指南 + +Button 的视觉表现通过 `ControlTheme` + Design Token 系统控制。以下介绍几种常见的自定义方式。 + +--- + +## 1. 使用属性直接控制 + +最简单的方式是通过 Button 的公共属性来控制外观： + +```xml + +主按钮 +虚线按钮 +文本按钮 +链接按钮 + + +胶囊按钮 + + + +大按钮 +小按钮 + + +危险幽灵 + + + + Download + +``` + +> 📖 完整示例参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` + +--- + +## 2. 通过 Style 覆盖样式 + +可以在 AXAML 中使用 `Style` 对 Button 进行全局或局部样式覆盖： + +### 全局统一间距 + +```xml + + + +``` + +### 按类型定制颜色 + +```xml + + + +``` + +### 使用伪类选择器 + +```xml + + + + + + + + +``` + +### 通过属性选择器定制形状 + +```xml + + + + + +``` + +--- + +## 3. 通过 ControlTheme 完全替换主题 + +如果需要彻底替换 Button 的模板和样式，可以定义自定义 `ControlTheme`： + +```xml + + + + + + + + + + + + +自定义按钮 +``` + +> ⚠️ 注意：完全替换 ControlTheme 将丢失内置的波纹效果、加载图标等功能。建议优先使用 Style 覆盖。 + +--- + +## 4. Block 按钮（撑满父容器） + +Ant Design 的 `block` 属性在 AtomUI 中通过 Avalonia 原生布局属性实现： + +```xml + + + Primary Block + + + Default Block + + + Dashed Block + + +``` + +> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` 中 "Block Button" 示例。 + +--- + +## 5. 加载状态交互示例 + +```xml + + Click me! + +``` + +```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 + + + Primary + Default + Dashed + Danger + + +``` + +> 📖 参考：`controlgallery/AtomUIGallery/ShowCases/Views/General/ButtonShowCase.axaml` 中 "Ghost Button" 示例。 + +--- + +## 7. 控制动画行为 + +```xml + +无动画 + + +无波纹 +``` + +--- + +## 样式选择器速查 + +> 说明：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` | 访问模板内的图标展示器部件 | + diff --git a/docs/Desktop.Controls/Button/ButtonToken.md b/docs/Desktop.Controls/Button/ButtonToken.md new file mode 100644 index 000000000..e0887bcfa --- /dev/null +++ b/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` | + diff --git a/docs/Desktop.Controls/Button/ButtonUsage.md b/docs/Desktop.Controls/Button/ButtonUsage.md new file mode 100644 index 000000000..308cddadf --- /dev/null +++ b/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 + + Primary Button + Default Button + Dashed + Text Button + Link Button + +``` + +**使用场景指引**： +- 一个操作区域只放一个 **Primary** 按钮，引导用户注意力 +- 多个并列操作使用 **Default** 按钮 +- 添加类操作使用 **Dashed** 按钮 +- 内联次级操作使用 **Text** 按钮 +- 导航跳转使用 **Link** 按钮 + +--- + +## 2. 按钮形状 + +通过 `Shape` 属性设置按钮形状，支持默认矩形、圆形和胶囊形。 + +```xml + +Primary +Default + + +Primary +Default + + +AA +AA +``` + +**提示**：圆形按钮会强制 `宽度 = 高度`，最适合只放一个图标的场景。 + +--- + +## 3. 按钮尺寸 + +通过 `SizeType` 属性设置尺寸，支持 `Large`、`Middle`（默认）、`Small` 三种。 + +```xml +Large +Default +Small +``` + +尺寸也支持数据绑定，可在运行时动态切换： + +```xml + +Primary +Dashed +Default +Link +``` + +```csharp +// ViewModel +public class ButtonViewModel : ReactiveObject +{ + private SizeType _buttonSizeType; + public SizeType ButtonSizeType + { + get => _buttonSizeType; + set => this.RaiseAndSetIfChanged(ref _buttonSizeType, value); + } +} +``` + +尺寸与形状和图标组合使用： + +```xml + + + + + + + + Download + +``` + +--- + +## 4. 图标按钮 + +通过 `Icon` 属性设置按钮图标，图标使用 Ant Design 图标集提供： + +```xml + + + + + + Search + + + + + + Search + + + Search + + + Search + + +``` + +**图标 + 危险样式组合**： + +```xml + + Search + + + Search + + +``` + +--- + +## 5. 加载中状态 + +通过设置 `IsLoading` 属性控制按钮加载状态。加载中时按钮显示旋转图标，不透明度降低。 + +### 静态加载状态 + +```xml +Loading +Loading + + + +``` + +### 点击后动态进入加载态 + +这是最常见的使用场景——点击按钮发起异步请求，完成后恢复： + +```xml + + Click me! + + + + Click me! + + + + +``` + +```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 +Primary +Default +Dashed +Text +Link +``` + +**使用场景**：删除、移动、修改权限等不可逆操作，通常需配合二次确认弹窗。 + +--- + +## 7. 幽灵按钮 + +通过 `IsGhost="True"` 使按钮背景透明，适合放置在有色背景上： + +```xml + + + + + Primary + Default + Dashed + Text + Link + + Danger + + + + + + + Primary + + + Default + + + Danger + + + + +``` + +--- + +## 8. Block 按钮 + +Ant Design 的 `block` 属性在 AtomUI 中通过 Avalonia 原生布局属性 `HorizontalAlignment="Stretch"` 实现，使按钮撑满父容器宽度： + +```xml + + + Primary + + + Default + + + Dashed + + + Text + + + Link + + +``` + +--- + +## 9. 禁用状态 + +通过 `IsEnabled="False"` 禁用按钮，所有类型均支持： + +```xml + + + + Primary + + + Primary(disabled) + + + + + + Default + + + Default(disabled) + + + + + + + Danger Primary + + + Danger Primary(disabled) + + + + + + + + Ghost + + + Ghost(disabled) + + + +``` + +--- + +## 10. MVVM 命令绑定 + +Button 继承自 Avalonia 的 `Button`，完整支持 `Command` / `CommandParameter` 绑定模式： + +```xml + + Save + + + + Delete + +``` + +```csharp +// ViewModel（使用 ReactiveUI） +[Reactive] +public ReactiveCommand 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 + + + OK + + + + + Cancel + + + + + Save (Ctrl+S) + +``` + +--- + +## 12. 控制动画行为 + +```xml + + + No Animation + + + + + No Wave + +``` + +--- + +## 常见组合模式 + +### 操作栏（主 + 次按钮） + +```xml + + Submit + Cancel + +``` + +### 确认/取消对话框 + +```xml + + Cancel + OK + +``` + +### 危险操作确认 + +```xml + + Cancel + + Delete + + +``` + +### 工具栏（纯图标按钮组） + +```xml + + + + + +``` +