Back to Details

syncfusion-winforms-progress-bar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Windows Forms Progress Bar (ProgressBarAdv)

Windows Forms 进度条 (ProgressBarAdv)

The Syncfusion Windows Forms ProgressBarAdv control provides progress information during lengthy operations such as installation, copying, printing, and downloading. It displays progress with customizable text formats, colors, orientations, and visual styles.
Syncfusion Windows Forms ProgressBarAdv控件可在安装、复制、打印、下载等耗时操作中提供进度信息，支持自定义文本格式、颜色、方向和视觉样式来展示进度。

When to Use This Skill

本技能适用场景

Use this skill when you need to:
  • Display progress information for lengthy operations (file operations, installations, downloads)
  • Show percentage completion or current value out of total
  • Implement loading indicators with custom text and animations
  • Create progress bars with horizontal or vertical orientation
  • Customize progress appearance with colors, gradients, borders, and images
  • Apply visual themes (Office 2016, System, Tube, Gradient styles)
  • Handle progress events (ValueChanged, custom rendering)
  • Display custom text on progress bars (e.g., "Loading...", "Processing...")
  • Track time-consuming operations with visual feedback
当你需要实现以下需求时可使用本技能：
  • 为耗时操作（文件操作、安装、下载）展示进度信息
  • 展示完成百分比或当前值占总数值的比例
  • 实现带自定义文本和动画的加载指示器
  • 创建水平或垂直方向的进度条
  • 通过颜色、渐变、边框和图片自定义进度条外观
  • 应用视觉主题（Office 2016、System、Tube、渐变样式）
  • 处理进度事件（ValueChanged、自定义渲染）
  • 在进度条上展示自定义文本（如"Loading..."、"Processing..."）
  • 通过视觉反馈追踪耗时操作的执行情况

Component Overview

组件概述

Key Features:
  • Text formats: Percentage, Value, or Custom text display
  • Progress images: Use images for progress indication
  • Color customization: Foreground, background, gradient, and border colors
  • Orientation: Horizontal or vertical progress bars
  • Visual styles: Office2016Colorful, Office2016White, Office2016DarkGray, Office2016Black, System, Tube, Gradient
  • Events: ValueChanged, DrawWaitingCustomRender for custom rendering
  • Themes: Built-in theme support with ThemesEnabled property
核心特性：
  • 文本格式： 支持百分比、数值、自定义文本展示
  • 进度图片： 可使用图片作为进度指示器
  • 颜色自定义： 支持前景色、背景色、渐变色和边框颜色设置
  • 方向： 支持水平或垂直进度条
  • 视觉样式： Office2016Colorful、Office2016White、Office2016DarkGray、Office2016Black、System、Tube、Gradient
  • 事件： ValueChanged、用于自定义渲染的DrawWaitingCustomRender
  • 主题： 通过ThemesEnabled属性支持内置主题

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md
Read this reference when you need to:
  • Install the ProgressBarAdv control via NuGet or designer
  • Add the control to a Windows Forms project
  • Create a ProgressBarAdv instance programmatically
  • Set basic properties (Value, Minimum, Maximum)
  • Configure initial progress bar setup
  • Understand assembly deployment requirements
📄 阅读： references/getting-started.md
当你需要实现以下需求时可阅读该参考文档：
  • 通过NuGet或设计器安装ProgressBarAdv控件
  • 将控件添加到Windows Forms项目中
  • 通过代码创建ProgressBarAdv实例
  • 设置基础属性（Value、Minimum、Maximum）
  • 完成进度条初始配置
  • 了解程序集部署要求

Text and Display Settings

文本与显示设置

📄 Read: references/text-display.md
Read this reference when you need to:
  • Configure TextStyle (Percentage, Value, Custom)
  • Set custom text with CustomText property
  • Adjust text alignment (Left, Center, Right)
  • Configure text orientation
  • Customize text color and font
  • Implement display format patterns
📄 阅读： references/text-display.md
当你需要实现以下需求时可阅读该参考文档：
  • 配置TextStyle（百分比、数值、自定义）
  • 通过CustomText属性设置自定义文本
  • 调整文本对齐方式（左对齐、居中、右对齐）
  • 配置文本方向
  • 自定义文本颜色和字体
  • 实现展示格式规则

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md
Read this reference when you need to:
  • Customize foreground colors and gradients
  • Set background colors and images
  • Configure border settings (style, color, sides)
  • Add progress images
  • Use ProgressStyle options
  • Apply background styles
  • Implement color customization patterns
📄 阅读： references/appearance-styling.md
当你需要实现以下需求时可阅读该参考文档：
  • 自定义前景色和渐变效果
  • 设置背景色和背景图片
  • 配置边框设置（样式、颜色、边框边）
  • 添加进度图片
  • 使用ProgressStyle选项
  • 应用背景样式
  • 实现颜色自定义规则

Orientation and Layout

方向与布局

📄 Read: references/orientation-layout.md
Read this reference when you need to:
  • Set horizontal or vertical orientation
  • Configure progress bar layout
  • Handle size and positioning
  • Implement responsive design patterns
  • Adjust for different form layouts
📄 阅读： references/orientation-layout.md
当你需要实现以下需求时可阅读该参考文档：
  • 设置水平或垂直方向
  • 配置进度条布局
  • 处理尺寸和定位
  • 实现响应式设计规则
  • 适配不同的窗体布局

Themes

主题

📄 Read: references/themes.md
Read this reference when you need to:
  • Enable theme support with ThemesEnabled
  • Apply built-in visual styles (Office2016Colorful, Office2016White, etc.)
  • Configure ProgressStyle options
  • Choose appropriate themes for your application
  • Understand theme selection guidelines
📄 阅读： references/themes.md
当你需要实现以下需求时可阅读该参考文档：
  • 通过ThemesEnabled开启主题支持
  • 应用内置视觉样式（Office2016Colorful、Office2016White等）
  • 配置ProgressStyle选项
  • 为你的应用选择合适的主题
  • 了解主题选择指南

Events and Advanced Customization

事件与高级自定义

📄 Read: references/events-advanced.md
Read this reference when you need to:
  • Handle ValueChanged event
  • Implement DrawWaitingCustomRender event
  • Create custom rendering patterns
  • Use WaitingCustomRender mode
  • Configure ProgressFallBackStyle options
  • Implement advanced customization scenarios
📄 阅读： references/events-advanced.md
当你需要实现以下需求时可阅读该参考文档：
  • 处理ValueChanged事件
  • 实现DrawWaitingCustomRender事件
  • 创建自定义渲染规则
  • 使用WaitingCustomRender模式
  • 配置ProgressFallBackStyle选项
  • 实现高级自定义场景

Quick Start

快速上手

Basic Progress Bar

基础进度条

csharp
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);
csharp
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);

Common Patterns

常用场景示例

Pattern 1: Percentage Progress Bar

场景1：百分比进度条

csharp
// 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);
csharp
// 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);

Pattern 2: Custom Text Progress Bar

场景2：自定义文本进度条

csharp
// 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);
csharp
// 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);

Pattern 3: Value Format Progress Bar

场景3：数值格式进度条

csharp
// 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);
csharp
// 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);

Pattern 4: Vertical Progress Bar

场景4：垂直进度条

csharp
// 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);
csharp
// 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);

Pattern 5: Themed Progress Bar with Custom Colors

场景5：带自定义颜色的主题进度条

csharp
// 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);
csharp
// 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);

Pattern 6: Progress Bar with ValueChanged Event

场景6：带ValueChanged事件的进度条

csharp
// 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!";
    }
}
csharp
// 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!";
    }
}

Pattern 7: Simulated Long Operation

场景7：模拟耗时操作

csharp
// 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!");
}
csharp
// 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!");
}

Key Properties

核心属性

PropertyTypeDescription
Value
int
Current progress value
Minimum
int
Minimum progress value (default: 0)
Maximum
int
Maximum progress value (default: 100)
TextStyle
ProgressBarTextStyles
Text format: Percentage, Value, Custom
CustomText
string
Custom text to display (when TextStyle = Custom)
TextAlignment
TextAlignment
Text alignment: Left, Center, Right
ProgressOrientation
Orientation
Horizontal or Vertical orientation
ProgressStyle
ProgressBarStyles
Visual style: Office2016Colorful, Tube, Gradient, etc.
ThemesEnabled
bool
Enable theme support
ForeColor
Color
Foreground/progress color
BackColor
Color
Background color
BackgroundStyle
ProgressBarBackgroundStyles
Background style options
属性类型描述
Value
int
当前进度值
Minimum
int
最小进度值（默认：0）
Maximum
int
最大进度值（默认：100）
TextStyle
ProgressBarTextStyles
文本格式：Percentage、Value、Custom
CustomText
string
要展示的自定义文本（当TextStyle = Custom时生效）
TextAlignment
TextAlignment
文本对齐方式：Left、Center、Right
ProgressOrientation
Orientation
水平或垂直方向
ProgressStyle
ProgressBarStyles
视觉样式：Office2016Colorful、Tube、Gradient等
ThemesEnabled
bool
是否启用主题支持
ForeColor
Color
前景/进度颜色
BackColor
Color
背景色
BackgroundStyle
ProgressBarBackgroundStyles
背景样式选项

Key Events

核心事件

EventDescription
ValueChanged
Occurs when the Value property changes
DrawWaitingCustomRender
Allows custom rendering of waiting gradient
事件描述
ValueChanged
Value属性变更时触发
DrawWaitingCustomRender
支持等待渐变的自定义渲染

Text Format Options

文本格式选项

TextStyleDisplay FormatExample
Percentage
Shows percentage"60%"
Value
Shows value/max"60/100"
Custom
Shows CustomText"Loading..."
TextStyle展示格式示例
Percentage
展示百分比"60%"
Value
展示值/最大值"60/100"
Custom
展示CustomText"Loading..."

Visual Style Options

视觉样式选项

ProgressStyleDescription
Office2016Colorful
Vibrant Office 2016 theme with blue accents
Office2016White
Clean, light Office 2016 theme
Office2016DarkGray
Medium-dark Office 2016 theme
Office2016Black
High-contrast dark Office 2016 theme
System
Standard Windows system style
Tube
Tube-style progress indicator
Gradient
Gradient progress effect
ProgressStyle描述
Office2016Colorful
带蓝色点缀的活力Office 2016主题
Office2016White
简洁浅色Office 2016主题
Office2016DarkGray
中等深度Office 2016深色主题
Office2016Black
高对比度深色Office 2016主题
System
标准Windows系统样式
Tube
管状进度指示器
Gradient
渐变进度效果

Related Components

相关组件

  • Badge - For status indicators and notifications
  • Toast - For temporary notification messages
  • Skeleton - For loading state placeholders
  • StatusBarAdv - For application status information
  • Badge - 用于状态指示器和通知
  • Toast - 用于临时通知消息
  • Skeleton - 用于加载状态占位
  • StatusBarAdv - 用于展示应用状态信息