AtomUI/docs/Desktop.Controls/ToggleIconButton/ToggleIconButton.md

ToggleIconButton 切换图标按钮

概述

切换图标按钮（ToggleIconButton）是一个纯图标的切换按钮控件，在选中（Checked）和未选中（Unchecked）状态之间切换时可以显示不同的图标。它没有文本内容、无背景、无边框，仅通过图标和图标颜色来表达状态。

ToggleIconButton 常用于工具栏、面板头部的折叠/展开、收藏/取消收藏、排序方向切换等交互场景。在 Ant Design 中没有直接对应的组件，它是 AtomUI 基于 Avalonia ToggleButton 扩展的实用控件。

---

设计原理

设计定位

在 Ant Design 的组件体系中，切换类控件（Switch、Checkbox、Radio）都有较重的视觉表现和明确的表单语义。而在实际开发中，经常需要一种更轻量的切换方式——仅通过图标变化表达二元状态，不占据过多视觉空间。例如：

• 折叠/展开：Collapse 面板的箭头图标在展开和收起时切换方向
• 排序切换：表格列标题的排序图标在升序和降序之间切换
• 收藏/取消：心形或星形图标在空心和实心之间切换

ToggleIconButton 就是为这类轻量切换场景设计的。

Avalonia ToggleButton 基础能力

AtomUI 的 ToggleIconButton 通过 AbstractToggleIconButton 继承自 Avalonia 的 Avalonia.Controls.Primitives.ToggleButton。理解 Avalonia ToggleButton 的基础能力有助于理解 ToggleIconButton 的交互基础。

Avalonia ToggleButton 的核心职责：

Avalonia 的 ToggleButton 继承自 Button，在标准按钮的点击行为之上增加了 IsChecked 状态管理。每次点击时 IsChecked 在 true / false（以及可选的 null）之间切换。它的继承链为：

Control → TemplatedControl → ContentControl → Button → ToggleButton

Avalonia ToggleButton 提供的基础属性：

属性	说明
IsChecked	切换状态：true（选中）、false（未选中）、null（不确定，当 IsThreeState=true 时）
IsThreeState	是否支持三态切换
Command / CommandParameter	MVVM 命令绑定
ClickMode	点击触发时机
IsPressed	只读，是否处于按压状态

Avalonia ToggleButton 提供的基础伪类：

伪类	说明
:checked	IsChecked == true
:unchecked	IsChecked == false
:indeterminate	IsChecked == null（三态模式）
:pointerover	鼠标悬浮
:pressed	按下
:disabled	禁用

AtomUI 的扩展设计

AtomUI ToggleIconButton 在 Avalonia ToggleButton 的基础上做了以下扩展：

扩展能力	实现方式	设计动机
双图标切换	CheckedIcon + UnCheckedIcon 属性	选中和未选中状态显示不同图标，通过模板中两个 IconPresenter 的可见性切换实现
精细颜色控制	NormalIconBrush / ActiveIconBrush / SelectedIconBrush / DisabledIconBrush	四种状态各有独立的颜色属性，主题根据伪类自动切换
当前生效颜色	IconBrush 属性	由主题根据当前状态自动设置的生效颜色
图标尺寸	IconWidth / IconHeight 属性	精确控制图标渲染尺寸
过渡动画	IMotionAwareControl + Background / RenderTransform 过渡	平滑的背景色和变换过渡
Design Token	ButtonToken.ScopeProvider	复用 Button 的 Token 作用域

---

功能详解

双图标切换机制

ToggleIconButton 通过两个属性分别设置选中和未选中状态的图标：

属性	用途	可见性条件
CheckedIcon	选中状态（IsChecked = true）时显示的图标	:checked 伪类激活时可见
UnCheckedIcon	未选中状态（IsChecked = false）时显示的图标	:unchecked 伪类激活时可见

模板中包含两个 IconPresenter，通过 IsChecked 绑定控制它们的交替显示。

颜色状态系统

ToggleIconButton 提供了精细的颜色控制体系，支持四种状态各自独立的颜色定义：

属性	对应状态	说明
NormalIconBrush	未选中正常态	默认图标颜色
ActiveIconBrush	悬浮/按下态	鼠标悬浮或按下时的图标颜色
SelectedIconBrush	选中态	IsChecked = true 时的图标颜色
DisabledIconBrush	禁用态	IsEnabled = false 时的图标颜色
IconBrush	当前生效颜色	由主题根据当前状态自动赋值，实际渲染使用此属性

过渡动画

当 IsMotionEnabled = true 时，OnLoaded 阶段自动配置以下过渡：

• Background：SolidColorBrushTransition（背景色平滑过渡）
• RenderTransform：TransformOperationsTransition（缩放/旋转等变换平滑过渡）

OnUnloaded 时清除过渡，避免不可见控件消耗资源。

---

继承关系

Avalonia.Controls.Primitives.TemplatedControl
  └── Avalonia.Controls.ContentControl
        └── Avalonia.Controls.Button
              └── Avalonia.Controls.Primitives.ToggleButton
                    └── AtomUI.Controls.Commons.AbstractToggleIconButton (IMotionAwareControl)  ← 设备无关基类
                          └── AtomUI.Desktop.Controls.ToggleIconButton                          ← 桌面实现

各层级职责划分：

层级	提供的能力
Avalonia.Controls.Button	点击交互 → Click 事件、ICommand 绑定、IsPressed 状态
Avalonia.Controls.Primitives.ToggleButton	IsChecked 状态管理、:checked / :unchecked 伪类、三态支持
AbstractToggleIconButton（基类层）	CheckedIcon / UnCheckedIcon 双图标、四种颜色状态属性、IconWidth / IconHeight、过渡动画
ToggleIconButton（桌面层）	注册 ButtonToken.ScopeProvider，由主题控制视觉表现

实现的共享接口：

接口	定义位置	作用
IMotionAwareControl	AtomUI.Controls	支持 IsMotionEnabled 过渡动画开关

---

源码位置

层级	文件路径	说明
基类	src/AtomUI.Controls/Buttons/AbstractToggleIconButton.cs	设备无关基类
控件类	src/AtomUI.Desktop.Controls/Buttons/ToggleIconButton.cs	桌面切换图标按钮
主题模板	src/AtomUI.Desktop.Controls/Buttons/Themes/ToggleIconButtonTheme.axaml	ControlTheme AXAML
主题代码	src/AtomUI.Desktop.Controls/Buttons/Themes/ToggleIconButtonTheme.cs	主题 Code-behind
主题常量	src/AtomUI.Desktop.Controls/Buttons/Themes/ToggleIconButtonThemeConstants.cs	模板部件名常量

---

模板结构

Border#Frame (背景 + 边框 + 圆角)
  └── Panel#RootLayout (叠层容器)
        ├── IconPresenter#CheckedIconPresenter   (选中图标，IsChecked=True 时可见)
        └── IconPresenter#UnCheckedIconPresenter (未选中图标，IsChecked=False 时可见)

模板设计理由：

• Panel 叠层容器：两个 IconPresenter 叠加放置在同一位置，通过 IsVisible 绑定 IsChecked 实现交替显示。使用 Panel 而非 Grid 是因为只需简单叠层，无需行列定义。
• 两个独立 IconPresenter：分开两个图标展示器而非运行时替换 Icon 属性，避免了图标切换时的测量/排列抖动。

模板部件常量

常量名	值	说明
ToggleIconButtonThemeConstants.RootLayoutPart	"PART_RootLayout"	根布局面板
ToggleIconButtonThemeConstants.CheckedIconPresenterPart	"PART_CheckedIconPresenter"	选中态图标展示器
ToggleIconButtonThemeConstants.UnCheckedIconPresenterPart	"PART_UnCheckedIconPresenter"	未选中态图标展示器