AtomUI/docs/Icons.Shared/UsageGuide.md

Icon 使用规范指南

本文档规范 AtomUI 项目中 Icon 的各种使用方式，涵盖 C# 代码和 AXAML 标记两个场景。

---

1. AXAML 中使用 Icon

1.1 命名空间声明

在 AXAML 文件头部添加 Ant Design 图标命名空间：

xmlns:antdicons="https://atomui.net/icons/antdesign"

约定: Ant Design 图标推荐前缀 antdicons，自定义图标包使用自己的前缀。

1.2 直接作为 XML 元素使用

最常用的方式——直接在 AXAML 中实例化图标控件：

<!-- 基础用法 -->
<antdicons:CheckCircleFilled />
<antdicons:LoadingOutlined />
<antdicons:SettingTwoTone />

<!-- 设置 Loading 动画 -->
<antdicons:LoadingOutlined LoadingAnimation="Spin" />

<!-- 自定义画刷颜色 -->
<antdicons:CheckCircleFilled
    FillBrush="{atom:SharedTokenResource ColorSuccess}" />

<!-- TwoTone 图标设置双色 -->
<antdicons:SettingTwoTone
    StrokeBrush="{atom:SharedTokenResource ColorPrimary}"
    FillBrush="{atom:SharedTokenResource ColorInfoBg}" />

<!-- 设置尺寸 -->
<antdicons:SearchOutlined Width="24" Height="24" />

适用场景：在 ControlTheme 模板中直接放置图标、需要精细控制图标属性时。

1.3 通过 IconProvider MarkupExtension 使用

用于需要将图标赋值给 PathIcon? 类型属性的场景：

<!-- 基本用法 - 简写（省略 Kind=） -->
<atom:Button Icon="{antdicons:AntDesignIconProvider CloseOutlined}" />

<!-- 完整写法 -->
<atom:Button Icon="{antdicons:AntDesignIconProvider Kind=CheckCircleFilled}" />

<!-- 设置画刷和尺寸 -->
<atom:IconButton
    Icon="{antdicons:AntDesignIconProvider Kind=DeleteOutlined,
           FillBrush=Red, Width=16, Height=16}" />

<!-- 设置动画 -->
<atom:Button
    Icon="{antdicons:AntDesignIconProvider Kind=LoadingOutlined,
           Animation=Spin}" />

AntDesignIconProvider 的构造函数接受一个 AntDesignIconKind 参数，因此 {antdicons:AntDesignIconProvider CloseOutlined} 是 {antdicons:AntDesignIconProvider Kind=CloseOutlined} 的简写形式。

适用场景：给控件的 Icon 属性赋值（如 Button.Icon、IconButton.Icon、MenuItem.Icon）。

1.4 在 IconTemplate 中使用

<atom:IconTemplate>
    <antdicons:CloseOutlined />
</atom:IconTemplate>

适用场景：控件需要 IconTemplate 类型属性时（如 Tour 控件的关闭图标）。

1.5 主题文件中的典型模式

<ResourceDictionary
    xmlns="https://github.com/avaloniaui"
    xmlns:atom="https://atomui.net"
    xmlns:antdicons="https://atomui.net/icons/antdesign">

    <ControlTheme TargetType="atom:Alert">
        <Setter Property="Template">
            <ControlTemplate>
                <!-- 多个图标按状态显示/隐藏 -->
                <antdicons:CheckCircleFilled Name="SuccessIcon"
                    IsVisible="False" />
                <antdicons:InfoCircleFilled Name="InfoIcon"
                    IsVisible="False" />
                <antdicons:ExclamationCircleFilled Name="WarningIcon"
                    IsVisible="False" />
                <antdicons:CloseCircleFilled Name="ErrorIcon"
                    IsVisible="False" />
            </ControlTemplate>
        </Setter>

        <!-- 通过 Style Selector 控制可见性 -->
        <Style Selector="^:success /template/ antdicons|CheckCircleFilled#SuccessIcon">
            <Setter Property="IsVisible" Value="True" />
        </Style>
    </ControlTheme>
</ResourceDictionary>

注意: 在 Style Selector 中引用图标类型时，使用 antdicons|CheckCircleFilled 语法（| 分隔命名空间和类型名）。

---

2. C# 代码中使用 Icon

2.1 直接实例化

using AtomUI.Icons.AntDesign;

// 基础实例化
var icon = new CheckCircleFilled();

// 设置属性
var loadingIcon = new LoadingOutlined()
{
    LoadingAnimation = IconAnimation.Spin
};

// 通过 SetCurrentValue 设置（推荐，保留属性优先级）
SetCurrentValue(IconProperty, new CloseCircleFilled());

// 通过 SetValue 设置（指定绑定优先级）
SetValue(IconProperty, new CheckCircleFilled(), BindingPriority.Template);

2.2 动态根据状态创建 Icon

using AtomUI.Icons.AntDesign;

// 根据状态选择不同图标
PathIcon? icon = notificationType switch
{
    NotificationType.Success     => new CheckCircleFilled(),
    NotificationType.Information => new InfoCircleFilled(),
    NotificationType.Warning     => new ExclamationCircleFilled(),
    NotificationType.Error       => new CloseCircleFilled(),
    _                            => null
};

// 设置到控件属性
if (icon != null)
{
    SetCurrentValue(IconProperty, icon);
}

2.3 带动画的 Loading 图标

using AtomUI.Icons.AntDesign;
using AtomUI.Controls;

// 创建旋转加载图标
SetCurrentValue(SuffixLoadingIconProperty, new LoadingOutlined()
{
    LoadingAnimation = IconAnimation.Spin
});

2.4 IconFuncTemplate 用法

在代码中创建可复用的图标模板：

using AtomUI.Controls;
using AtomUI.Icons.AntDesign;

// 创建函数式图标模板
var iconTemplate = new IconFuncTemplate(() => new SearchOutlined());

---

3. Icon 属性体系速查

3.1 外观属性

属性	类型	说明	默认来源
Width / Height	double	图标尺寸	SharedToken.IconSize
StrokeBrush	IBrush?	主描边画刷（Outlined 主色）	SharedToken.ColorIconHover
FillBrush	IBrush?	主填充画刷（Filled 主色）	SharedToken.ColorIconHover
SecondaryStrokeBrush	IBrush?	次描边画刷（TwoTone 次色）	IconToken.SecondaryStrokeColor
SecondaryFillBrush	IBrush?	次填充画刷（TwoTone 次色）	IconToken.SecondaryFillColor
FallbackBrush	IBrush?	回退画刷	White
StrokeWidth	double	描边线宽	IconToken.StrokeWidth (4)
StrokeLineCap	PenLineCap	线端样式	IconToken.StrokeLineCap (Round)
StrokeLineJoin	PenLineJoin	线连接样式	IconToken.StrokeLineJoin (Round)

3.2 动画属性

属性	类型	说明	默认值
LoadingAnimation	IconAnimation	动画类型	None
LoadingAnimationDuration	TimeSpan	旋转周期	1s
FillAnimationDuration	TimeSpan	颜色过渡时长	200ms（来自 MotionDurationMid token）
IsMotionEnabled	bool	启用/禁用动画	来自 SharedToken.EnableMotion

3.3 IconAnimation 枚举

值	效果
None	无动画
Spin	匀速旋转（平滑）
Pulse	步进旋转（8 步阶梯，类似 CSS steps(8)）

---

4. 常见使用场景

4.1 按钮中的图标

<!-- 图标按钮 -->
<atom:Button Icon="{antdicons:AntDesignIconProvider SearchOutlined}"
             ButtonType="Primary">
    Search
</atom:Button>

<!-- 纯图标按钮 -->
<atom:IconButton Icon="{antdicons:AntDesignIconProvider DeleteOutlined}" />

<!-- Loading 按钮 -->
<atom:Button IsLoading="True" ButtonType="Primary">
    Submitting
</atom:Button>
<!-- Button 内部会自动显示 LoadingOutlined 带 Spin 动画 -->

4.2 输入框中的图标

<!-- 带前缀/后缀图标 -->
<atom:TextBox>
    <atom:TextBox.InnerLeftContent>
        <antdicons:UserOutlined />
    </atom:TextBox.InnerLeftContent>
</atom:TextBox>

4.3 提示信息中的状态图标

// NotificationCard / MessageCard 内部实现模式
PathIcon? icon = messageType switch
{
    MessageType.Success => new CheckCircleFilled(),
    MessageType.Error   => new CloseCircleFilled(),
    MessageType.Warning => new ExclamationCircleFilled(),
    MessageType.Info    => new InfoCircleFilled(),
    MessageType.Loading => new LoadingOutlined()
    {
        LoadingAnimation = IconAnimation.Spin
    },
    _ => null
};

4.4 导航菜单中的图标

<atom:NavMenuItem Header="Dashboard"
                  Icon="{antdicons:AntDesignIconProvider DashboardOutlined}">
</atom:NavMenuItem>

4.5 进度条完成/异常图标

// 在控件内部设置默认图标
SetValue(SuccessCompletedIconProperty,
    new CheckCircleFilled(), BindingPriority.Template);
SetValue(ExceptionCompletedIconProperty,
    new CloseCircleFilled(), BindingPriority.Template);

---

5. 颜色控制最佳实践

5.1 通过 Token 系统控制颜色（推荐）

在主题文件中使用 Token 资源，确保 Icon 颜色跟随主题变化：

<!-- 使用全局 SharedToken -->
<antdicons:CheckCircleFilled
    FillBrush="{atom:SharedTokenResource ColorSuccess}" />

<!-- 使用组件 Token -->
<antdicons:CloseOutlined
    StrokeBrush="{atom:TokenResource NotificationCloseIconColor}" />

5.2 IconPresenter 统一颜色

当 Icon 嵌入在复杂控件中时，使用 IconPresenter 统一管理颜色：

<atom:IconPresenter Icon="{TemplateBinding Icon}"
                    IconBrush="{atom:SharedTokenResource ColorText}" />

IconPresenter 会自动将 IconBrush 同时绑定到子 Icon 的 StrokeBrush 和 FillBrush，无论图标是 Outlined 还是 Filled 类型都能正确着色。

5.3 TwoTone 图标颜色定制

<!-- 默认主题色 -->
<antdicons:SettingTwoTone />
<!-- 主色=ColorPrimary，次色=ColorInfoBg（由 IconTheme.axaml 定义） -->

<!-- 自定义双色 -->
<antdicons:HeartTwoTone
    StrokeBrush="Red"
    FillBrush="Pink" />

---

6. 编码规范与约定

6.1 命名空间导入

// 在 C# 中引用 Ant Design 图标
using AtomUI.Icons.AntDesign;

// 引用核心 Icon 类型
using AtomUI.Controls;  // Icon, IconAnimation, IconThemeType, etc.

6.2 在控件代码中使用图标的规范

• 优先使用 SetCurrentValue 设置图标，保留属性优先级链：

  SetCurrentValue(IconProperty, new CloseCircleFilled());
  

• 使用 SetValue + BindingPriority.Template 设置模板级默认值：

  SetValue(IconProperty, new CheckCircleFilled(), BindingPriority.Template);
  

• 不要在 AXAML 中硬编码图标颜色，始终使用 Token 资源引用

6.3 图标类命名约定

每个图标类的命名格式为 {IconName}{ThemeType}：

格式	示例
{Name}Filled	CheckCircleFilled、HomeFilled
{Name}Outlined	SearchOutlined、LoadingOutlined
{Name}TwoTone	SettingTwoTone、HeartTwoTone

6.4 Style Selector 中引用图标类型

在 AXAML Style Selector 中，使用 命名空间|类型名 语法：

<!-- 正确 -->
<Style Selector="^:success /template/ antdicons|CheckCircleFilled#SuccessIcon">

<!-- 带名称 -->
<Style Selector="/template/ antdicons|LoadingOutlined#LoadingIcon">

---

7. 常用图标参考

用途	推荐图标
成功状态	CheckCircleFilled / CheckCircleOutlined
错误状态	CloseCircleFilled / CloseCircleOutlined
警告状态	ExclamationCircleFilled / ExclamationCircleOutlined
信息状态	InfoCircleFilled / InfoCircleOutlined
加载中	LoadingOutlined（配合 LoadingAnimation="Spin"）
关闭	CloseOutlined
搜索	SearchOutlined
删除	DeleteOutlined
编辑	EditOutlined
清除	CloseCircleFilled（input 清除按钮）
展开/收起	RightOutlined / DownOutlined
上传	UploadOutlined
下载	DownloadOutlined
设置	SettingOutlined / SettingTwoTone
用户	UserOutlined
眼睛（显示/隐藏）	EyeOutlined / EyeInvisibleOutlined