syncfusion-winforms-progress-bar

Windows Forms 进度条（ProgressBarAdv）

Syncfusion Windows Forms ProgressBarAdv 控件可在安装、复制、打印和下载等耗时操作期间提供进度信息。它支持通过可自定义的文本格式、颜色、方向和视觉样式显示进度。

何时使用此技能

在以下情况下使用此技能：

• 显示进度信息，用于耗时操作（文件操作、安装、下载）
• 显示完成百分比或当前值与总值
• 实现加载指示器，并使用自定义文本和动画
• 创建进度条，并设置水平或垂直方向
• 自定义进度条外观，包括颜色、渐变、边框和图像
• 应用视觉主题（Office 2016、System、Tube、Gradient 样式）
• 处理进度事件（ValueChanged、自定义绘制）
• 在进度条上显示自定义文本（例如，“正在加载...”“正在处理...”）
• 跟踪耗时操作并提供视觉反馈

组件概述

主要功能：

• **文本格式：**显示百分比、值或自定义文本
• **进度图像：**使用图像指示进度
• **颜色自定义：**前景色、背景色、渐变色和边框颜色
• **方向：**水平或垂直进度条
• **视觉样式：**Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black、System、Tube、Gradient
• **事件：**ValueChanged、DrawWaitingCustomRender（用于自定义绘制）
• **主题：**通过 ThemesEnabled 属性支持内置主题

文档和导航指南

入门

📄 阅读：references/getting-started.md

在以下情况下阅读此参考文档：

• 通过 NuGet 或设计器安装 ProgressBarAdv 控件
• 将控件添加到 Windows Forms 项目
• 以编程方式创建 ProgressBarAdv 实例
• 设置基本属性（Value、Minimum、Maximum）
• 配置进度条的初始设置
• 了解程序集部署要求

文本和显示设置

📄 阅读：references/text-display.md

在以下情况下阅读此参考文档：

• 配置 TextStyle（Percentage、Value、Custom）
• 使用 CustomText 属性设置自定义文本
• 调整文本对齐方式（Left、Center、Right）
• 配置文本方向
• 自定义文本颜色和字体
• 实现显示格式模式

外观和样式

📄 阅读：references/appearance-styling.md

在以下情况下阅读此参考文档：

• 自定义前景色和渐变
• 设置背景色和图像
• 配置边框设置（样式、颜色、边）
• 添加进度图像
• 使用 ProgressStyle 选项
• 应用背景样式
• 实现颜色自定义模式

方向和布局

📄 阅读：references/orientation-layout.md

在以下情况下阅读此参考文档：

• 设置水平或垂直方向
• 配置进度条布局
• 处理尺寸和位置
• 实现响应式设计模式
• 适配不同的窗体布局

主题

📄 阅读：references/themes.md

在以下情况下阅读此参考文档：

• 使用 ThemesEnabled 启用主题支持
• 应用内置视觉样式（Office2016Colorful、Office2016White 等）
• 配置 ProgressStyle 选项
• 为应用选择合适的主题
• 了解主题选择指南

事件和高级自定义

📄 阅读：references/events-advanced.md

在以下情况下阅读此参考文档：

• 处理 ValueChanged 事件
• 实现 DrawWaitingCustomRender 事件
• 创建自定义绘制模式
• 使用 WaitingCustomRender 模式
• 配置 ProgressFallBackStyle 选项
• 实现高级自定义场景

快速入门

基本进度条

using Syncfusion.Windows.Forms.Tools;

// Create ProgressBarAdv instance
ProgressBarAdv progressBarAdv1 = new ProgressBarAdv();
progressBarAdv1.Location = new Point(20, 20);
progressBarAdv1.Size = new Size(300, 30);

// Set range and value
progressBarAdv1.Minimum = 0;
progressBarAdv1.Maximum = 100;
progressBarAdv1.Value = 60;

// Configure text display
progressBarAdv1.TextStyle = ProgressBarTextStyles.Percentage;
progressBarAdv1.TextAlignment = TextAlignment.Center;

// Apply visual style
progressBarAdv1.ProgressStyle = ProgressBarStyles.Office2016Colorful;

// Add to form
this.Controls.Add(progressBarAdv1);

常见模式

模式 1：百分比进度条

// Display progress as percentage
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 45;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

模式 2：自定义文本进度条

// Display custom text (e.g., "Loading...")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 30;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Loading files...";
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

模式 3：数值格式进度条

// Display current value out of maximum (e.g., "60/100")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 60;
progressBar.TextStyle = ProgressBarTextStyles.Value;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

模式 4：垂直进度条

// Create vertical progress bar
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressOrientation = Orientation.Vertical;
progressBar.Size = new Size(50, 200);
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 75;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;

this.Controls.Add(progressBar);

模式 5：自定义颜色的主题进度条

// Apply theme and custom colors
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 50;

// Custom colors
progressBar.ForeColor = Color.Blue;
progressBar.BackColor = Color.LightGray;

// Text settings
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

模式 6：带 ValueChanged 事件的进度条

// Create progress bar with event handling
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 0;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Starting...";

// Subscribe to ValueChanged event
progressBar.ValueChanged += ProgressBar_ValueChanged;

this.Controls.Add(progressBar);

// Event handler
private void ProgressBar_ValueChanged(object sender, EventArgs e)
{
    ProgressBarAdv pb = sender as ProgressBarAdv;
    if (pb.Value < 100)
    {
        pb.CustomText = $"Processing... {pb.Value}%";
    }
    else
    {
        pb.CustomText = "Complete!";
    }
}

模式 7：模拟长时间操作

// Simulate a long-running operation with progress updates
private async void StartOperation()
{
    ProgressBarAdv progressBar = new ProgressBarAdv();
    progressBar.Location = new Point(20, 20);
    progressBar.Size = new Size(400, 30);
    progressBar.Minimum = 0;
    progressBar.Maximum = 100;
    progressBar.Value = 0;
    progressBar.TextStyle = ProgressBarTextStyles.Percentage;
    progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;
    
    this.Controls.Add(progressBar);
    
    // Simulate operation
    for (int i = 0; i <= 100; i += 10)
    {
        progressBar.Value = i;
        await Task.Delay(500); // Simulate work
    }
    
    MessageBox.Show("Operation complete!");
}

关键属性

属性	类型	描述
Value	int	当前进度值
Minimum	int	最小进度值（默认值：0）
Maximum	int	最大进度值（默认值：100）
TextStyle	ProgressBarTextStyles	文本格式：百分比、数值、自定义
CustomText	string	要显示的自定义文本（当 TextStyle = Custom 时）
TextAlignment	TextAlignment	文本对齐方式：左对齐、居中、右对齐
ProgressOrientation	Orientation	水平或垂直方向
ProgressStyle	ProgressBarStyles	视觉样式：Office2016Colorful、Tube、Gradient 等
ThemesEnabled	bool	启用主题支持
ForeColor	Color	前景色／进度颜色
BackColor	Color	背景色
BackgroundStyle	ProgressBarBackgroundStyles	背景样式选项

关键事件

事件	描述
ValueChanged	Value 属性更改时触发
DrawWaitingCustomRender	允许自定义渲染等待渐变效果

文本格式选项

TextStyle	显示格式	示例
Percentage	显示百分比	"60%"
Value	显示数值／最大值	"60/100"
Custom	显示 CustomText	"Loading..."

视觉样式选项

ProgressStyle	描述
Office2016Colorful	带蓝色点缀的鲜艳 Office 2016 主题
Office2016White	简洁明亮的 Office 2016 主题
Office2016DarkGray	中深色 Office 2016 主题
Office2016Black	高对比度的深色 Office 2016 主题
System	标准 Windows 系统样式
Tube	管状进度指示器
Gradient	渐变进度效果