mirror of
https://github.com/AtomUI/AtomUI.git
synced 2026-10-20 15:52:17 +08:00
chinboy
202 lines
7.9 KiB
Markdown
202 lines
7.9 KiB
Markdown
# ToggleIconButton 自定义样式指南
|
||
|
||
ToggleIconButton 的视觉表现通过 `ControlTheme` + Design Token 系统控制。由于 ToggleIconButton 是纯图标控件（无文本、无边框、无背景），其自定义主要集中在图标颜色和图标尺寸上。
|
||
|
||
---
|
||
|
||
## 1. 通过属性直接控制
|
||
|
||
最简单的方式是通过 ToggleIconButton 的公共属性来控制外观：
|
||
|
||
```xml
|
||
<!-- 基本切换图标按钮 -->
|
||
<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 进行全局或局部样式覆盖：
|
||
|
||
### 全局统一图标尺寸
|
||
|
||
```xml
|
||
<Window.Styles>
|
||
<Style Selector="atom|ToggleIconButton">
|
||
<Setter Property="IconWidth" Value="16" />
|
||
<Setter Property="IconHeight" Value="16" />
|
||
</Style>
|
||
</Window.Styles>
|
||
```
|
||
|
||
### 选中状态自定义颜色
|
||
|
||
```xml
|
||
<Style Selector="atom|ToggleIconButton:checked">
|
||
<Setter Property="IconBrush" Value="{atom:SharedTokenResource ColorPrimary}" />
|
||
</Style>
|
||
```
|
||
|
||
### 悬浮态自定义背景
|
||
|
||
```xml
|
||
<!-- 为悬浮态添加微弱背景 -->
|
||
<Style Selector="atom|ToggleIconButton:pointerover">
|
||
<Setter Property="Background" Value="{atom:SharedTokenResource ColorBgTextHover}" />
|
||
</Style>
|
||
```
|
||
|
||
### 按选中状态组合悬浮色
|
||
|
||
```xml
|
||
<!-- 选中 + 悬浮态使用主色调亮色 -->
|
||
<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`：
|
||
|
||
```xml
|
||
<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. 控制动画行为
|
||
|
||
```xml
|
||
<!-- 禁用过渡动画（背景色、变换不再渐变过渡） -->
|
||
<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 部件 |
|