AtomUI/docs/Desktop.Controls/ProgressBar/ProgressBarStyling.md

ProgressBar 自定义样式指南

ProgressBar 家族（ProgressBar、CircleProgress、DashboardProgress、StepsProgressBar）的视觉表现通过自定义渲染 + Design Token 系统控制。由于进度条采用 DrawingContext 直接绘制，样式自定义主要通过属性控制和 Token 覆盖实现。

---

1. 使用属性直接控制

线形进度条（ProgressBar）

<!-- 基本用法 -->
<atom:ProgressBar Value="30" Minimum="0" Maximum="100" />

<!-- 不同状态 -->
<atom:ProgressBar Value="70" Status="Exception" />
<atom:ProgressBar Value="100" />   <!-- 自动显示完成图标 -->

<!-- 隐藏进度信息 -->
<atom:ProgressBar Value="50" IsShowProgressInfo="False" />

<!-- 不同尺寸 -->
<atom:ProgressBar Value="50" SizeType="Large" />
<atom:ProgressBar Value="50" SizeType="Middle" />
<atom:ProgressBar Value="50" SizeType="Small" />

<!-- 自定义线宽 -->
<atom:ProgressBar Value="50" IndicatorThickness="20" />

<!-- 方角端点 -->
<atom:ProgressBar Value="75" StrokeLineCap="Square" />

<!-- 垂直方向 -->
<atom:ProgressBar Value="55" Orientation="Vertical" Height="300" />

圆形进度条（CircleProgress）

<!-- 基本用法 -->
<atom:CircleProgress Value="75" Minimum="0" Maximum="100" />

<!-- 不同尺寸 -->
<atom:CircleProgress Value="75" SizeType="Large" />
<atom:CircleProgress Value="75" SizeType="Middle" />
<atom:CircleProgress Value="75" SizeType="Small" />

<!-- 精确尺寸控制 -->
<atom:CircleProgress Value="50" Width="20" Height="20" />

<!-- 自定义线宽 -->
<atom:CircleProgress Value="50" IndicatorThickness="20" />

<!-- 步进段 -->
<atom:CircleProgress Value="50" StepCount="4" StepGap="8" IndicatorThickness="20" />

<!-- 自定义文字格式 -->
<atom:CircleProgress Value="75" ProgressTextFormat="\{0\} Days" />

仪表盘进度条（DashboardProgress）

<!-- 不同缺口位置 -->
<atom:DashboardProgress Value="75" DashboardGapPosition="Left" />
<atom:DashboardProgress Value="60" DashboardGapPosition="Top" />
<atom:DashboardProgress Value="75" DashboardGapPosition="Right" GapDegree="40" />
<atom:DashboardProgress Value="100" DashboardGapPosition="Bottom" GapDegree="40" />

<!-- 步进段仪表盘 -->
<atom:DashboardProgress Value="50" StepCount="4" StepGap="8" IndicatorThickness="20" />

步骤进度条（StepsProgressBar）

<!-- 基本用法 -->
<atom:StepsProgressBar Value="50" Steps="3" />
<atom:StepsProgressBar Value="30" Steps="5" />
<atom:StepsProgressBar Value="100" Steps="5" SizeType="Middle" />
<atom:StepsProgressBar Value="80" Steps="8" SizeType="Small" />

<!-- 自定义块尺寸 -->
<atom:StepsProgressBar Value="50" Steps="3" ChunkHeight="20" ChunkWidth="20" />

<!-- 垂直方向 -->
<atom:StepsProgressBar Value="55" Steps="5" Orientation="Vertical" Height="300" />

📖 完整示例参考：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/ProgressBarShowCase.axaml

---

2. 自定义颜色

自定义描边颜色

<!-- 纯色 -->
<atom:ProgressBar Value="70" StrokeBrush="#001342" />

<!-- 线性渐变 -->
<atom:ProgressBar Value="99">
    <atom:ProgressBar.StrokeBrush>
        <LinearGradientBrush StartPoint="0%,0%" EndPoint="100%,0%">
            <GradientStop Color="#108ee9" Offset="0" />
            <GradientStop Color="#87d068" Offset="1" />
        </LinearGradientBrush>
    </atom:ProgressBar.StrokeBrush>
</atom:ProgressBar>

<!-- 圆形渐变 -->
<atom:CircleProgress Value="90">
    <atom:CircleProgress.StrokeBrush>
        <LinearGradientBrush StartPoint="0%,0%" EndPoint="100%,0%">
            <GradientStop Color="#108ee9" Offset="0" />
            <GradientStop Color="#87d068" Offset="1" />
        </LinearGradientBrush>
    </atom:CircleProgress.StrokeBrush>
</atom:CircleProgress>

自定义轨道颜色

<atom:ProgressBar Value="50" TrailColor="LightGray" />

每个步骤独立颜色

<!-- 通过绑定设置步骤颜色列表 -->
<atom:StepsProgressBar Value="60" Steps="5"
                       StepsStrokeBrush="{Binding StepsChunkBrushes}" />

// ViewModel
public List<IBrush> StepsChunkBrushes { get; } = new()
{
    new SolidColorBrush(Colors.Green),
    new SolidColorBrush(Colors.Green),
    new SolidColorBrush(Colors.Orange),
    new SolidColorBrush(Colors.Red),
    new SolidColorBrush(Colors.Red),
};

---

3. 成功阈值

<!-- 线形 -->
<atom:ProgressBar Value="60" SuccessThreshold="30" />

<!-- 圆形 -->
<atom:CircleProgress Value="60" SuccessThreshold="30" />

<!-- 仪表盘 + 自定义成功色 -->
<atom:DashboardProgress Value="60" SuccessThreshold="30" SuccessStrokeBrush="Chocolate" />

<!-- 步进段 + 成功阈值 -->
<atom:CircleProgress Value="77" StepCount="8" StepGap="10"
                     IndicatorThickness="20" SuccessThreshold="30" />

---

4. 百分比标签位置（ProgressBar）

ProgressBar 支持通过 PercentPosition 精确控制百分比标签位置：

// ViewModel 中定义不同位置
public PercentPosition InnerStartPercentPosition { get; } = new() { IsInner = true, Alignment = LinePercentAlignment.Start };
public PercentPosition InnerCenterPercentPosition { get; } = new() { IsInner = true, Alignment = LinePercentAlignment.Center };
public PercentPosition InnerEndPercentPosition { get; } = new() { IsInner = true, Alignment = LinePercentAlignment.End };
public PercentPosition OuterStartPercentPosition { get; } = new() { IsInner = false, Alignment = LinePercentAlignment.Start };
public PercentPosition OuterCenterPercentPosition { get; } = new() { IsInner = false, Alignment = LinePercentAlignment.Center };

<!-- Inner 模式：标签在进度条内部 -->
<atom:ProgressBar Value="30" Width="300"
                  PercentPosition="{Binding InnerStartPercentPosition}" />
<atom:ProgressBar Value="60" Width="300"
                  PercentPosition="{Binding InnerCenterPercentPosition}" />
<atom:ProgressBar Value="50" Width="300"
                  PercentPosition="{Binding InnerEndPercentPosition}" />

<!-- Outer 模式：标签在进度条外部 -->
<atom:ProgressBar Value="100"
                  PercentPosition="{Binding OuterStartPercentPosition}" />
<atom:ProgressBar Value="60"
                  PercentPosition="{Binding OuterCenterPercentPosition}" />

📖 参考：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/ProgressBarShowCase.axaml 中 "Change progress value position" 示例。

---

5. 通过 Style 覆盖样式

<Window.Styles>
    <!-- 统一圆形进度条间距 -->
    <Style Selector="atom|CircleProgress">
        <Setter Property="Margin" Value="5" />
    </Style>
    
    <!-- 统一仪表盘间距 -->
    <Style Selector="atom|DashboardProgress">
        <Setter Property="Margin" Value="5" />
    </Style>
    
    <!-- 所有线形进度条使用方角 -->
    <Style Selector="atom|ProgressBar">
        <Setter Property="StrokeLineCap" Value="Square" />
    </Style>
    
    <!-- 异常状态使用自定义前景色 -->
    <Style Selector="atom|ProgressBar[Status=Exception]">
        <Setter Property="Foreground" Value="DarkRed" />
    </Style>
</Window.Styles>

---

6. 动态交互示例

<StackPanel Orientation="Vertical" Spacing="10">
    <atom:ProgressBar Value="{Binding ProgressValue}" IsShowProgressInfo="False" />
    <atom:CircleProgress Value="{Binding ProgressValue}" />
    <StackPanel Orientation="Horizontal" Spacing="10">
        <atom:Button SizeType="Small" Command="{Binding SubProgressValue}">Sub</atom:Button>
        <atom:Button SizeType="Small" Command="{Binding AddProgressValue}">Add</atom:Button>
    </StackPanel>
</StackPanel>

public class ProgressBarViewModel : ReactiveObject
{
    [Reactive] public double ProgressValue { get; set; } = 50;
    
    public ReactiveCommand<Unit, Unit> AddProgressValue { get; }
    public ReactiveCommand<Unit, Unit> SubProgressValue { get; }
    
    public ProgressBarViewModel()
    {
        AddProgressValue = ReactiveCommand.Create(() => 
        {
            ProgressValue = Math.Min(100, ProgressValue + 10);
        });
        SubProgressValue = ReactiveCommand.Create(() => 
        {
            ProgressValue = Math.Max(0, ProgressValue - 10);
        });
    }
}

📖 参考：controlgallery/AtomUIGallery/ShowCases/Views/Feedback/ProgressBarShowCase.axaml 中 "Dynamic" 示例。

---

样式选择器速查

按控件类型选择

选择器	说明
atom|ProgressBar	匹配所有线形进度条
atom|CircleProgress	匹配所有圆形进度条
atom|DashboardProgress	匹配所有仪表盘进度条
atom|StepsProgressBar	匹配所有步骤进度条

按状态选择

选择器	说明
atom|ProgressBar[Status=Normal]	Normal 状态的线形进度条
atom|ProgressBar[Status=Exception]	异常状态的线形进度条
atom|ProgressBar[Status=Active]	活跃状态的线形进度条
atom|CircleProgress[Status=Exception]	异常状态的圆形进度条

按尺寸选择

选择器	说明
atom|ProgressBar[SizeType=Large]	大号线形进度条
atom|ProgressBar[SizeType=Small]	小号线形进度条
atom|CircleProgress[SizeType=Middle]	中号圆形进度条

按伪类选择

选择器	说明
atom|ProgressBar:completed	已完成的进度条（Value == Maximum）
atom|ProgressBar:indeterminate	不定态进度条
atom|ProgressBar:horizontal	水平方向进度条
atom|ProgressBar:vertical	垂直方向进度条
atom|ProgressBar:labelinner	百分比标签在内部的进度条
atom|ProgressBar:disabled	禁用状态

组合选择器示例

选择器	说明
atom|ProgressBar[Status=Exception]:completed	异常但已完成的进度条
atom|ProgressBar:vertical[SizeType=Small]	垂直方向小号进度条
atom|StepsProgressBar:horizontal[SizeType=Large]	水平方向大号步骤进度条