对于Qt：QProgressBar常见属性的解析

ShineWinsu2026-11-02 8:32

开篇介绍：

hello 大家，本篇博客我们来学习QProgressBar常见属性

在 Qt 界面开发中，我们经常会遇到一些 "耗时任务"------ 比如下载一个大文件、加载大量数据、安装一个软件、导出一份报表。在这些场景下，用户最需要的是什么？是反馈------ 他们需要知道 "任务进行到哪了""还要多久才能完成"，而不是面对一个毫无反应的界面干着急。

为了满足这个需求，Qt 专门为我们提供了一个核心控件：QProgressBar（进度条控件）。QProgressBar 是界面中反馈任务进度的关键组件，它可以用可视化的色块展示任务完成度，还可以配合文本显示百分比、当前值，让用户对任务进度一目了然。

很多新手刚接触 QProgressBar 时，会觉得它很简单 ------ 不就是设个最小值、最大值，再设个当前值吗？但用起来才发现，它还有很多实用的属性：比如可以让进度条垂直显示、反向增长、自定义文本格式、隐藏文本、甚至在未知进度时显示 "繁忙模式"（色块来回滚动）。更重要的是，千万不要把类名拼错！ 是 QProgressBar（Progress = 进度），不是 QProcessBar（Process = 进程）------ 这个拼写错误新手几乎都会犯，一定要牢记！

别担心！这篇文章我会结合 QProgressBar 的所有核心属性（minimum、maximum、value、orientation、invertAppearance、textVisible、alignment、textDirection、format）进行解析

我们还会讲如何用样式表自定义进度条颜色，以及如何结合 QTimer 实现一个定时增长的进度条。

话不多说，我们正式开始！

第一章 先搞懂基础：QProgressBar 的定位与拼写警告

在讲具体属性之前，我们必须先搞懂两个最基础、最重要的问题：QProgressBar 是用来做什么的？以及，它的类名怎么拼才对？

1.1 QProgressBar 的核心定位

QProgressBar 是 Qt 中用于可视化展示任务进度的核心控件，主要用于展示耗时任务的完成进度（如文件下载、数据加载、安装流程、文件导出等）。

通俗理解：QLabel 是 "告示牌"，用来显示文字；QLCDNumber 是 "液晶计算器屏幕"，用来显示数字；而 QProgressBar 就是 "进度指示器"------ 它用一个 "填充色块" 的方式，直观地告诉你 "任务完成了多少"，比如填充了一半，就是完成了 50%；填充完了，就是任务完成了。

QProgressBar 支持很多自定义功能：你可以自定义进度范围（比如 0-100，或者 0-500）、可以让进度条水平或垂直显示、可以让进度反向增长、可以自定义上面的文本格式（显示百分比、当前值）、可以隐藏文本、甚至在不知道任务还要多久完成时，让进度条进入 "繁忙模式"（色块来回滚动，告诉用户 "我在干活，只是不知道还要多久"）。

1.2 重要！重要！重要！拼写警告

这里有一个新手几乎 100% 会踩的坑，必须放在最前面、用最大的字号提醒你：

类名是 QProgressBar，不是 QProcessBar！ Progress（进度），不是 Process（进程）！

为什么会拼错？因为 "Process（进程）" 这个词我们见得太多了，而 "Progress（进度）" 稍微少一点，所以手一滑就写成了 QProcessBar------ 但 Qt 里根本没有 QProcessBar 这个类，只有 QProgressBar 和 QProcess（后者是用来启动外部进程的，和进度条完全没关系）。

如果你写成了 QProcessBar，编译时会报错说 "'QProcessBar': 未声明的标识符"，这时候一定要检查拼写 ------ 把 Process 改成 Progress 就好了。这个错误虽然低级，但真的太常见了，一定要牢记！

第二章 QProgressBar 核心属性详解（上）：范围与值属性（minimum、maximum、value）

QProgressBar 的核心功能是展示 "进度"，而 "进度" 首先得有一个 "范围" 和一个 "当前值"------ 比如 "从 0 到 100，当前是 50"，就是完成了 50%。Qt 为 QProgressBar 提供了三个核心属性来控制范围和值：minimum（最小值）、maximum（最大值）、value（当前值）。这三个属性是 QProgressBar 最基础、最常用的属性，我们先从它们讲起。

2.1 属性一：minimum（最小值）------ 进度范围的起点

2.1.1 属性的核心定义

minimum 属性用于定义 QProgressBar 进度范围的下限值，也就是进度的 "起点"，默认值为 0。

通俗理解：minimum 就像 "跑步的起跑线"------ 你从 0 米开始跑，0 就是最小值；如果你从 10 米开始跑，10 就是最小值。

这里有一个非常重要的规则：最小值必须小于等于最大值 ------ 如果你不小心手动设置了最小值大于最大值（比如 setMinimum(100)，setMaximum(0)），Qt 不会报错，而是会自动交换二者 ，确保范围合法（变成 minimum=0，maximum=100）。

另外，minimum 还是计算进度百分比（%p）的核心基准之一 ------ 百分比的计算公式是：

百分比 = (当前值 - 最小值) / (最大值 - 最小值) × 100（当最大值 ≠ 最小值时）

比如最小值是 0，最大值是 100，当前值是 50，百分比就是 (50-0)/(100-0)×100 = 50%；如果最小值是 10，最大值是 110，当前值是 60，百分比也是 (60-10)/(110-10)×100 = 50%------ 所以百分比只和 "相对位置" 有关，和 "绝对数值" 无关。

2.1.2 数据类型

int 类型，整数（常规场景建议设为非负数，无强制限制），默认值为 0。

2.1.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前最小值：int minimum () const

函数原型：

复制代码 
int QProgressBar::minimum() const;

逐词逐句底层解析：

  • int：返回值类型，返回当前设置的进度条最小值；
  • QProgressBar::：说明这个函数是 QProgressBar 类的成员函数，只能用 QProgressBar 对象调用；
  • minimum()：函数名，很直观，就是 "获取最小值" 的意思；
  • const：说明这个函数是常成员函数 ------ 它只会读取 QProgressBar 的最小值，不会修改任何状态，所以你可以在 const 的成员函数里调用它。

返回值说明：

  • 返回 int 类型的整数，默认返回 0（未设置时）。

调用示例：

复制代码 
// 获取当前设置的最小值
int minVal = ui->progressBar->minimum();
// 打印出来验证
qDebug() << "当前进度条最小值：" << minVal;
2. 设置最小值：void setMinimum (int min)

函数原型：

复制代码 
void QProgressBar::setMinimum(int min);

逐词逐句底层解析：

  • void：函数没有返回值，只是执行 "设置最小值" 的操作；
  • QProgressBar::：成员函数；
  • setMinimum()：函数名，"设置最小值" 的意思；
  • int min：入参，min 是要设置的最小值（整数）。

参数说明：

  • min：要设置的最小值，int 类型；
  • 常规场景建议设为 0（默认值），符合大多数人的习惯；
  • 如果你设置的 min 大于当前的 maximum，Qt 会自动交换二者，确保范围合法。

生效规则：

  • 调用后立即生效；
  • 修改最小值后，当前的 value（当前值）会自动适配新范围（比如原范围 0-100、value=50，改为 10-110 后，value 仍为 50，对应 40%）。

调用示例：

复制代码 
// 示例1：设置最小值为 0（默认值，常规场景）
ui->progressBar->setMinimum(0);

// 示例2：自定义最小值为 10（需配合 maximum > 10）
ui->progressBar->setMinimum(10);
ui->progressBar->setMaximum(110); // 最大值设为 110，确保范围合法

2.2 属性二：maximum（最大值）------ 进度范围的终点（含繁忙模式详解）

2.2.1 属性的核心定义

maximum 属性用于定义 QProgressBar 进度范围的上限值，也就是进度的 "终点"，默认值为 100。

通俗理解：maximum 就像 "跑步的终点线"------ 你要跑到 100 米，100 就是最大值；你要跑到 500 米，500 就是最大值。

这里有一个非常重要、非常实用的特殊规则，必须单独拿出来讲：

如果将最大值设为 0，进度条会进入「繁忙模式」（Indeterminate Mode）！

什么是 "繁忙模式"？通俗理解就是 ------"我不知道任务还要多久完成，但我确实在干活"。在繁忙模式下，进度条不会显示具体的进度值，而是有一个色块在进度条里来回滚动，告诉用户 "程序没卡死，正在处理中，请耐心等待"。

繁忙模式的适用场景非常多：比如网络请求（不知道服务器多久响应）、文件扫描（不知道文件数量多少）、复杂计算（不知道计算量多大）------ 只要是 "未知耗时" 的任务，都可以用繁忙模式。

除了繁忙模式，正常模式下（maximum > minimum），需保证最大值 ≥ 最小值，否则 Qt 会自动交换二者。

2.2.2 数据类型

int 类型，整数，默认值为 100；设为 0 进入繁忙模式。

2.2.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前最大值：int maximum () const

函数原型：

复制代码 
int QProgressBar::maximum() const;

逐词逐句底层解析：

  • int：返回值类型，返回当前设置的进度条最大值；
  • QProgressBar::：成员函数；
  • maximum()：函数名，"获取最大值" 的意思；
  • const：常成员函数。

返回值说明：

  • 返回 int 类型的整数，默认返回 100（未设置时）；
  • 返回 0 表示当前是繁忙模式。

调用示例：

复制代码 
// 获取当前设置的最大值
int maxVal = ui->progressBar->maximum();
if (maxVal == 0) {
    qDebug() << "当前是繁忙模式";
} else {
    qDebug() << "当前进度条最大值：" << maxVal;
}
2. 设置最大值：void setMaximum (int max)

函数原型：

复制代码 
void QProgressBar::setMaximum(int max);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setMaximum()：函数名，"设置最大值" 的意思；
  • int max：入参，max 是要设置的最大值（整数）。

参数说明：

  • max：要设置的最大值，int 类型；
  • 设为 0 进入繁忙模式（未知进度，色块滚动）；
  • 设为 > minimum 的值进入正常模式（已知进度，显示具体值）；
  • 如果你设置的 max 小于当前的 minimum，Qt 会自动交换二者。

生效规则：

  • 调用后立即生效；
  • 从正常模式切换到繁忙模式：value 属性失效（设置无效果），进度条开始滚动；
  • 从繁忙模式切换到正常模式：value 属性恢复生效，进度条显示具体值。

调用示例：

复制代码 
// 示例1：正常模式：进度范围 0-100（百分比进度，最常用）
ui->progressBar->setMinimum(0);
ui->progressBar->setMaximum(100);

// 示例2：繁忙模式：未知进度，进度条滚动
ui->progressBar->setMaximum(0); // 开启繁忙模式
ui->progressBar->setTextVisible(false); // 繁忙模式下通常隐藏文本

// 示例3：自定义范围：0-500（适用于大任务量进度，比如文件总大小 500KB）
ui->progressBar->setMinimum(0);
ui->progressBar->setMaximum(500);

2.3 属性三：value（当前值）------ 进度条的核心，更新进度就靠它

2.3.1 属性的核心定义

value 属性表示 QProgressBar 当前的进度位置，是更新进度的核心属性------ 我们要让进度条往前走，就是靠修改这个属性。

value 的取值范围严格限制在 [minimum, maximum] 之间：

  • 如果你设置的值小于 minimum，Qt 会自动把它截断为 minimum；
  • 如果你设置的值大于 maximum，Qt 会自动把它截断为 maximum；
  • 当 value 等于 maximum 时，代表任务 100% 完成。

这里有几个非常重要的规则，必须牢记：

  1. 繁忙模式下失效 ：如果 maximum=0（繁忙模式），setValue() 没有任何效果 ------ 进度条只会滚动，不会显示具体值；
  2. 自动截断：超出范围的值会被自动截断，不会报错；
  3. 百分比计算 ：百分比基于 (value - minimum)/(maximum - minimum) × 100 计算，和 maximum 是否为 100 无关。
2.3.2 数据类型

int 类型，整数，默认值为 0。

2.3.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前进度值：int value () const

函数原型：

复制代码 
int QProgressBar::value() const;

逐词逐句底层解析：

  • int：返回值类型，返回当前的进度值；
  • QProgressBar::：成员函数；
  • value()：函数名，"获取当前值" 的意思；
  • const：常成员函数。

返回值说明：

  • 返回 int 类型的整数，默认返回 0（未设置时）；
  • 繁忙模式下返回 0（但无实际意义）。

调用示例：

复制代码 
// 获取当前进度值
int currentVal = ui->progressBar->value();
// 打印出来验证
qDebug() << "当前进度值：" << currentVal;
2. 设置当前进度值：void setValue (int val)

函数原型：

复制代码 
void QProgressBar::setValue(int val);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setValue()：函数名，"设置当前值" 的意思 ------这是更新进度的核心方法！
  • int val：入参，val 是要设置的当前进度值（整数）。

参数说明：

  • val：要设置的当前进度值，int 类型；
  • 超出 [minimum, maximum] 范围的值会被自动截断（小于 minimum 取 minimum，大于 maximum 取 maximum）；
  • 繁忙模式下（maximum=0），调用此函数无任何效果。

生效规则：

  • 调用后立即生效，进度条的色块会立即更新到对应位置；
  • 如果 textVisible 为 true，文本也会立即更新。

调用示例：

复制代码 
// 先设置常规进度范围
ui->progressBar->setMinimum(0);
ui->progressBar->setMaximum(100);

// 示例1：设置当前进度为 50（对应 50%）
ui->progressBar->setValue(50);

// 示例2：超出最大值，自动截断为 100
ui->progressBar->setValue(120); // 实际 value 为 100

// 示例3：低于最小值，自动截断为 0
ui->progressBar->setValue(-10); // 实际 value 为 0
2.3.4 典型代码示例（两个实用场景，一看就懂）
示例一：验证范围与自动截断规则

这个场景可以直观地看到范围设置和自动截断的效果：

复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>
#include <QDebug>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    QProgressBar *progressBar = new QProgressBar(this);
    progressBar->setGeometry(100, 100, 400, 30);
    progressBar->setTextVisible(true);
    progressBar->setFormat("%p%"); // 显示百分比

    // 1. 常规范围：0-100
    progressBar->setMinimum(0);
    progressBar->setMaximum(100);
    progressBar->setValue(50);
    qDebug() << "=== 范围 0-100，setValue(50) ===";
    qDebug() << "value:" << progressBar->value(); // 输出 50
    qDebug() << "百分比:" << (progressBar->value() - progressBar->minimum()) * 100 / (progressBar->maximum() - progressBar->minimum()) << "%"; // 输出 50%

    // 2. 测试超出最大值：自动截断
    progressBar->setValue(120);
    qDebug() << "=== setValue(120)（超出最大值）===";
    qDebug() << "value:" << progressBar->value(); // 输出 100（自动截断）

    // 3. 测试低于最小值：自动截断
    progressBar->setValue(-10);
    qDebug() << "=== setValue(-10)（低于最小值）===";
    qDebug() << "value:" << progressBar->value(); // 输出 0（自动截断）

    // 4. 测试繁忙模式：setValue 失效
    progressBar->setMaximum(0); // 切换到繁忙模式
    progressBar->setValue(50); // 繁忙模式下调用 setValue 无效果
    qDebug() << "=== 切换到繁忙模式，setValue(50) ===";
    qDebug() << "value:" << progressBar->value(); // 输出 0（无实际意义，进度条仅滚动）
}

Widget::~Widget()
{
    delete ui;
}
示例二：文件下载进度模拟（自定义范围）

这个场景模拟了文件下载进度，总大小 1024KB，当前下载 512KB：

复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>
#include <QDebug>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    QProgressBar *progressBar = new QProgressBar(this);
    progressBar->setGeometry(100, 100, 400, 30);
    progressBar->setTextVisible(true);

    // 场景：文件下载，总大小 1024KB，当前下载 512KB
    progressBar->setMinimum(0); // 起始值 0（未开始下载）
    progressBar->setMaximum(1024); // 总大小 1024KB
    progressBar->setValue(512); // 当前下载 512KB

    // 自定义文本格式：显示"已下载 512/1024 KB"
    progressBar->setFormat("已下载 %v/1024 KB");

    // 手动计算百分比验证
    int percentage = (progressBar->value() - progressBar->minimum()) * 100 / (progressBar->maximum() - progressBar->minimum());
    qDebug() << "当前下载进度：" << percentage << "%"; // 输出 50%
}

Widget::~Widget()
{
    delete ui;
}

三属性示例代码：

cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK，那么本文件我们就来学习QProgressBar的minimum属性、maxmum属性、value属性
    //那么起那两个是很简单的，就是定义进度条可显示的进度下限值以及上限值
    //真正重要的是value属性，该属性表示进度条当前的进度位置，取值严格限制在 [minimum, maximum] 区间内；
    //我们要更新进度条的进度就是通过修改该value属性的哦~~~
    //这个要注意

    /**
     * @property QProgressBar::minimum
     * @brief QProgressBar进度范围的最小值属性
     * @details 该属性定义进度条可显示的进度下限值，是进度范围的起始点，默认值为0；
     *          设置时需保证最小值 ≤ 最大值（若手动设置最小值大于最大值，Qt会自动交换二者，确保范围合法）；
     *          该属性是计算进度百分比（%p）的核心基准之一（百分比 = (value - minimum)/(maximum - minimum) × 100）。
     *
     * 【关联API详解】
     * 1. int minimum() const
     *    - 功能：获取当前设置的进度条最小值
     *    - 返回值：int类型，默认返回0
     *    - 调用示例：
     *      int minVal = ui->progressBar->minimum(); // 读取最小值
     *
     * 2. void setMinimum(int min)
     *    - 功能：设置进度条最小值
     *    - 参数：min - 整数（常规场景建议设为非负数，无强制限制）
     *    - 示例：
     *      ui->progressBar->setMinimum(0); // 常规进度范围起始（默认）
     *      ui->progressBar->setMinimum(10); // 自定义起始值（需配合maximum>10）
     *
     * ===================================== 属性2：maximum =====================================
     * @property QProgressBar::maximum
     * @brief QProgressBar进度范围的最大值属性
     * @details 该属性定义进度条可显示的进度上限值，是进度范围的终点，默认值为100；
     *          核心特殊规则：若将最大值设为0，进度条会进入**繁忙模式**（Indeterminate Mode）------ 无具体进度值，进度色块来回滚动，适用于未知耗时的任务（如网络加载、文件扫描）；
     *          正常模式下需保证最大值 ≥ 最小值，否则Qt自动交换二者。
     *
     * 【关联API详解】
     * 1. int maximum() const
     *    - 功能：获取当前设置的进度条最大值
     *    - 返回值：int类型，默认返回100
     *    - 调用示例：
     *      int maxVal = ui->progressBar->maximum(); // 读取最大值
     *
     * 2. void setMaximum(int max)
     *    - 功能：设置进度条最大值，控制进度范围/模式
     *    - 参数：max - 整数（设为0进入繁忙模式，>minimum为正常模式）
     *    - 示例：
     *      // 正常模式：进度范围0-100（百分比进度）
     *      ui->progressBar->setMaximum(100);
     *      // 繁忙模式：未知进度，进度条滚动
     *      ui->progressBar->setMaximum(0);
     *      // 自定义范围：0-500（适用于大任务量进度）
     *      ui->progressBar->setMaximum(500);
     *
     * ===================================== 属性3：value =====================================
     * @property QProgressBar::value
     * @brief QProgressBar的当前进度值属性
     * @details 该属性表示进度条当前的进度位置，取值严格限制在 [minimum, maximum] 区间内；
     *          若设置的值超出该区间，Qt会自动截断（小于minimum取minimum，大于maximum取maximum）；
     *          繁忙模式下（maximum=0），该属性失效（设置无效果，进度条无固定值）；
     *          当value等于maximum时，代表任务100%完成。
     *
     * 【关联API详解】
     * 1. int value() const
     *    - 功能：获取当前进度值
     *    - 返回值：int类型，默认返回0
     *    - 调用示例：
     *      int currentVal = ui->progressBar->value(); // 读取当前进度
     *
     * 2. void setValue(int val)
     *    - 功能：设置当前进度值，是更新进度的核心方法
     *    - 参数：val - 整数，超出[minimum, maximum]会被自动截断
     *    - 示例：
     *      // 先设置常规进度范围
     *      ui->progressBar->setMinimum(0);
     *      ui->progressBar->setMaximum(100);
     *      // 设置当前进度为50（对应50%）
     *      ui->progressBar->setValue(50);
     *      // 超出最大值，自动截断为100
     *      ui->progressBar->setValue(120);
     *      // 低于最小值，自动截断为0
     *      ui->progressBar->setValue(-10);
     *
     * 【核心关联规则（必知）】
     * 1. 进度百分比计算：%p = (value - minimum) / (maximum - minimum) × 100（maximum≠minimum）；
     * 2. 繁忙模式：maximum=0时，setValue()无任何效果，进度条仅滚动不显示具体值；
     * 3. 范围修改：修改minimum/maximum后，当前value会自动适配新范围（如原0-100、value=50，改为0-200后value仍为50，对应25%）。
     *
     * 【典型组合示例】
     * // 场景：文件下载进度（总大小1024KB，当前下载512KB）
     * ui->progressBar->setMinimum(0); // 起始值0
     * ui->progressBar->setMaximum(1024); // 总大小1024KB
     * ui->progressBar->setValue(512); // 当前下载512KB（对应50%）
     * qDebug() << "当前进度百分比：" << (ui->progressBar->value() - ui->progressBar->minimum()) * 100 / (ui->progressBar->maximum() - ui->progressBar->minimum()) << "%";
     */

    QProgressBar* progressbar=new QProgressBar(this);

    progressbar->setMaximum(100);

    progressbar->setMinimum(0);

    progressbar->setValue(50);
}

Widget::~Widget()
{
    delete ui;
}

第三章 QProgressBar 核心属性详解（中）：视觉布局属性（orientation、invertAppearance）

讲完了范围和值属性，我们再讲两个控制进度条视觉布局 的属性：orientation（显示方向）和 invertAppearance（反向增长）。这两个属性可以让进度条水平或垂直显示，还可以让进度反向增长（比如从右到左、从上到下），非常灵活。

3.1 属性四：orientation（显示方向）------ 水平还是垂直？

3.1.1 属性的核心定义

orientation 属性用于控制 QProgressBar 的整体展示方向是水平 还是垂直 ，默认值为 Qt::Horizontal（水平）。

通俗理解：orientation 就像 "进度条的摆放方向"------ 你可以把它横着放（水平），也可以把它竖着放（垂直）。

这里有几个点需要注意：

  1. 方向仅改变视觉布局 ：不影响 value、minimum、maximum 的数值计算 ------ 不管是水平还是垂直，50% 就是 50%；
  2. 垂直进度条需调整高度 ：垂直进度条如果高度太小，视觉效果不明显，建议用 setFixedHeight() 设置足够的高度；
  3. 联动 invertAppearance ：方向切换后，invertAppearance（反向增长）的逻辑会自动适配新方向 ------ 我们后面会讲。
3.1.2 数据类型

Qt::Orientation 枚举类型，包含两个常用值：

  • Qt::Horizontal：水平方向（默认）；
  • Qt::Vertical：垂直方向。
3.1.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前显示方向：Qt::Orientation orientation () const

函数原型：

复制代码 
Qt::Orientation QProgressBar::orientation() const;

逐词逐句底层解析：

  • Qt::Orientation：返回值类型，返回当前的显示方向；
  • QProgressBar::：成员函数；
  • orientation()：函数名，"获取显示方向" 的意思；
  • const：常成员函数。

返回值说明：

  • 返回 Qt::Horizontal（水平）或 Qt::Vertical（垂直）；
  • 默认返回 Qt::Horizontal。

调用示例：

复制代码 
Qt::Orientation orient = ui->progressBar->orientation();
if (orient == Qt::Horizontal) {
    qDebug() << "当前是水平进度条";
} else {
    qDebug() << "当前是垂直进度条";
}
2. 设置显示方向：void setOrientation (Qt::Orientation orient)

函数原型：

复制代码 
void QProgressBar::setOrientation(Qt::Orientation orient);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setOrientation()：函数名，"设置显示方向" 的意思；
  • Qt::Orientation orient：入参，orient 是方向枚举值（Horizontal/Vertical）。

参数说明：

  • orient：Qt::Horizontal（水平）或 Qt::Vertical（垂直）；
  • 垂直进度条建议配合 setFixedHeight() 设置足够的高度，否则视觉效果不明显。

生效规则：

  • 调用后立即生效，进度条的布局会立即切换；
  • invertAppearance 的反向增长逻辑会自动适配新方向。

调用示例：

复制代码 
// 示例1：水平进度条（默认，最常用）
ui->progressBar->setOrientation(Qt::Horizontal);

// 示例2：垂直进度条（需设置足够的高度）
ui->progressBar->setOrientation(Qt::Vertical);
ui->progressBar->setFixedHeight(200); // 设置垂直进度条高度为 200 像素

3.2 属性五：invertAppearance（反向增长）------ 从左到右还是从右到左？

3.2.1 属性的核心定义

invertAppearance 属性用于控制 QProgressBar 的色块填充方向是否反向 ，默认值为 false（正向增长）。

通俗理解：invertAppearance 就像 "进度条的填充方向开关"------ 如果关闭（false，正向），水平进度条从左到右填充，垂直进度条从下到上填充；如果开启（true，反向），水平进度条从右到左填充，垂直进度条从上到下填充。

这里有一个非常重要的点：反向增长仅改变视觉填充方向，不影响数值计算 ------ 不管是从左到右还是从右到左，value=50 就是 50%，百分比计算完全不受影响。

3.2.2 不同方向下的增长规则（核心，必知）

为了让你更清楚地理解正向和反向的效果，我做了一个对比表格：

表格

进度条方向 正向增长（invertAppearance=false） 反向增长（invertAppearance=true）
水平（Horizontal） 进度色块从左向右填充（默认） 进度色块从右向左填充
垂直（Vertical） 进度色块从下向上填充（默认） 进度色块从上向下填充

这个规则一定要牢记 ------ 水平和垂直的正向 / 反向是不一样的，垂直正向是从下到上，不是从上到下！

3.2.3 数据类型

bool 类型，false 表示正向增长（默认），true 表示反向增长。

3.2.4 关联 API 详解（逐词逐句，零模糊）
1. 获取是否开启反向增长：bool invertAppearance () const

函数原型：

复制代码 
bool QProgressBar::invertAppearance() const;

逐词逐句底层解析：

  • bool：返回值类型，返回是否开启反向增长；
  • QProgressBar::：成员函数；
  • invertAppearance()：函数名，"获取是否反向增长" 的意思；
  • const：常成员函数。

返回值说明：

  • false 表示正向增长（默认），true 表示反向增长。

调用示例：

复制代码 
bool isInvert = ui->progressBar->invertAppearance();
if (isInvert) {
    qDebug() << "当前是反向增长";
} else {
    qDebug() << "当前是正向增长";
}
2. 设置是否开启反向增长：void setInvertAppearance (bool invert)

函数原型：

复制代码 
void QProgressBar::setInvertAppearance(bool invert);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setInvertAppearance()：函数名，"设置是否反向增长" 的意思；
  • bool invert：入参，invert 是 true 开启反向，false 关闭反向。

参数说明：

  • invert：true 开启反向增长，false 关闭反向增长（默认）；
  • 开启后，进度色块会立即切换填充方向，无需刷新。

生效规则：

  • 调用后立即生效，当前进度色块会立即切换填充方向；
  • 仅改变视觉效果，value 的数值大小和百分比计算不受任何影响；
  • 繁忙模式下（maximum=0），反向属性会改变滚动色块的移动方向。

调用示例：

复制代码 
// 示例1：水平进度条反向增长（从右到左填充）
ui->progressBar->setOrientation(Qt::Horizontal);
ui->progressBar->setInvertAppearance(true);
ui->progressBar->setValue(50); // 右侧 50% 区域填充色块

// 示例2：垂直进度条反向增长（从上到下填充）
ui->progressBar->setOrientation(Qt::Vertical);
ui->progressBar->setFixedHeight(200);
ui->progressBar->setInvertAppearance(true);
ui->progressBar->setValue(50); // 上侧 50% 区域填充色块

两属性示例代码：

cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK，那么本文件我们来学习QProgressBar的orientation属性，invertAppearance属性、format属性
    //前两个属性比较简单，orientation属性是控制进度条的方向是水平的还是垂直的
    //Qt::Vertical垂直方向，Qt::Horizontal水平方向
    //而invertAppearance属性是控制进度条是否是朝反方向增长进度

    //最重要的format属性，我们就是要通过这个属性设置QProgressBar控件的文本显示，令其不是单单的数字
    //还可以有汉字，包括还能设置数字的显示格式，就是使用占位符
    //• %p ：表示进度的百分比（0-100）
    //• %v ：表示进度的数值（0-100）
    //• %m ：表示剩余时间（以毫秒为单位）
    //• %t ：表示总时间（以毫秒为单位）
    //它的使用方法也是很简单，就像printf一样使用就差不多， progressbar->setFormat("进度：%p");
    //但是它获取数值，依旧是从QProgressBar的value属性获取哦~~~

    /**
     * @property QProgressBar::orientation
     * @brief QProgressBar的显示方向属性
     * @details 该属性控制进度条的整体展示方向是水平还是垂直，默认值为Qt::Horizontal（水平）；
     *          方向仅改变进度条的视觉布局，不影响进度值（value）的计算逻辑，垂直进度条的进度增长方向受invertAppearance属性联动控制。
     *
     * 【枚举值详解（Qt::Orientation）】
     * | 枚举值              | 中文名称   | 功能说明                                                                 |
     * |---------------------|------------|--------------------------------------------------------------------------|
     * | Qt::Horizontal      | 水平方向   | 进度条沿水平方向展示（默认），是最常用的展示形式，进度增长方向为左右向；   |
     * | Qt::Vertical        | 垂直方向   | 进度条沿垂直方向展示，需调整控件高度以体现进度变化，进度增长方向为上下向； |
     *
     * 【关联API详解】
     * 1. Qt::Orientation orientation() const
     *    - 功能：获取当前进度条的显示方向
     *    - 返回值：Qt::Orientation枚举值，默认返回Qt::Horizontal
     *    - 调用示例：
     *      Qt::Orientation orient = ui->progressBar->orientation();
     *
     * 2. void setOrientation(Qt::Orientation orient)
     *    - 功能：设置进度条的显示方向
     *    - 参数：orient - 方向枚举值（Horizontal/Vertical）
     *    - 示例：
     *      // 切换为垂直进度条（需调整控件高度才能直观看到效果）
     *      ui->progressBar->setOrientation(Qt::Vertical);
     *      ui->progressBar->setFixedHeight(200); // 设置垂直进度条高度
     *
     * 【关键注意事项】
     * 1. 布局适配：垂直进度条需设置足够的高度（如setFixedHeight），否则视觉效果不明显；
     * 2. 联动规则：方向切换后，invertAppearance的反向增长逻辑会自动适配新方向；
     * 3. 文本适配：垂直进度条的文本朝向需通过textDirection属性调整，alignment仍控制水平对齐。
     *
     * ---
     *
     * @property QProgressBar::invertAppearance
     * @brief QProgressBar的进度反向增长属性
     * @details 该属性控制进度条的色块填充方向是否反向，默认值为false（正向增长）；
     *          仅改变进度的视觉增长方向，不影响value、minimum、maximum的数值计算，是纯视觉层面的调整。
     *
     * 【不同方向下的增长规则（核心）】
     * | 进度条方向       | 正向增长（invertAppearance=false） | 反向增长（invertAppearance=true） |
     * |------------------|------------------------------------|------------------------------------|
     * | 水平（Horizontal）| 进度色块从左向右填充               | 进度色块从右向左填充               |
     * | 垂直（Vertical）  | 进度色块从下向上填充               | 进度色块从上向下填充               |
     *
     * 【关联API详解】
     * 1. bool invertAppearance() const
     *    - 功能：获取是否开启进度反向增长
     *    - 返回值：false正向（默认），true反向
     *    - 调用示例：
     *      bool isInvert = ui->progressBar->invertAppearance();
     *
     * 2. void setInvertAppearance(bool invert)
     *    - 功能：设置进度增长方向是否反向
     *    - 参数：invert - true开启反向，false关闭
     *    - 示例：
     *      // 水平进度条反向增长（从右到左填充）
     *      ui->progressBar->setOrientation(Qt::Horizontal);
     *      ui->progressBar->setInvertAppearance(true);
     *      ui->progressBar->setValue(50); // 右侧50%区域填充色块
     *
     * 【关键注意事项】
     * 1. 数值无关：反向增长仅改变视觉填充方向，value的数值大小和百分比计算不受任何影响；
     * 2. 即时生效：设置后无需刷新进度条，当前进度色块会立即切换填充方向；
     * 3. 繁忙模式适配：繁忙模式（maximum=0）下，反向属性会改变滚动色块的移动方向。
     *
     * ---
     *
     * @property QProgressBar::format
     * @brief QProgressBar的进度文本格式属性
     * @details 该属性用于自定义进度条显示的文本内容格式，支持占位符动态替换，默认值为"%p%"（显示百分比）；
     *          仅当textVisible为true时生效，若设置为空字符串（""），文本区域仍保留但内容为空，适用于自定义文本展示场景。
     *
     * 【占位符详解（核心）】
     * | 占位符 | 中文含义       | 功能说明                                                                 |
     * |--------|----------------|--------------------------------------------------------------------------|
     * | %p     | 进度百分比     | 显示0-100的百分比值（如value=50时显示"50"，默认格式%p%会显示"50%"），最常用； |
     * | %v     | 进度当前数值   | 显示value的原始数值（如minimum=0、maximum=100时，value=50显示"50"）；     |
     * | %m     | 剩余时间（毫秒）| 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
     * | %t     | 总时间（毫秒） | 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
     *
     * 【关联API详解】
     * 1. QString format() const
     *    - 功能：获取当前文本格式字符串
     *    - 返回值：QString类型，默认返回"%p%"
     *    - 调用示例：
     *      QString fmt = ui->progressBar->format();
     *
     * 2. void setFormat(const QString &format)
     *    - 功能：设置自定义文本格式
     *    - 参数：format - 包含占位符的格式字符串（支持普通文本+占位符组合）
     *    - 示例：
     *      // 默认格式：显示"50%"
     *      ui->progressBar->setFormat("%p%");
     *      // 自定义格式：显示"进度：50/100"
     *      ui->progressBar->setFormat("进度：%v/100");
     *      // 组合格式：显示"完成50%，剩余1000ms"（需手动绑定%m值）
     *      ui->progressBar->setFormat("完成%p%，剩余%m ms");
     *      // 清空格式：文本区域为空
     *      ui->progressBar->setFormat("");
     *
     * 【关键注意事项】
     * 1. %m/%t使用：这两个占位符需手动通过代码计算并关联（如定时器统计耗时），Qt不会自动计算剩余/总时间；
     * 2. 格式生效：修改format后，文本会立即刷新为新格式，无需重启进度条；
     * 3. 百分比计算：%p的取值基于 (value - minimum)/(maximum - minimum) × 100，与maximum是否为100无关；
     * 4. 文本长度：格式字符串过长可能导致文本超出进度条区域，需结合控件宽度适配。
     *
     * 【典型组合示例】
     * // 需求：垂直反向进度条，显示"当前进度：80/200"格式文本
     * ui->progressBar->setMinimum(0);
     * ui->progressBar->setMaximum(200);
     * ui->progressBar->setOrientation(Qt::Vertical); // 垂直方向
     * ui->progressBar->setInvertAppearance(true); // 从上到下增长
     * ui->progressBar->setTextVisible(true); // 显示文本
     * ui->progressBar->setFormat("当前进度：%v/200"); // 自定义格式
     * ui->progressBar->setValue(80); // 显示"当前进度：80/200"，色块从上到下填充80/200区域
     */


    QProgressBar* progressbar=new QProgressBar(this);

    progressbar->setMaximum(100);

    progressbar->setMinimum(0);

    progressbar->setValue(50);

    progressbar->setGeometry(200,200,500,200);


//    * | 占位符 | 中文含义       | 功能说明                                                                 |
//    * |--------|----------------|--------------------------------------------------------------------------|
//    * | %p     | 进度百分比     | 显示0-100的百分比值（如value=50时显示"50"，默认格式%p%会显示"50%"），最常用； |
//    * | %v     | 进度当前数值   | 显示value的原始数值（如minimum=0、maximum=100时，value=50显示"50"）；     |
//    * | %m     | 剩余时间（毫秒）| 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
//    * | %t     | 总时间（毫秒） | 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
    progressbar->setFormat("进度：%p");

    progressbar->setFormat("进度：%v");

    progressbar->setFormat("进度：%m");

    progressbar->setFormat("进度：%t");

    //那么其实我们还可以设置一个定时进度条，但是没什么必要了就是，以后用到再说，毕竟我们之前也使用过QTimer了~~~
}

Widget::~Widget()
{
    delete ui;
}

第四章 QProgressBar 核心属性详解（下）：文本显示属性（textVisible、alignment、textDirection、format）

除了色块，QProgressBar 还可以显示文本 ------ 比如百分比、当前值，让用户更直观地知道进度。Qt 为 QProgressBar 提供了四个文本相关的属性：textVisible（文本显隐）、alignment（文本对齐）、textDirection（文本朝向）、format（文本格式）。其中 format 是最灵活、最常用的，我们会重点讲解。

4.1 属性六：textVisible（文本显隐开关）------ 要不要显示数字？

4.1.1 属性的核心定义

textVisible 属性用于控制 QProgressBar 上的数字、百分比等文本内容是否可见 ，默认值为 true（可见）。

通俗理解：textVisible 就像 "进度条文本的开关"------ 你可以打开它（显示百分比 / 数值），也可以关掉它（只显示色块，不显示任何数字）。

这里有几个点需要注意：

  1. 仅影响文本显隐 ：不影响进度条的色块展示、value 计算，也不影响 format、alignment 等文本相关属性的设置 ------ 只是这些属性需要 textVisible=true 才会生效；
  2. 设为 false 时：进度条仅显示色块区域，文本区域完全隐藏，适用于仅需视觉反馈进度、无需数字提示的场景；
  3. 繁忙模式适配 ：繁忙模式下（maximum=0），该属性仍生效 ------ 设为 true 会显示空文本区域，设为 false 则完全隐藏文本区域。
4.1.2 数据类型

bool 类型，true 表示文本可见（默认），false 表示文本隐藏。

4.1.3 关联 API 详解（逐词逐句，零模糊）
1. 获取文本是否可见：bool isTextVisible () const

函数原型：

复制代码 
bool QProgressBar::isTextVisible() const;

逐词逐句底层解析：

  • bool：返回值类型，返回文本是否可见；
  • QProgressBar::：成员函数；
  • isTextVisible()：函数名，"获取文本是否可见" 的意思；
  • const：常成员函数。

返回值说明：

  • true 表示文本可见（默认），false 表示文本隐藏。

调用示例：

复制代码 
bool isVisible = ui->progressBar->isTextVisible();
if (isVisible) {
    qDebug() << "进度文本当前可见";
} else {
    qDebug() << "进度文本当前隐藏";
}
2. 设置文本显隐：void setTextVisible (bool visible)

函数原型：

复制代码 
void QProgressBar::setTextVisible(bool visible);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setTextVisible()：函数名，"设置文本显隐" 的意思；
  • bool visible：入参，visible 是 true 显示文本，false 隐藏文本。

参数说明：

  • visible：true 显示文本（默认），false 隐藏文本；
  • 设置后立即生效，无需重启 / 刷新进度条。

调用示例：

复制代码 
// 示例1：隐藏进度文本，仅显示进度色块
ui->progressBar->setTextVisible(false);

// 示例2：重新显示文本（恢复默认）
ui->progressBar->setTextVisible(true);

4.2 属性七：alignment（文本对齐）------ 文本居左、居右还是居中？

4.2.1 属性的核心定义

alignment 属性用于控制 QProgressBar 内文本在其显示区域的水平对齐位置 ，默认值为 Qt::AlignCenter（居中）。

通俗理解：alignment 就像 "进度条文本的位置"------ 你可以让文本在左边、右边、中间。

这里有一个非常重要的坑点，新手很容易踩：

仅水平对齐值生效！垂直对齐值（如 Qt::AlignTop、Qt::AlignBottom）无任何效果！

也就是说，你只能控制文本 "居左、居右、居中"，不能控制它 "靠上、靠下"------ 垂直方向默认就是居中的，无法修改。

另外，该属性仅在 textVisible=true 时生效，对齐范围是 "进度条的文本显示区域"，而非整个进度条控件区域。

4.2.2 对齐枚举值详解（Qt::Alignment）

为了让你更清楚地理解，我做了一个对比表格：

枚举值 中文名称 功能说明
Qt::AlignLeft 左对齐 文本在进度条的文本显示区域靠左对齐，水平进度条左侧、垂直进度条顶部对齐；
Qt::AlignRight 右对齐 文本在进度条的文本显示区域靠右对齐，水平进度条右侧、垂直进度条底部对齐；
Qt::AlignCenter 居中对齐 文本在进度条的文本显示区域居中对齐（默认），是最常用的对齐方式；
Qt::AlignJustify 两端对齐 视觉效果等同于左对齐（仅对多行文本生效，进度条文本为单行，无实际差异）；
4.2.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前对齐方式：Qt::Alignment alignment () const

函数原型：

复制代码 
Qt::Alignment QProgressBar::alignment() const;

逐词逐句底层解析：

  • Qt::Alignment：返回值类型，返回当前的文本对齐方式；
  • QProgressBar::：成员函数；
  • alignment()：函数名，"获取对齐方式" 的意思；
  • const：常成员函数。

返回值说明：

  • 返回 Qt::Alignment 枚举值，默认返回 Qt::AlignCenter。

调用示例：

复制代码 
Qt::Alignment align = ui->progressBar->alignment();
if (align == Qt::AlignCenter) {
    qDebug() << "当前文本居中对齐";
}
2. 设置对齐方式：void setAlignment (Qt::Alignment align)

函数原型：

复制代码 
void QProgressBar::setAlignment(Qt::Alignment align);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setAlignment()：函数名，"设置对齐方式" 的意思；
  • Qt::Alignment align：入参，align 是水平对齐枚举值（仅 Left/Right/Center/Justify 生效）。

参数说明：

  • align：水平对齐枚举值（Qt::AlignLeft、Qt::AlignRight、Qt::AlignCenter）；
  • 垂直对齐值（如 Qt::AlignTop）无效，不要设置；
  • 仅在 textVisible=true 时生效。

调用示例：

复制代码 
// 示例1：水平进度条文本右对齐
ui->progressBar->setOrientation(Qt::Horizontal);
ui->progressBar->setAlignment(Qt::AlignRight);
ui->progressBar->setTextVisible(true);

// 示例2：垂直进度条文本居中对齐（默认）
ui->progressBar->setOrientation(Qt::Vertical);
ui->progressBar->setAlignment(Qt::AlignCenter);

4.3 属性八：textDirection（文本朝向）------ 仅对垂直进度条有用

4.3.1 属性的核心定义

textDirection 属性用于控制 QProgressBar 内文本的排版朝向 ，核心适配垂直进度条 的文本展示场景，默认值为 QProgressBar::TopToBottom（从上到下）。

通俗理解：textDirection 就像 "垂直进度条文本的方向"------ 你可以让文字从上到下正常显示，也可以让它从下到上倒置显示。

这里有几个非常重要的点，新手一定要知道：

  1. 仅垂直进度条生效 ：水平进度条设置该属性无任何视觉效果（文本始终水平显示）；
  2. 仅改变排版朝向：不影响文本内容，仅改变文字的方向；
  3. BottomToTop 会倒置文字 ：设置为 BottomToTop 时，文字会倒置展示，可能影响可读性，需结合界面设计场景使用；
  4. 仅在 textVisible=true 时生效。

这个属性实际开发中用得非常少，知道即可，不用深入研究。

4.3.2 枚举值详解（QProgressBar::TextDirection）
枚举值 中文名称 功能说明
QProgressBar::TopToBottom 从上到下朝向 文本沿垂直进度条从上到下显示（默认），适配常规垂直进度条的视觉习惯；
QProgressBar::BottomToTop 从下到上朝向 文本沿垂直进度条从下到上显示，文字会倒置展示，适用于特殊视觉设计需求；
4.3.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前文本朝向：QProgressBar::TextDirection textDirection () const

函数原型：

复制代码 
QProgressBar::TextDirection QProgressBar::textDirection() const;

返回值说明：

  • 返回 QProgressBar::TopToBottom（默认）或 QProgressBar::BottomToTop。
2. 设置文本朝向：void setTextDirection (QProgressBar::TextDirection dir)

函数原型：

复制代码 
void QProgressBar::setTextDirection(QProgressBar::TextDirection dir);

参数说明：

  • dir：QProgressBar::TopToBottom 或 QProgressBar::BottomToTop；
  • 生效前提 ：需先将进度条设为垂直方向（orientation=Qt::Vertical），否则无效果。

调用示例：

复制代码 
// 第一步：将进度条设为垂直方向（生效前提）
ui->progressBar->setOrientation(Qt::Vertical);
ui->progressBar->setFixedHeight(200);
// 第二步：设置文本从下到上显示（文字会倒置）
ui->progressBar->setTextDirection(QProgressBar::BottomToTop);
// 第三步：确保文本可见
ui->progressBar->setTextVisible(true);

两属性示例代码：

cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK，那么本文件我们来学习QProgressBar控件的textDirection属性以及alignment属性
    //那么alignment属性我们很熟悉了，在学习QLabel控件的时候，我们就学习了
    //就是控制文本是要居左还是巴拉巴拉
    //这个其实就是需要我们知道，QProgressBar控件，也是可以设置文本的哦·~~~
    //这个就得使用format属性了，我们下个文件会解析
    //然后就是textDirection属性，这个没什么用，不用管~~~知道即可

    //这两个属性其实都没什么用的啦~~~

    /**
     * @property QProgressBar::textDirection
     * @brief QProgressBar进度文本的显示朝向属性
     * @details 该属性用于控制进度条内文本的排版朝向，核心适配**垂直进度条**的文本展示场景，默认值为QProgressBar::TopToBottom；
     *          水平进度条设置该属性无视觉效果（文本始终水平显示），仅垂直进度条能体现朝向差异；
     *          该属性仅在textVisible为true时生效，不影响文本内容，仅改变文本的排版方向。
     *
     * 【枚举值详解（QProgressBar::TextDirection）】
     * | 枚举值                  | 中文名称       | 功能说明                                                                 |
     * |-------------------------|----------------|--------------------------------------------------------------------------|
     * | QProgressBar::TopToBottom | 从上到下朝向   | 文本沿垂直进度条从上到下显示（默认），适配常规垂直进度条的视觉习惯；       |
     * | QProgressBar::BottomToTop | 从下到上朝向   | 文本沿垂直进度条从下到上显示，文字会倒置展示，适用于特殊视觉设计需求；     |
     *
     * 【关联API详解】
     * 1. QProgressBar::TextDirection textDirection() const
     *    - 功能：获取当前文本朝向
     *    - 返回值：QProgressBar::TextDirection枚举值，默认返回TopToBottom
     *    - 调用示例：
     *      QProgressBar::TextDirection dir = ui->progressBar->textDirection();
     *
     * 2. void setTextDirection(QProgressBar::TextDirection dir)
     *    - 功能：设置文本的显示朝向
     *    - 参数：dir - 文本朝向枚举值（TopToBottom/BottomToTop）
     *    - 生效前提：需先将进度条设为垂直方向（orientation=Qt::Vertical），否则无效果
     *    - 示例：
     *      // 第一步：将进度条设为垂直方向（生效前提）
     *      ui->progressBar->setOrientation(Qt::Vertical);
     *      // 第二步：设置文本从下到上显示
     *      ui->progressBar->setTextDirection(QProgressBar::BottomToTop);
     *      // 第三步：确保文本可见
     *      ui->progressBar->setTextVisible(true);
     *
     * 【关键注意事项】
     * 1. 方向依赖：仅垂直进度条（Qt::Vertical）能体现文本朝向差异，水平进度条设置后无任何视觉变化；
     * 2. 文本可见性：需保证textVisible=true，否则该属性设置无意义；
     * 3. 视觉适配：BottomToTop朝向会导致文字倒置，需结合界面设计场景使用，避免影响可读性。
     *
     * ---
     *
     * @property QProgressBar::alignment
     * @brief QProgressBar进度文本的对齐方式属性
     * @details 该属性用于控制进度条内文本在其显示区域的水平对齐位置，默认值为Qt::AlignCenter；
     *          仅当textVisible为true时生效，支持Qt::Alignment枚举的水平对齐值（垂直对齐值无效果），是调整文本位置的核心属性。
     *
     * 【对齐枚举值详解（Qt::Alignment）】
     * | 枚举值              | 中文名称   | 功能说明                                                                 |
     * |---------------------|------------|--------------------------------------------------------------------------|
     * | Qt::AlignLeft       | 左对齐     | 文本在进度条的文本显示区域靠左对齐，水平进度条左侧、垂直进度条顶部对齐；   |
     * | Qt::AlignRight      | 右对齐     | 文本在进度条的文本显示区域靠右对齐，水平进度条右侧、垂直进度条底部对齐；   |
     * | Qt::AlignCenter     | 居中对齐   | 文本在进度条的文本显示区域居中对齐（默认），是最常用的对齐方式；           |
     * | Qt::AlignJustify    | 两端对齐   | 视觉效果等同于左对齐（仅对多行文本生效，进度条文本为单行，无实际差异）；   |
     *
     * 【关联API详解】
     * 1. Qt::Alignment alignment() const
     *    - 功能：获取当前文本的对齐方式
     *    - 返回值：Qt::Alignment枚举值，默认返回Qt::AlignCenter
     *    - 调用示例：
     *      Qt::Alignment align = ui->progressBar->alignment();
     *
     * 2. void setAlignment(Qt::Alignment align)
     *    - 功能：设置文本的对齐方式
     *    - 参数：align - 水平对齐枚举值（仅Left/Right/Center/Justify生效）
     *    - 示例：
     *      // 水平进度条文本右对齐
     *      ui->progressBar->setOrientation(Qt::Horizontal);
     *      ui->progressBar->setAlignment(Qt::AlignRight);
     *      ui->progressBar->setTextVisible(true);
     *
     *      // 垂直进度条文本居中对齐（默认）
     *      ui->progressBar->setOrientation(Qt::Vertical);
     *      ui->progressBar->setAlignment(Qt::AlignCenter);
     *
     * 【关键注意事项】
     * 1. 仅水平对齐生效：设置垂直对齐值（如Qt::AlignTop）无任何效果，进度条文本仅支持水平对齐；
     * 2. 区域限制：对齐范围是进度条的文本显示区域，而非整个进度条控件区域；
     * 3. 优先级：对齐方式优先级高于文本朝向，先确定对齐位置，再应用朝向。
     *
     * 【典型组合示例】
     * // 需求：垂直进度条、文本从下到上显示、文本右对齐、显示百分比
     * ui->progressBar->setOrientation(Qt::Vertical); // 垂直方向
     * ui->progressBar->setTextDirection(QProgressBar::BottomToTop); // 文本从下到上
     * ui->progressBar->setAlignment(Qt::AlignRight); // 文本右对齐
     * ui->progressBar->setTextVisible(true); // 显示文本
     * ui->progressBar->setFormat("%p%"); // 百分比格式
     * ui->progressBar->setMinimum(0);
     * ui->progressBar->setMaximum(100);
     * ui->progressBar->setValue(60); // 显示"60%"，右对齐+从下到上朝向
     */

     //还有一个属性就是textVisible，就是控制进度条的文本（数字）可不可见，一般都是设置为可见的，默认也是可见的~~

    /**
     * @property QProgressBar::textVisible
     * @brief QProgressBar进度文本（数字/百分比）的显示开关属性
     * @details 该属性用于控制进度条上的数字、百分比等文本内容是否可见，默认值为true（可见）；
     *          仅影响文本的显示状态，不会改变进度条的色块展示、进度值（value）计算，也不影响format、alignment等文本相关属性的设置（只是这些属性需textVisible=true才会生效）；
     *          设为false时，进度条仅显示色块区域，文本区域完全隐藏，适用于仅需视觉反馈进度、无需数字提示的场景。
     *
     * 【关联API详解】
     * 1. bool isTextVisible() const
     *    - 功能：获取当前进度文本的显示状态
     *    - 返回值：true表示文本可见（默认），false表示文本隐藏
     *    - 调用示例：
     *      bool isVisible = ui->progressBar->isTextVisible();
     *      if (isVisible) {
     *          qDebug() << "进度文本当前可见";
     *      }
     *
     * 2. void setTextVisible(bool visible)
     *    - 功能：设置进度文本的显示/隐藏状态
     *    - 参数：visible - true显示文本，false隐藏文本
     *    - 生效规则：设置后立即生效，无需重启/刷新进度条
     *    - 示例：
     *      // 隐藏进度文本，仅显示进度色块
     *      ui->progressBar->setTextVisible(false);
     *      // 重新显示文本（恢复默认）
     *      ui->progressBar->setTextVisible(true);
     *
     * 【关键注意事项】
     * 1. 显隐独立：文本隐藏（false）时，进度条的色块、进度值更新等核心功能不受任何影响；
     * 2. 属性兼容：即使textVisible=false，仍可正常设置format、alignment等文本属性，仅不会显示；
     * 3. 繁忙模式适配：繁忙模式（maximum=0）下，该属性仍生效------设为true会显示空文本区域，设为false则完全隐藏文本区域；
     * 4. 性能影响：切换该属性无明显性能开销，可根据业务逻辑动态调整（如任务开始隐藏、完成显示百分比）。
     *
     * 【典型使用示例】
     * // 场景1：常规进度条（显示百分比文本）
     * ui->progressBar->setMinimum(0);
     * ui->progressBar->setMaximum(100);
     * ui->progressBar->setTextVisible(true); // 显示文本（默认）
     * ui->progressBar->setFormat("%p%");
     * ui->progressBar->setValue(80); // 显示"80%"
     *
     * // 场景2：仅展示色块的进度条（隐藏文本）
     * ui->progressBar->setTextVisible(false); // 隐藏文本
     * ui->progressBar->setValue(80); // 仅显示80%进度的色块，无任何数字
     *
     * // 场景3：动态切换文本显隐（任务中隐藏，完成后显示）
     * connect(ui->btnStart, &QPushButton::clicked, this, [=](){
     *     ui->progressBar->setTextVisible(false); // 任务开始，隐藏文本
     *     // 模拟进度更新
     *     QTimer *timer = new QTimer(this);
     *     int val = 0;
     *     connect(timer, &QTimer::timeout, this, [&](){
     *         val += 10;
     *         ui->progressBar->setValue(val);
     *         if (val >= 100) {
     *             timer->stop();
     *             ui->progressBar->setTextVisible(true); // 任务完成，显示文本
     *         }
     *     });
     *     timer->start(500);
     * });
     */

    QProgressBar* progressbar=new QProgressBar(this);

    progressbar->setMaximum(100);

    progressbar->setMinimum(0);

    progressbar->setValue(50);

    progressbar->setGeometry(200,200,500,200);

    progressbar->setFormat("进度：%p");

    //居右展示
    progressbar->setAlignment(Qt::AlignLeft);

}
Widget::~Widget()
{
    delete ui;
}

4.4 属性九：format（文本格式）------ 最灵活的文本属性，重点讲解！

4.4.1 属性的核心定义

format 属性用于自定义 QProgressBar 显示的文本内容格式，支持占位符动态替换 ，默认值为 "%p%"（显示百分比，如 "50%"）。

通俗理解：format 就像 "进度条文本的模板"------ 你可以在模板里写普通文字，再用特殊的 "占位符" 代替动态内容（比如百分比、当前值），Qt 会自动把占位符替换成实际的数值。

这个属性是 QProgressBar 文本相关属性中最灵活、最常用的，一定要重点掌握！

这里有几个点需要注意：

  1. 仅在 textVisible=true 时生效；
  2. 若设置为空字符串（""）：文本区域仍保留但内容为空；
  3. 占位符区分大小写 ：必须是小写的 %p、%v、%m、%t，大写无效。
4.4.2 占位符详解（核心，必知！）

QProgressBar 支持四个占位符，其中前两个最常用，后两个需要手动关联逻辑：

占位符 中文含义 功能说明
%p 进度百分比 显示 0-100 的百分比值（如 value=50 时显示 "50"，默认格式 %p% 会显示 "50%"），最常用；
%v 进度当前数值 显示 value 的原始数值（如 minimum=0、maximum=100 时，value=50 显示 "50"）；
%m 剩余时间（毫秒） 需手动结合定时器 / 任务逻辑绑定数值，Qt 无默认计算逻辑，默认显示空值；
%t 总时间（毫秒） 需手动结合定时器 / 任务逻辑绑定数值，Qt 无默认计算逻辑，默认显示空值；

⚠️ 重要提醒 ：%m 和 %t 这两个占位符，Qt 不会自动计算 "剩余时间" 和 "总时间"------ 你需要自己用定时器统计任务耗时，然后通过某种方式关联（不过 QProgressBar 没有直接设置 %m/%t 值的公共 API，所以这两个占位符实际用得很少，知道即可）。

我们重点掌握 %p 和 %v 就够了！

4.4.3 关联 API 详解（逐词逐句，零模糊）
1. 获取当前文本格式：QString format () const

函数原型：

复制代码 
QString QProgressBar::format() const;

逐词逐句底层解析：

  • QString：返回值类型，返回当前的文本格式字符串；
  • QProgressBar::：成员函数；
  • format()：函数名，"获取文本格式" 的意思；
  • const：常成员函数。

返回值说明：

  • 返回 QString 类型的字符串，默认返回 "%p%"。

调用示例：

复制代码 
QString fmt = ui->progressBar->format();
qDebug() << "当前文本格式：" << fmt; // 输出 "%p%"（默认）
2. 设置文本格式：void setFormat (const QString &format)

函数原型：

复制代码 
void QProgressBar::setFormat(const QString &format);

逐词逐句底层解析：

  • void：无返回值；
  • QProgressBar::：成员函数；
  • setFormat()：函数名，"设置文本格式" 的意思；
  • const QString &format：入参，format 是包含占位符的格式字符串（支持普通文本 + 占位符组合）。

参数说明：

  • format：包含占位符的格式字符串（如 "%p%"、"进度：%v/100"）；
  • 支持普通文本和占位符组合；
  • 修改后立即生效，文本会立即刷新为新格式。

调用示例：

复制代码 
// 先设置常规进度范围
ui->progressBar->setMinimum(0);
ui->progressBar->setMaximum(100);
ui->progressBar->setValue(50);
ui->progressBar->setTextVisible(true);

// 示例1：默认格式：显示"50%"
ui->progressBar->setFormat("%p%");

// 示例2：自定义格式：显示"进度：50/100"
ui->progressBar->setFormat("进度：%v/100");

// 示例3：组合格式：显示"完成 50%"
ui->progressBar->setFormat("完成 %p%");

// 示例4：清空格式：文本区域为空
ui->progressBar->setFormat("");
4.4.4 典型组合示例
复制代码 
// 需求：垂直反向进度条，显示"当前进度：80/200"格式文本
ui->progressBar->setMinimum(0);
ui->progressBar->setMaximum(200);
ui->progressBar->setOrientation(Qt::Vertical); // 垂直方向
ui->progressBar->setInvertAppearance(true); // 从上到下增长
ui->progressBar->setTextVisible(true); // 显示文本
ui->progressBar->setFormat("当前进度：%v/200"); // 自定义格式
ui->progressBar->setValue(80); // 显示"当前进度：80/200"，色块从上到下填充 80/200 区域

示例代码：

cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK，那么本文件我们来学习QProgressBar的orientation属性，invertAppearance属性、format属性
    //前两个属性比较简单，orientation属性是控制进度条的方向是水平的还是垂直的
    //Qt::Vertical垂直方向，Qt::Horizontal水平方向
    //而invertAppearance属性是控制进度条是否是朝反方向增长进度

    //最重要的format属性，我们就是要通过这个属性设置QProgressBar控件的文本显示，令其不是单单的数字
    //还可以有汉字，包括还能设置数字的显示格式，就是使用占位符
    //• %p ：表示进度的百分比（0-100）
    //• %v ：表示进度的数值（0-100）
    //• %m ：表示剩余时间（以毫秒为单位）
    //• %t ：表示总时间（以毫秒为单位）
    //它的使用方法也是很简单，就像printf一样使用就差不多， progressbar->setFormat("进度：%p");
    //但是它获取数值，依旧是从QProgressBar的value属性获取哦~~~

    /**
     * @property QProgressBar::orientation
     * @brief QProgressBar的显示方向属性
     * @details 该属性控制进度条的整体展示方向是水平还是垂直，默认值为Qt::Horizontal（水平）；
     *          方向仅改变进度条的视觉布局，不影响进度值（value）的计算逻辑，垂直进度条的进度增长方向受invertAppearance属性联动控制。
     *
     * 【枚举值详解（Qt::Orientation）】
     * | 枚举值              | 中文名称   | 功能说明                                                                 |
     * |---------------------|------------|--------------------------------------------------------------------------|
     * | Qt::Horizontal      | 水平方向   | 进度条沿水平方向展示（默认），是最常用的展示形式，进度增长方向为左右向；   |
     * | Qt::Vertical        | 垂直方向   | 进度条沿垂直方向展示，需调整控件高度以体现进度变化，进度增长方向为上下向； |
     *
     * 【关联API详解】
     * 1. Qt::Orientation orientation() const
     *    - 功能：获取当前进度条的显示方向
     *    - 返回值：Qt::Orientation枚举值，默认返回Qt::Horizontal
     *    - 调用示例：
     *      Qt::Orientation orient = ui->progressBar->orientation();
     *
     * 2. void setOrientation(Qt::Orientation orient)
     *    - 功能：设置进度条的显示方向
     *    - 参数：orient - 方向枚举值（Horizontal/Vertical）
     *    - 示例：
     *      // 切换为垂直进度条（需调整控件高度才能直观看到效果）
     *      ui->progressBar->setOrientation(Qt::Vertical);
     *      ui->progressBar->setFixedHeight(200); // 设置垂直进度条高度
     *
     * 【关键注意事项】
     * 1. 布局适配：垂直进度条需设置足够的高度（如setFixedHeight），否则视觉效果不明显；
     * 2. 联动规则：方向切换后，invertAppearance的反向增长逻辑会自动适配新方向；
     * 3. 文本适配：垂直进度条的文本朝向需通过textDirection属性调整，alignment仍控制水平对齐。
     *
     * ---
     *
     * @property QProgressBar::invertAppearance
     * @brief QProgressBar的进度反向增长属性
     * @details 该属性控制进度条的色块填充方向是否反向，默认值为false（正向增长）；
     *          仅改变进度的视觉增长方向，不影响value、minimum、maximum的数值计算，是纯视觉层面的调整。
     *
     * 【不同方向下的增长规则（核心）】
     * | 进度条方向       | 正向增长（invertAppearance=false） | 反向增长（invertAppearance=true） |
     * |------------------|------------------------------------|------------------------------------|
     * | 水平（Horizontal）| 进度色块从左向右填充               | 进度色块从右向左填充               |
     * | 垂直（Vertical）  | 进度色块从下向上填充               | 进度色块从上向下填充               |
     *
     * 【关联API详解】
     * 1. bool invertAppearance() const
     *    - 功能：获取是否开启进度反向增长
     *    - 返回值：false正向（默认），true反向
     *    - 调用示例：
     *      bool isInvert = ui->progressBar->invertAppearance();
     *
     * 2. void setInvertAppearance(bool invert)
     *    - 功能：设置进度增长方向是否反向
     *    - 参数：invert - true开启反向，false关闭
     *    - 示例：
     *      // 水平进度条反向增长（从右到左填充）
     *      ui->progressBar->setOrientation(Qt::Horizontal);
     *      ui->progressBar->setInvertAppearance(true);
     *      ui->progressBar->setValue(50); // 右侧50%区域填充色块
     *
     * 【关键注意事项】
     * 1. 数值无关：反向增长仅改变视觉填充方向，value的数值大小和百分比计算不受任何影响；
     * 2. 即时生效：设置后无需刷新进度条，当前进度色块会立即切换填充方向；
     * 3. 繁忙模式适配：繁忙模式（maximum=0）下，反向属性会改变滚动色块的移动方向。
     *
     * ---
     *
     * @property QProgressBar::format
     * @brief QProgressBar的进度文本格式属性
     * @details 该属性用于自定义进度条显示的文本内容格式，支持占位符动态替换，默认值为"%p%"（显示百分比）；
     *          仅当textVisible为true时生效，若设置为空字符串（""），文本区域仍保留但内容为空，适用于自定义文本展示场景。
     *
     * 【占位符详解（核心）】
     * | 占位符 | 中文含义       | 功能说明                                                                 |
     * |--------|----------------|--------------------------------------------------------------------------|
     * | %p     | 进度百分比     | 显示0-100的百分比值（如value=50时显示"50"，默认格式%p%会显示"50%"），最常用； |
     * | %v     | 进度当前数值   | 显示value的原始数值（如minimum=0、maximum=100时，value=50显示"50"）；     |
     * | %m     | 剩余时间（毫秒）| 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
     * | %t     | 总时间（毫秒） | 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
     *
     * 【关联API详解】
     * 1. QString format() const
     *    - 功能：获取当前文本格式字符串
     *    - 返回值：QString类型，默认返回"%p%"
     *    - 调用示例：
     *      QString fmt = ui->progressBar->format();
     *
     * 2. void setFormat(const QString &format)
     *    - 功能：设置自定义文本格式
     *    - 参数：format - 包含占位符的格式字符串（支持普通文本+占位符组合）
     *    - 示例：
     *      // 默认格式：显示"50%"
     *      ui->progressBar->setFormat("%p%");
     *      // 自定义格式：显示"进度：50/100"
     *      ui->progressBar->setFormat("进度：%v/100");
     *      // 组合格式：显示"完成50%，剩余1000ms"（需手动绑定%m值）
     *      ui->progressBar->setFormat("完成%p%，剩余%m ms");
     *      // 清空格式：文本区域为空
     *      ui->progressBar->setFormat("");
     *
     * 【关键注意事项】
     * 1. %m/%t使用：这两个占位符需手动通过代码计算并关联（如定时器统计耗时），Qt不会自动计算剩余/总时间；
     * 2. 格式生效：修改format后，文本会立即刷新为新格式，无需重启进度条；
     * 3. 百分比计算：%p的取值基于 (value - minimum)/(maximum - minimum) × 100，与maximum是否为100无关；
     * 4. 文本长度：格式字符串过长可能导致文本超出进度条区域，需结合控件宽度适配。
     *
     * 【典型组合示例】
     * // 需求：垂直反向进度条，显示"当前进度：80/200"格式文本
     * ui->progressBar->setMinimum(0);
     * ui->progressBar->setMaximum(200);
     * ui->progressBar->setOrientation(Qt::Vertical); // 垂直方向
     * ui->progressBar->setInvertAppearance(true); // 从上到下增长
     * ui->progressBar->setTextVisible(true); // 显示文本
     * ui->progressBar->setFormat("当前进度：%v/200"); // 自定义格式
     * ui->progressBar->setValue(80); // 显示"当前进度：80/200"，色块从上到下填充80/200区域
     */


    QProgressBar* progressbar=new QProgressBar(this);

    progressbar->setMaximum(100);

    progressbar->setMinimum(0);

    progressbar->setValue(50);

    progressbar->setGeometry(200,200,500,200);


//    * | 占位符 | 中文含义       | 功能说明                                                                 |
//    * |--------|----------------|--------------------------------------------------------------------------|
//    * | %p     | 进度百分比     | 显示0-100的百分比值（如value=50时显示"50"，默认格式%p%会显示"50%"），最常用； |
//    * | %v     | 进度当前数值   | 显示value的原始数值（如minimum=0、maximum=100时，value=50显示"50"）；     |
//    * | %m     | 剩余时间（毫秒）| 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
//    * | %t     | 总时间（毫秒） | 需手动结合定时器/任务逻辑绑定数值，Qt无默认计算逻辑，默认显示空值；         |
    progressbar->setFormat("进度：%p");

    progressbar->setFormat("进度：%v");

    progressbar->setFormat("进度：%m");

    progressbar->setFormat("进度：%t");

    //那么其实我们还可以设置一个定时进度条，但是没什么必要了就是，以后用到再说，毕竟我们之前也使用过QTimer了~~~
}

Widget::~Widget()
{
    delete ui;
}

第五章 进阶：用样式表自定义 QProgressBar 颜色

默认的 QProgressBar 通常是绿色的，但有时候我们需要自定义颜色 ------ 比如红色表示错误、黄色表示警告、蓝色表示正常。QProgressBar 是 QWidget 的子类，所以我们可以用 Qt Style Sheets（QSS，样式表） 来修改它的颜色和样式，就像网页用 CSS 一样。

这里我们讲一个最常用的场景：把进度条改成红色。

5.1 核心样式表选择器

在 QSS 中，我们用两个选择器来控制 QProgressBar：

  1. QProgressBar：控制进度条的背景、边框等整体样式；
  2. QProgressBar::chunk：控制进度条中 "填充色块" 的样式（这个是关键！）。

5.2 代码示例：创建一个红色的进度条

复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QProgressBar>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    QProgressBar *progressBar = new QProgressBar(this);
    progressBar->setGeometry(100, 100, 400, 30);
    progressBar->setMinimum(0);
    progressBar->setMaximum(100);
    progressBar->setValue(50);
    progressBar->setTextVisible(true);
    progressBar->setFormat("%p%");
    progressBar->setAlignment(Qt::AlignCenter); // 居中文本，避免文本跑到左上角（Qt 某些版本的小问题）

    // 关键：用样式表设置红色进度条
    progressBar->setStyleSheet(R"(
        QProgressBar {
            border: 2px solid grey; /* 灰色边框 */
            border-radius: 5px; /* 圆角 */
            text-align: center; /* 文本居中（配合 alignment）*/
            background-color: #f0f0f0; /* 浅灰色背景 */
        }

        QProgressBar::chunk {
            background-color: #FF0000; /* 红色填充色块（核心！）*/
            width: 20px; /* 色块宽度（可选，让色块有间隔感）*/
        }
    )");
}

Widget::~Widget()
{
    delete ui;
}

5.3 样式表详解

我们来逐部分解释上面的样式表：

  1. QProgressBar 部分：
    • border: 2px solid grey;：设置 2 像素宽的灰色实线边框；
    • border-radius: 5px;：设置 5 像素的圆角，让进度条更好看；
    • text-align: center;：文本居中（配合 setAlignment(Qt::AlignCenter) 一起用，避免 Qt 某些版本中文本跑到左上角）；
    • background-color: #f0f0f0;：设置进度条的背景色为浅灰色。
  2. QProgressBar::chunk 部分（核心）：
    • background-color: #FF0000;：设置填充色块的颜色为红色（#FF0000 是红色的十六进制颜色码）------ 这是最关键的一行！
    • width: 20px;：设置每个色块的宽度为 20 像素（可选，让色块有间隔感，像老式进度条一样；如果不设置，就是一个连续的色块）。

你可以把 #FF0000 改成其他颜色码，比如 #00FF00（绿色）、#0000FF（蓝色）、#FFFF00（黄色），就能得到不同颜色的进度条了！

第六章 综合实战：QTimer + QProgressBar 实现定时增长进度条

现在，我们把之前学的 QProgressBar 和 QTimer 结合起来，实现一个完整的实战项目：定时增长的进度条------ 需求是：进度条从 0 开始，每隔 100 毫秒（0.1 秒）增长 1，直到 100 停止，显示百分比文本，居中对齐。

这个实战会覆盖我们之前讲的所有核心内容：QProgressBar 的 minimum、maximum、value、textVisible、alignment、format，以及 QTimer 的 setInterval()、start()、stop()、timeout() 信号，非常适合巩固学习。

6.1 需求分析

我们的需求很明确：

  1. 界面上有一个水平进度条，范围 0-100，初始值 0；
  2. 显示百分比文本（"50%"），居中对齐；
  3. 用 QTimer 实现每隔 100ms（0.1 秒）增长 1；
  4. 增长到 100 时，停止定时器，提示 "完成"。

6.2 代码实现

6.2.1 头文件（widget.h）

首先，我们需要在头文件中声明成员变量和槽函数：

复制代码 
#ifndef WIDGET_H
#define WIDGET_H

#include <QWidget>
#include <QProgressBar>
#include <QTimer>

QT_BEGIN_NAMESPACE
namespace Ui { class Widget; }
QT_END_NAMESPACE

class Widget : public QWidget
{
    Q_OBJECT

public:
    Widget(QWidget *parent = nullptr);
    ~Widget();

    // 声明槽函数：更新进度条
private slots:
    void updateProgress();

private:
    Ui::Widget *ui;
    // 成员变量：QProgressBar 和 QTimer，方便在槽函数中访问
    QProgressBar *progressBar;
    QTimer *timer;
};

#endif // WIDGET_H
6.2.2 源文件（widget.cpp）

然后，我们在源文件中实现构造函数和槽函数：

复制代码 
#include "widget.h"
#include "ui_widget.h"
#include <QDebug>

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    // ==========================================
    // 1. 初始化 QProgressBar
    // ==========================================
    progressBar = new QProgressBar(this);
    progressBar->setGeometry(100, 150, 400, 30);
    // 设置范围：0-100
    progressBar->setMinimum(0);
    progressBar->setMaximum(100);
    // 设置初始值：0
    progressBar->setValue(0);
    // 显示文本
    progressBar->setTextVisible(true);
    // 文本居中对齐
    progressBar->setAlignment(Qt::AlignCenter);
    // 文本格式：显示百分比
    progressBar->setFormat("%p%");

    // ==========================================
    // 2. 初始化 QTimer
    // ==========================================
    timer = new QTimer(this);
    // 设置间隔：100ms（0.1 秒）
    timer->setInterval(100);
    // 绑定 timeout 信号与 updateProgress 槽函数
    connect(timer, &QTimer::timeout, this, &Widget::updateProgress);
    // 启动定时器
    timer->start(100);

    qDebug() << "进度条开始增长...";
}

// ==========================================
// 3. 实现 updateProgress 槽函数
// ==========================================
void Widget::updateProgress()
{
    // 获取当前进度值
    int value = progressBar->value();

    // 如果进度达到最大值，停止定时器
    if (value >= progressBar->maximum()) {
        timer->stop();
        qDebug() << "进度条完成！";
        // 可以在这里添加"完成"后的逻辑，比如弹出提示框
        return;
    }

    // 进度值 +1
    progressBar->setValue(value + 1);
}

Widget::~Widget()
{
    // 析构时停止定时器（虽然父对象销毁时会自动处理，但显式停止更安全）
    if (timer->isActive()) {
        timer->stop();
    }
    delete ui;
}

6.3 代码详解

我们来逐部分解释代码：

  1. 初始化 QProgressBar ：
    • 创建 QProgressBar 对象，设置位置和大小；
    • 设置范围 0-100，初始值 0；
    • 显示文本，居中对齐，格式为百分比。
  2. 初始化 QTimer ：
    • 创建 QTimer 对象，设置间隔 100ms（0.1 秒）；
    • 绑定 timeout 信号到 updateProgress 槽函数 ------ 每 100ms 触发一次 updateProgress()；
    • 启动定时器。
  3. 实现 updateProgress() 槽函数 ：
    • 获取当前进度值；
    • 如果达到最大值，停止定时器，打印 "完成"；
    • 否则，进度值 +1，更新进度条。

完整示例代码：

cpp 复制代码 
#include "widget.h"
#include "ui_widget.h"

Widget::Widget(QWidget *parent)
    : QWidget(parent)
    , ui(new Ui::Widget)
{
    ui->setupUi(this);

    //OK大家，那么本文件我们就来学习QProgressBar控件，其实也就是进度条啦~~~大家都不陌生
    //这个也还是很简单的

    /**
     * @class QProgressBar
     * @brief Qt中用于可视化展示任务进度的进度条控件
     * @details QProgressBar是Qt提供的进度可视化核心控件，主要用于展示耗时任务的完成进度（如文件下载、数据加载、安装流程等）；
     *          支持自定义进度范围、显示方向、进度文本格式、文本对齐方式等，是界面中反馈任务进度的关键组件；
     *          重要提醒：类名拼写为QProgressBar（Progress=进度），切勿错误拼写成QProcessBar（Process=进程）！
     *
     * 【核心属性详解】
     *
     * ===================================== 属性1：minimum =====================================
     * @property QProgressBar::minimum
     * @brief 进度条的最小值属性
     * @details 该属性定义进度条进度范围的下限值，默认值为0；
     *          最小值必须小于等于最大值（若手动设置最小值大于最大值，Qt会自动交换二者），进度条的有效进度范围为 [minimum, maximum]。
     *
     * 【关联API详解】
     * 1. int minimum() const
     *    - 功能：获取当前设置的最小值
     *    - 返回值：int类型，默认返回0
     *
     * 2. void setMinimum(int min)
     *    - 功能：设置进度条最小值
     *    - 参数：min - 非负整数（常规场景建议设为0）
     *    - 示例：
     *      ui->progressBar->setMinimum(0); // 设置最小值为0（默认值）
     *      ui->progressBar->setMinimum(10); // 自定义最小值为10（需配合maximum>10）
     *
     * ===================================== 属性2：maximum =====================================
     * @property QProgressBar::maximum
     * @brief 进度条的最大值属性
     * @details 该属性定义进度条进度范围的上限值，默认值为100；
     *          特殊规则：若将最大值设为0，进度条会进入**繁忙模式**（无具体进度值，进度条色块来回滚动，适用于未知耗时的任务）。
     *
     * 【关联API详解】
     * 1. int maximum() const
     *    - 功能：获取当前设置的最大值
     *    - 返回值：int类型，默认返回100
     *
     * 2. void setMaximum(int max)
     *    - 功能：设置进度条最大值
     *    - 参数：max - 整数（≥minimum，设为0进入繁忙模式）
     *    - 示例：
     *      ui->progressBar->setMaximum(100); // 常规进度（0-100，百分比）
     *      ui->progressBar->setMaximum(0); // 繁忙模式（未知进度，进度条滚动）
     *      ui->progressBar->setMaximum(500); // 自定义进度范围（0-500）
     *
     * ===================================== 属性3：value =====================================
     * @property QProgressBar::value
     * @brief 进度条的当前进度值属性
     * @details 该属性表示进度条当前的进度值，取值范围严格限制在 [minimum, maximum] 之间；
     *          若当前值等于最大值，代表任务100%完成；若最大值设为0（繁忙模式），该属性失效（进度条无固定值）。
     *
     * 【关联API详解】
     * 1. int value() const
     *    - 功能：获取当前进度值
     *    - 返回值：int类型，默认返回0
     *
     * 2. void setValue(int val)
     *    - 功能：设置当前进度值
     *    - 参数：val - 整数，超出[minimum, maximum]范围时会被自动截断
     *    - 示例：
     *      ui->progressBar->setMinimum(0);
     *      ui->progressBar->setMaximum(100);
     *      ui->progressBar->setValue(50); // 设置当前进度为50（对应50%）
     *      ui->progressBar->setValue(120); // 超出最大值，自动截断为100
     *
     * ===================================== 属性4：alignment =====================================
     * @property QProgressBar::alignment
     * @brief 进度条内文本的对齐方式属性
     * @details 该属性控制进度条上显示的文本（百分比/数值）的对齐位置，默认值为Qt::AlignCenter；
     *          仅当textVisible为true时生效，支持Qt::Alignment枚举的水平对齐值，垂直对齐无效果。
     *
     * 【对齐枚举值详解】
     * | 枚举值              | 功能说明                     |
     * |---------------------|------------------------------|
     * | Qt::AlignLeft       | 文本左对齐                   |
     * | Qt::AlignRight      | 文本右对齐                   |
     * | Qt::AlignCenter     | 文本居中对齐（默认）|
     * | Qt::AlignJustify    | 文本两端对齐（效果同左对齐） |
     *
     * 【关联API详解】
     * 1. Qt::Alignment alignment() const
     *    - 功能：获取当前文本对齐方式
     *    - 返回值：Qt::Alignment枚举值，默认返回Qt::AlignCenter
     *
     * 2. void setAlignment(Qt::Alignment align)
     *    - 功能：设置文本对齐方式
     *    - 参数：align - 对齐枚举值（仅水平对齐生效）
     *    - 示例：
     *      ui->progressBar->setAlignment(Qt::AlignRight); // 文本右对齐
     *      ui->progressBar->setAlignment(Qt::AlignCenter); // 文本居中（默认）
     *
     * ===================================== 属性5：textVisible =====================================
     * @property QProgressBar::textVisible
     * @brief 进度条文本的显示开关属性
     * @details 该属性控制进度条上的数字/百分比文本是否可见，默认值为true（可见）；
     *          设为false时，仅显示进度条的色块，不显示任何文本，适用于仅需视觉反馈进度的场景。
     *
     * 【关联API详解】
     * 1. bool isTextVisible() const
     *    - 功能：获取文本是否可见
     *    - 返回值：true可见（默认），false隐藏
     *
     * 2. void setTextVisible(bool visible)
     *    - 功能：设置文本显示状态
     *    - 参数：visible - true显示文本，false隐藏文本
     *    - 示例：
     *      ui->progressBar->setTextVisible(false); // 隐藏进度文本，仅显示色块
     *
     * ===================================== 属性6：orientation =====================================
     * @property QProgressBar::orientation
     * @brief 进度条的显示方向属性
     * @details 该属性控制进度条是水平显示还是垂直显示，默认值为Qt::Horizontal（水平）；
     *          垂直进度条的进度增长方向受invertAppearance影响（正向从下到上，反向从上到下）。
     *
     * 【枚举值详解】
     * | 枚举值              | 功能说明                     |
     * |---------------------|------------------------------|
     * | Qt::Horizontal      | 水平进度条（默认）|
     * | Qt::Vertical        | 垂直进度条                   |
     *
     * 【关联API详解】
     * 1. Qt::Orientation orientation() const
     *    - 功能：获取当前显示方向
     *    - 返回值：Qt::Orientation枚举值，默认返回Qt::Horizontal
     *
     * 2. void setOrientation(Qt::Orientation orient)
     *    - 功能：设置进度条显示方向
     *    - 参数：orient - 方向枚举值
     *    - 示例：
     *      ui->progressBar->setOrientation(Qt::Vertical); // 设置为垂直进度条
     *
     * ===================================== 属性7：invertAppearance =====================================
     * @property QProgressBar::invertAppearance
     * @brief 进度条进度的反向增长属性
     * @details 该属性控制进度条的进度是否朝反方向增长，默认值为false（正向增长）；
     *          反向增长仅改变进度色块的填充方向，不影响进度值的计算。
     *
     * 【增长方向规则】
     * | 显示方向       | 正向增长（false）| 反向增长（true）|
     * |----------------|-------------------------|-------------------------|
     * | 水平（Horizontal） | 从左到右填充            | 从右到左填充            |
     * | 垂直（Vertical）   | 从下到上填充            | 从上到下填充            |
     *
     * 【关联API详解】
     * 1. bool invertAppearance() const
     *    - 功能：获取是否开启反向增长
     *    - 返回值：false正向（默认），true反向
     *
     * 2. void setInvertAppearance(bool invert)
     *    - 功能：设置进度增长方向
     *    - 参数：invert - true开启反向，false关闭
     *    - 示例：
     *      ui->progressBar->setInvertAppearance(true); // 水平进度条从右到左增长
     *
     * ===================================== 属性8：textDirection =====================================
     * @property QProgressBar::textDirection
     * @brief 进度条文本的朝向属性
     * @details 该属性控制进度条文本的显示朝向，主要适配垂直进度条的文本展示，默认值为QProgressBar::TopToBottom；
     *          水平进度条设置该属性无明显效果，仅垂直进度条生效。
     *
     * 【枚举值详解】
     * | 枚举值                  | 功能说明                     |
     * |-------------------------|------------------------------|
     * | QProgressBar::TopToBottom | 文本从上到下显示（默认）|
     * | QProgressBar::BottomToTop | 文本从下到上显示             |
     *
     * 【关联API详解】
     * 1. QProgressBar::TextDirection textDirection() const
     *    - 功能：获取文本朝向
     *    - 返回值：QProgressBar::TextDirection枚举值
     *
     * 2. void setTextDirection(QProgressBar::TextDirection dir)
     *    - 功能：设置文本朝向
     *    - 参数：dir - 文本朝向枚举值
     *    - 示例：
     *      ui->progressBar->setOrientation(Qt::Vertical); // 先设为垂直进度条
     *      ui->progressBar->setTextDirection(QProgressBar::BottomToTop); // 文本从下到上显示
     *
     * ===================================== 属性9：format =====================================
     * @property QProgressBar::format
     * @brief 进度条文本的显示格式属性
     * @details 该属性自定义进度条显示的文本格式，支持占位符替换，默认值为"%p%"（显示百分比）；
     *          仅当textVisible为true时生效，若设置为空字符串，文本区域仍保留但内容为空。
     *
     * 【占位符详解（核心）】
     * | 占位符 | 功能说明                                                                 |
     * |--------|--------------------------------------------------------------------------|
     * | %p     | 进度百分比（0-100，显示为"0%"~"100%"，最常用）|
     * | %v     | 进度当前数值（如最小值0、最大值100时，值50显示为"50"）|
     * | %m     | 剩余时间（毫秒，需手动结合定时器/任务逻辑关联，默认无有效数值）|
     * | %t     | 总时间（毫秒，需手动结合定时器/任务逻辑关联，默认无有效数值）|
     *
     * 【关联API详解】
     * 1. QString format() const
     *    - 功能：获取当前文本格式
     *    - 返回值：QString类型，默认返回"%p%"
     *
     * 2. void setFormat(const QString &format)
     *    - 功能：设置文本显示格式
     *    - 参数：format - 包含占位符的格式字符串
     *    - 示例：
     *      ui->progressBar->setFormat("%p%"); // 默认，显示"50%"
     *      ui->progressBar->setFormat("进度：%v/100"); // 显示"进度：50/100"
     *      ui->progressBar->setFormat("完成%p%，剩余%m ms"); // 需绑定时间逻辑才显示有效剩余时间
     *
     * 【典型使用示例】
     * // 示例1：常规水平进度条（0-100，百分比显示，居中文本）
     * ui->progressBar->setMinimum(0);
     * ui->progressBar->setMaximum(100);
     * ui->progressBar->setOrientation(Qt::Horizontal);
     * ui->progressBar->setTextVisible(true);
     * ui->progressBar->setAlignment(Qt::AlignCenter);
     * ui->progressBar->setFormat("%p%");
     * ui->progressBar->setValue(75); // 显示"75%"
     *
     * // 示例2：繁忙模式（未知进度，无文本）
     * ui->progressBar->setMaximum(0); // 开启繁忙模式
     * ui->progressBar->setTextVisible(false); // 隐藏文本
     *
     * // 示例3：垂直反向进度条（自定义格式）
     * ui->progressBar->setOrientation(Qt::Vertical);
     * ui->progressBar->setInvertAppearance(true); // 从上到下增长
     * ui->progressBar->setFormat("当前值：%v");
     * ui->progressBar->setValue(30); // 显示"当前值：30"
     */

}

Widget::~Widget()
{
    delete ui;
}

第七章 全文总结与学习建议

恭喜你！终于看完了这篇QProgressBar 常见属性详细解析！

如果你跟着文章一步步敲了代码，做了练习，那么现在你已经完全掌握了 QProgressBar 的核心内容：

  • 你知道了类名是 QProgressBar，不是 QProcessBar（这个坑一定要避开！）；
  • 你会用 minimum、maximum、value 设置进度范围和当前值，知道了繁忙模式 （maximum=0）的用法；
  • 你会用 orientation 让进度条水平或垂直显示，用 invertAppearance 让进度反向增长；
  • 你会用 textVisible 控制文本显隐，用 alignment 让文本居左 / 居右 / 居中（知道垂直对齐无效），用 format 自定义文本格式（重点掌握 %p 和 %v）；
  • 你还会用样式表自定义进度条的颜色，比如改成红色；
  • 你还完成了一个综合实战：用 QTimer 和 QProgressBar 实现定时增长的进度条。

毫不夸张地说，掌握了这些内容，你就掌握了 QProgressBar 开发的 90% 以上的需求！接下来，你可以用这些内容，实现各种你想要的进度条效果。

7.1 核心要点回顾

在结束之前，我们最后再回顾一下这篇文章的核心要点：

  1. 拼写警告 ：QProgressBar，不是 QProcessBar！
  2. 范围与值 ：
    • minimum 是最小值（默认 0），maximum 是最大值（默认 100），value 是当前值；
    • maximum=0 进入繁忙模式（未知进度，色块滚动）；
    • value 超出范围会自动截断，繁忙模式下失效。
  3. 视觉布局 ：
    • orientation：水平（Horizontal）或垂直（Vertical）；
    • invertAppearance：false 正向（水平从左到右，垂直从下到上），true 反向（水平从右到左，垂直从上到下）；
    • 仅改变视觉，不影响数值。
  4. 文本显示 ：
    • textVisible：true 显示文本，false 隐藏；
    • alignment：仅水平对齐生效（Left/Right/Center）；
    • textDirection：仅垂直进度条有用，知道即可；
    • format：重点！%p 百分比，%v 当前值，%m/%t 需手动关联。
  5. 样式表 ：用 QProgressBar::chunk 控制填充色块颜色。

7.2 最后的话

编程学习没有捷径，唯手熟尔。QProgressBar 的属性虽然看起来很多，但只要你多敲代码、多做练习、多踩坑、多排查，很快就能熟练掌握。

这篇文章虽然很长，但我相信，如果你认真看完了，跟着敲了代码，你一定会对 QProgressBar 有一个极其深刻的理解，再也不会为进度条的实现发愁。

感谢你阅读这篇文章，希望它能帮到你。我们下一篇 Qt 教程再见！

相关推荐
fanruitian1 小时前
python 机器学习 交叉验证train_test_split 网格搜索GridSearchCV
开发语言·python·机器学习
AlanAshley1 小时前
无 SIM 卡也能打 110？手机紧急呼叫能力的软硬件技术探究
开发语言·智能手机·php
ShineWinsu1 小时前
对于Qt：QLCDNumber常见属性以及QTimer的解析
服务器·数据库·c++·qt·gui·qtimer·qlcdnumber
modelmd1 小时前
Go 切片、映射常见使用场景
开发语言·后端·golang
xiaoye-duck1 小时前
《C++ 工具库实战》C++ 解析利器 JsonCpp：从基础使用到封装简易 JSON 工具
c++·json·第三方库
dialect_9 小时前
KMP算法
开发语言·c++·算法
总要学点什么10 小时前
第89篇：三维特效-螺旋圆效果——让螺旋臂卷起一圈圈外扩的涟漪
开发语言·javascript·ecmascript·webgl·cesium·空间分析·1024程序员节
听风吹等浪起11 小时前
第26章：ViT+InceptionDW+FocalLoss改进｜CT骨折影像二分类完整Pytorch实现（含PyQt5推理GUI）
pytorch·qt·分类
ShineWinsu11 小时前
对于Qt：QRadioButton常见属性以及QButtonGroup的解析
数据库·c++·qt·microsoft·gui·qradiobutton·qbuttongroup
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03GitHub 镜像站点04如何新建文件夹？ 电脑新建文件夹的4种方法05几个好用的ip纯净度检测网站06苹果iPA游戏软件资源下载网站07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08昇腾910B系列芯片完全指南：四款型号对比、服务器选型与大模型部署实战09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10Dify：一站式AI应用开发平台全解析与Windows部署指南