# ProgressBar 使用文档
本文档介绍 AtomUI ProgressBar 家族四种控件的各种使用方式，示例代码摘自 Gallery 演示程序。
> 📖 Gallery 源码位置：`controlgallery/AtomUIGallery/ShowCases/Views/Feedback/ProgressBarShowCase.axaml`
---
## 前置准备
在 AXAML 中使用进度条，需要引入以下命名空间：
```xml
xmlns:atom="https://atomui.net"
```
在 C# 代码中引入：
```csharp
using AtomUI.Desktop.Controls; // ProgressBar, CircleProgress, DashboardProgress, StepsProgressBar
using AtomUI.Controls; // SizeType, ProgressStatus, PercentPosition 等共享类型
```
---
## 1. 线形进度条（ProgressBar）
最基础的进度条类型，展示水平或垂直方向的线形进度。
```xml
```
**行为说明**：
- `Value=100` 时自动切换为成功色并显示 ✓ 图标
- `Status="Exception"` 时使用红色并显示 ✗ 图标
- `IsShowProgressInfo="False"` 隐藏百分比文字
---
## 2. 圆形进度条（CircleProgress）
在紧凑空间中展示进度。
```xml
```
---
## 3. 尺寸控制
所有进度条支持三种尺寸，通过 `SizeType` 属性控制：
### 线形进度条
```xml
```
### 圆形进度条
```xml
```
### 仪表盘进度条
```xml
```
### 步骤进度条
```xml
```
---
## 4. 仪表盘进度条（DashboardProgress）
仪表盘形态支持设置缺口位置和缺口角度：
```xml
```
---
## 5. 步骤进度条（StepsProgressBar）
将进度分为离散的块状步骤：
```xml
```
每个步骤可以设置独立颜色：
```csharp
// ViewModel
public List StepsChunkBrushes { get; } = new()
{
new SolidColorBrush(Colors.Green),
new SolidColorBrush(Colors.Green),
new SolidColorBrush(Colors.Orange),
new SolidColorBrush(Colors.Red),
new SolidColorBrush(Colors.Red),
};
```
---
## 6. 成功阈值
展示部分完成的成功段：
```xml
```
---
## 7. 端点样式（StrokeLineCap）
```xml
```
---
## 8. 自定义渐变颜色
```xml
```
---
## 9. 圆形/仪表盘步进段
圆形和仪表盘进度条支持分段显示：
```xml
```
---
## 10. 自定义文字格式
```xml
```
`ProgressTextFormat` 使用 C# 标准格式化字符串，`{0}` 为当前百分比值。
---
## 11. 百分比标签位置
### ProgressBar 内外标签
```xml
```
### StepsProgressBar 标签位置
```xml
```
---
## 12. 垂直方向
ProgressBar 和 StepsProgressBar 支持垂直方向：
### 线形
```xml
```
### 步骤
```xml
```
---
## 13. 动态进度
通过数据绑定实现动态进度更新：
```xml
Sub
Add
```
---
## 14. 禁用状态
```xml
```
---
## 常见组合模式
### 文件上传进度
```xml
```
### 仪表板统计
```xml
```
### 步骤流程
```xml
```