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

ToggleIconButton 自定义样式指南

ToggleIconButton 的视觉表现通过 ControlTheme + Design Token 系统控制。由于 ToggleIconButton 是纯图标控件（无文本、无边框、无背景），其自定义主要集中在图标颜色和图标尺寸上。

---

1. 通过属性直接控制

最简单的方式是通过 ToggleIconButton 的公共属性来控制外观：

<!-- 基本切换图标按钮 -->
<atom:ToggleIconButton
    CheckedIcon="{antdicons:AntDesignIconProvider Kind=EyeOutlined}"
    UnCheckedIcon="{antdicons:AntDesignIconProvider Kind=EyeInvisibleOutlined}" />

<!-- 自定义图标尺寸 -->
<atom:ToggleIconButton
    CheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartFilled}"
    UnCheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartOutlined}"
    IconWidth="20" IconHeight="20" />

<!-- 自定义各状态图标颜色 -->
<atom:ToggleIconButton
    CheckedIcon="{antdicons:AntDesignIconProvider Kind=StarFilled}"
    UnCheckedIcon="{antdicons:AntDesignIconProvider Kind=StarOutlined}"
    NormalIconBrush="Gray"
    ActiveIconBrush="DarkGoldenrod"
    SelectedIconBrush="Gold"
    DisabledIconBrush="LightGray" />

颜色属性优先级

ToggleIconButton 的颜色由主题根据当前状态自动设置 IconBrush。当用户显式设置了 NormalIconBrush、ActiveIconBrush、SelectedIconBrush、DisabledIconBrush 时，这些值会覆盖主题默认颜色。

状态	优先使用的属性	默认来源（主题）
未选中正常态	NormalIconBrush	SharedToken.ColorIcon
悬浮/按下态	ActiveIconBrush	SharedToken.ColorIconHover（悬浮）/ SharedToken.ColorText（按下）
选中态	SelectedIconBrush	同正常态
禁用态	DisabledIconBrush	SharedToken.ColorTextDisabled

---

2. 通过 Style 覆盖样式

可以在 AXAML 中使用 Style 对 ToggleIconButton 进行全局或局部样式覆盖：

全局统一图标尺寸

<Window.Styles>
    <Style Selector="atom|ToggleIconButton">
        <Setter Property="IconWidth" Value="16" />
        <Setter Property="IconHeight" Value="16" />
    </Style>
</Window.Styles>

选中状态自定义颜色

<Style Selector="atom|ToggleIconButton:checked">
    <Setter Property="IconBrush" Value="{atom:SharedTokenResource ColorPrimary}" />
</Style>

悬浮态自定义背景

<!-- 为悬浮态添加微弱背景 -->
<Style Selector="atom|ToggleIconButton:pointerover">
    <Setter Property="Background" Value="{atom:SharedTokenResource ColorBgTextHover}" />
</Style>

按选中状态组合悬浮色

<!-- 选中 + 悬浮态使用主色调亮色 -->
<Style Selector="atom|ToggleIconButton:checked:pointerover">
    <Setter Property="IconBrush" Value="{atom:SharedTokenResource ColorPrimaryHover}" />
</Style>

<!-- 未选中 + 悬浮态使用图标悬浮色 -->
<Style Selector="atom|ToggleIconButton:unchecked:pointerover">
    <Setter Property="IconBrush" Value="{atom:SharedTokenResource ColorIconHover}" />
</Style>

---

3. 通过 ControlTheme 完全替换主题

如果需要彻底替换 ToggleIconButton 的模板和样式，可以定义自定义 ControlTheme：

<ControlTheme x:Key="MyCustomToggleIconButton" TargetType="atom:ToggleIconButton">
    <Setter Property="Template">
        <ControlTemplate>
            <Border Background="{TemplateBinding Background}"
                    CornerRadius="{TemplateBinding CornerRadius}"
                    Padding="{TemplateBinding Padding}">
                <Panel>
                    <atom:IconPresenter
                        Icon="{TemplateBinding CheckedIcon}"
                        IsVisible="{TemplateBinding IsChecked}"
                        Width="{TemplateBinding IconWidth}"
                        Height="{TemplateBinding IconHeight}"
                        IconBrush="{TemplateBinding IconBrush}" />
                    <atom:IconPresenter
                        Icon="{TemplateBinding UnCheckedIcon}"
                        IsVisible="{TemplateBinding IsChecked, Converter={x:Static BoolConverters.Not}}"
                        Width="{TemplateBinding IconWidth}"
                        Height="{TemplateBinding IconHeight}"
                        IconBrush="{TemplateBinding IconBrush}" />
                </Panel>
            </Border>
        </ControlTemplate>
    </Setter>
    <!-- 自定义样式... -->
</ControlTheme>

<!-- 使用 -->
<atom:ToggleIconButton Theme="{StaticResource MyCustomToggleIconButton}"
    CheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartFilled}"
    UnCheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartOutlined}" />

⚠️ 注意：完全替换 ControlTheme 将丢失内置的过渡动画等功能。建议优先使用 Style 覆盖。

---

4. 控制动画行为

<!-- 禁用过渡动画（背景色、变换不再渐变过渡） -->
<atom:ToggleIconButton
    CheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartFilled}"
    UnCheckedIcon="{antdicons:AntDesignIconProvider Kind=HeartOutlined}"
    IsMotionEnabled="False" />

过渡动画在 OnLoaded 时配置，OnUnloaded 时清除（避免不可见控件消耗资源）。

过渡属性	过渡类型	说明
Background	SolidColorBrushTransition	背景色平滑过渡
RenderTransform	TransformOperationsTransition	缩放/旋转等变换平滑过渡

---

5. 颜色状态映射

主题默认使用 SharedToken 中的图标色系：

状态	伪类	默认 Token	说明
正常	:unchecked（无悬浮）	ColorIcon	未选中且无交互时的图标色
悬浮	:pointerover	ColorIconHover	鼠标悬浮时的图标色
按下	:pressed	ColorText	鼠标按下时的图标色
禁用	:disabled	ColorTextDisabled	禁用态灰色

可通过 NormalIconBrush、ActiveIconBrush、SelectedIconBrush、DisabledIconBrush 属性覆盖默认颜色。

---

样式选择器速查

说明：Avalonia 样式选择器中使用 atom|ToggleIconButton 语法引用 atom XML 命名空间下的 ToggleIconButton 类型，其中 | 是命名空间分隔符。

基础选择器

选择器	说明
atom|ToggleIconButton	匹配所有 ToggleIconButton 实例，用于设置全局通用样式（如统一图标尺寸）

按状态伪类选择

选择器	说明
atom|ToggleIconButton:checked	匹配选中状态（IsChecked == true），可定制选中态的图标颜色
atom|ToggleIconButton:unchecked	匹配未选中状态（IsChecked == false），可定制未选中态的图标颜色
atom|ToggleIconButton:indeterminate	匹配不确定状态（IsChecked == null，三态模式下）
atom|ToggleIconButton:pointerover	匹配鼠标悬浮状态，用于定制 hover 时的图标颜色或背景
atom|ToggleIconButton:pressed	匹配按下状态，用于定制 active 时的视觉反馈
atom|ToggleIconButton:disabled	匹配禁用状态（IsEnabled == false），使用灰色调
atom|ToggleIconButton:focus-visible	匹配通过键盘（Tab 键）获得焦点的状态
atom|ToggleIconButton:focus	匹配获得焦点的状态（包含鼠标点击和键盘）

组合选择器示例

选择器	说明
atom|ToggleIconButton:checked:not(:disabled)	非禁用状态的选中按钮
atom|ToggleIconButton:checked:pointerover	选中状态 + 鼠标悬浮
atom|ToggleIconButton:unchecked:pointerover	未选中状态 + 鼠标悬浮
atom|ToggleIconButton /template/ atom|IconPresenter#PART_CheckedIconPresenter	访问模板内的选中态图标展示器部件
atom|ToggleIconButton /template/ atom|IconPresenter#PART_UnCheckedIconPresenter	访问模板内的未选中态图标展示器部件
atom|ToggleIconButton /template/ Border#Frame	访问模板内名为 Frame 的 Border 部件