AtomUI/docs/Desktop.Controls/CheckBox/CheckBox.md

CheckBox 复选框

概述

复选框（CheckBox）用于在一组选项中进行多选操作，允许用户从多个备选项中选择零个或多个。它支持三种状态：选中（Checked）、未选中（Unchecked）和半选中/不确定态（Indeterminate），半选态常用于实现「全选/部分选」的级联交互。

AtomUI 的 CheckBox 控件复刻了 Ant Design 5.0 Checkbox 的设计规范，在 .NET / Avalonia 平台上提供与 Ant Design React 版一致的视觉体验和交互行为。

---

设计原理

Ant Design 的复选框设计哲学

Ant Design 对复选框的定位是：「在一组可选项中进行多项选择」。其核心交互特征包括：

1. 独立使用 — 单个复选框表示两种状态（选中/未选中）之间的切换
2. 分组使用 — 多个复选框组成一组，用户可从中选择零个或多个选项
3. 全选联动 — 通过 Indeterminate 半选态实现「全选/部分选」的级联交互

设计建议（来自 Ant Design）：

• 单独使用时，用于选择一个或取消一个选项
• 集合使用时，用于收集用户的多项偏好
• 不要使用复选框来替代开关（Switch），复选框侧重于"收集选择"，开关侧重于"立即切换"

Avalonia CheckBox 基础能力

AtomUI 的 CheckBox 继承自 Avalonia 框架的 Avalonia.Controls.CheckBox（通过 AbstractCheckBox 中间层）。Avalonia CheckBox 继承自 ToggleButton，支持三态切换。其继承链为：

Control → TemplatedControl → ContentControl → Button → ToggleButton → CheckBox

Avalonia CheckBox 提供的基础属性：

属性	说明
Content	复选框旁的文本内容
IsChecked	选中状态：true（选中）、false（未选中）、null（不确定态）
IsThreeState	是否启用三态模式（允许 null 状态）
Command / CommandParameter	MVVM 命令绑定

Avalonia CheckBox 提供的基础伪类：

伪类	说明
:checked	选中状态
:unchecked	未选中状态
:indeterminate	不确定态（半选）
:pointerover	鼠标悬浮
:pressed	按下
:disabled	禁用

AtomUI 的扩展设计

AtomUI CheckBox 在 Avalonia CheckBox 的基础上，遵循 Ant Design 5.0 规范做了以下扩展：

扩展能力	实现方式	设计动机
自定义指示器	CheckBoxIndicator 内部控件	独立的选中/半选指示器，精确复刻 Ant Design 的勾选动画和圆角样式
点击波纹	IWaveSpiritAwareControl + WaveSpiritDecorator	复刻 Ant Design 的 Wave 点击涟漪效果
选中动画	CheckedMarkRenderTransform + scale 过渡	选中时勾号从缩放 0.1 过渡到 1.0 的动画效果
复选框组	CheckBoxGroup 容器控件	对齐 Ant Design 的 Checkbox.Group，支持分组管理、自动布局
数据驱动分组	CheckBoxGroup.ItemsSource + ICheckBoxOption	支持绑定数据集合生成复选框组
表单集成	IFormItemAware 接口	可参与 FormItem 验证流程
过渡动画	IsMotionEnabled	全局动画开关
Design Token	CheckBoxToken + RegisterTokenResourceScope	所有视觉值从全局/组件级 Token 派生

---

功能详解

三种状态

CheckBox 支持三种选中状态：

状态	IsChecked 值	视觉表现	典型用途
未选中	false	空白方框	默认状态
选中	true	蓝色背景 + 白色对勾	用户主动选择
不确定	null	白色背景 + 蓝色横杠	全选框部分子项被选中

默认为两态模式（IsThreeState = false），仅在 true ↔ false 之间切换。设置 IsThreeState = true 后启用三态循环：false → true → null → false。

复选框组（CheckBoxGroup）

CheckBoxGroup 是管理一组复选框的容器控件，提供统一的布局和选中状态管理：

• 支持 Orientation（水平/垂直排列）
• 支持 ItemSpacing / LineSpacing 控制间距
• 通过 CheckedItems 属性获取/设置选中项集合
• 触发 CheckedChanged 路由事件通知选中状态变化
• 支持 ItemsSource + ItemTemplate 数据驱动模式

指示器动画

CheckBox 使用自定义 CheckBoxIndicator 控件渲染选中标记：

• 选中时：对勾图标从 scale(0.1) 过渡到 scale(1.0)，产生弹入效果
• 半选时：显示蓝色横杠
• 波纹效果：点击时通过 WaveSpiritDecorator 产生方形波纹动画

---

与 Ant Design 规范的对齐程度

特性	Ant Design (React)	AtomUI (Avalonia)	对齐情况
基本复选框	✅ <Checkbox>	✅ <atom:CheckBox>	✅ 完全对齐
禁用 disabled	✅ 布尔属性	✅ IsEnabled	✅ 完全对齐
三态 indeterminate	✅ 布尔属性	✅ IsChecked=null + IsThreeState	✅ 完全对齐
复选框组 Checkbox.Group	✅ 组容器	✅ CheckBoxGroup	✅ 完全对齐
分组选项 options	✅ 数组配置	✅ ItemsSource + ICheckBoxOption	✅ 完全对齐
onChange	✅ 回调	✅ IsCheckedChanged / CheckedChanged 事件	✅ 完全对齐
全选联动	✅ 示例实现	✅ 通过 Indeterminate 态实现	✅ 完全对齐

---

继承关系

CheckBox

Avalonia.Controls.Primitives.TemplatedControl
  └── Avalonia.Controls.ContentControl
        └── Avalonia.Controls.Button
              └── Avalonia.Controls.Primitives.ToggleButton
                    └── Avalonia.Controls.CheckBox
                          └── AtomUI.Controls.Commons.AbstractCheckBox
                                ├── implements IWaveSpiritAwareControl
                                └── implements IFormItemAware
                                      └── AtomUI.Desktop.Controls.CheckBox

CheckBoxGroup

Avalonia.Controls.Primitives.TemplatedControl
  └── AtomUI.Controls.Commons.AbstractCheckBoxGroup
        ├── implements IMotionAwareControl
        └── implements IFormItemAware
              └── AtomUI.Desktop.Controls.CheckBoxGroup

实现的共享接口：

接口	控件	作用
IWaveSpiritAwareControl	CheckBox	支持点击涟漪（Wave）动画效果
IFormItemAware	CheckBox / CheckBoxGroup	可参与 FormItem 验证流程
IMotionAwareControl	CheckBoxGroup	支持 IsMotionEnabled 过渡动画开关

---

源码位置

层级	文件路径	说明
基类	src/AtomUI.Controls/CheckBox/AbstractCheckBox.cs	跨平台基类
基类	src/AtomUI.Controls/CheckBox/AbstractCheckBoxGroup.cs	复选框组跨平台基类
数据模型	src/AtomUI.Controls/CheckBox/CheckBoxOption.cs	ICheckBoxOption 接口和默认实现
控件类	src/AtomUI.Desktop.Controls/CheckBox/CheckBox.cs	桌面端 CheckBox
控件类	src/AtomUI.Desktop.Controls/CheckBox/CheckBoxGroup.cs	桌面端 CheckBoxGroup
Token 定义	src/AtomUI.Desktop.Controls/CheckBox/CheckBoxToken.cs	组件级 Design Token
主题模板	src/AtomUI.Desktop.Controls/CheckBox/Themes/CheckBoxTheme.axaml	CheckBox ControlTheme
主题模板	src/AtomUI.Desktop.Controls/CheckBox/Themes/CheckBoxGroupTheme.axaml	CheckBoxGroup ControlTheme
主题模板	src/AtomUI.Desktop.Controls/CheckBox/Themes/CheckBoxIndicatorTheme.axaml	指示器 ControlTheme
Gallery 示例	controlgallery/AtomUIGallery/ShowCases/Views/DataEntry/CheckBoxShowCase.axaml	使用范例

---

模板结构

CheckBox 模板

Border#Frame (Padding=0,1,0,1)
└── DockPanel
    ├── CheckBoxIndicator#Indicator (DockPanel.Dock=Left)  ← 选中指示器
    │   └── Panel
    │       ├── WaveSpiritDecorator (PART_WaveSpirit)     ← 点击波纹
    │       └── Border#Frame                               ← 指示器框架
    │           └── Panel
    │               ├── CheckBoldOutlined#CheckedMark     ← 对勾图标（选中时可见）
    │               └── Rectangle#TristateMark            ← 横杠（半选时可见）
    └── ContentPresenter#ContentPresenter                  ← 文本内容

CheckBoxGroup 模板

Border#Frame
└── CheckBoxItemsControl (PART_CheckBoxItems)  ← 内部 SelectingItemsControl
    └── WrapPanel                               ← 自动换行布局
        ├── CheckBox[0]
        ├── CheckBox[1]
        └── ...