QProgressBar Class
QProgressBar 控件提供水平或垂直的进度条。更多内容...
| 标题： | #include <QProgressBar> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake： | QT += widgets |
| 继承自： | QWidget |
公共类型
| enum | Direction { TopToBottom, BottomToTop } |
属性
|
|
公共函数
| QProgressBar(QWidget *parent = nullptr) | |
| virtual | ~QProgressBar() |
| Qt::Alignment | alignment() const |
| QString | format() const |
| bool | invertedAppearance() const |
| bool | isTextVisible() const |
| int | maximum() const |
| int | minimum() const |
| Qt::Orientation | orientation() const |
| void | resetFormat() |
| void | setAlignment(Qt::Alignment alignment) |
| void | setFormat(const QString &format) |
| void | setInvertedAppearance(bool invert) |
| void | setTextDirection(QProgressBar::Direction textDirection) |
| void | setTextVisible(bool visible) |
| virtual QString | text() const |
| QProgressBar::Direction | textDirection() const |
| int | value() const |
重新实现的公共函数
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
公共插槽
| void | reset() |
| void | setMaximum(int maximum) |
| void | setMinimum(int minimum) |
| void | setOrientation(Qt::Orientation) |
| void | setRange(int minimum, int maximum) |
| void | setValue(int value) |
信号
| void | valueChanged(int value) |
受保护函数
| virtual void | initStyleOption(QStyleOptionProgressBar *option) const |
重新实现的受保护函数
| virtual bool | event(QEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
详细说明
进度条用于向用户显示操作的进度，并让用户确信应用程序仍在运行。
进度条采用“步长”的概念。您通过指定可能的最小和最大步长值来设置它，当您随后向其提供当前步长值时，它将显示已完成步数的百分比。该百分比通过将进度（value() -minimum())）除以maximum() -minimum()）来计算。
您可以通过setMinimum() 和setMaximum 指定步数的最小值和最大值。当前步数通过setValue() 设置。使用reset() 可将进度条重置为起始位置。
如果最小值和最大值均设置为 0，进度条将显示忙碌指示符，而非步骤百分比。例如，当使用QNetworkAccessManager 下载项目时，若无法确定所下载项目的大小，此功能便十分有用。
另请参阅 QProgressDialog 。
成员类型文档
enum QProgressBar::Direction
指定text 在垂直进度条中的读取方向。
| 常量 | 值 | 描述 |
|---|---|---|
QProgressBar::TopToBottom | 0 | 文本顺时针旋转 90 度。 |
QProgressBar::BottomToTop | 1 | 文本顺时针旋转 90 度。 |
请注意，是否绘制文本取决于样式。目前，CleanLooks 和 Plastique 样式会绘制文本，而 Mac、Windows 和 Windows Vista 样式则不会。
另请参阅 textDirection 。
属性文档
alignment : Qt::Alignment
该属性用于指定进度条的对齐方式
访问函数：
| Qt::Alignment | alignment() const |
| void | setAlignment(Qt::Alignment alignment) |
format : QString
该属性存储用于生成当前文本的字符串
%p - 将被替换为已完成百分比。%v - 将被替换为当前值。%m - 将被替换为总步数。
默认值为“%p%”。
访问函数：
| QString | format() const |
| void | setFormat(const QString &format) |
| void | resetFormat() |
另请参阅 text()。
invertedAppearance : bool
该属性控制进度条是否以反向方式显示进度
如果此属性设置为true ，进度条将朝相反方向增长（例如从右向左）。默认情况下，进度条不反向显示。
访问函数：
| bool | invertedAppearance() const |
| void | setInvertedAppearance(bool invert) |
另请参阅 ` orientation ` 和 `layoutDirection`。
maximum : int
该属性用于存储进度条的最大值
设置此属性时，系统会根据需要调整minimum ，以确保范围保持有效。如果当前值超出新范围，则会通过reset()重置进度条。
访问函数：
| int | maximum() const |
| void | setMaximum(int maximum) |
minimum : int
该属性用于指定进度条的最小值
设置此属性时，系统会根据需要调整maximum ，以确保范围保持有效。如果当前值超出新范围，则会通过reset()重置进度条。
访问函数：
| int | minimum() const |
| void | setMinimum(int minimum) |
orientation : Qt::Orientation
该属性用于指定进度条的方向
方向必须为Qt::Horizontal （默认值）或Qt::Vertical 。
访问函数：
| Qt::Orientation | orientation() const |
| void | setOrientation(Qt::Orientation) |
另请参阅 invertedAppearance 和textDirection 。
[read-only] text : QString
该属性用于存储与进度条一起显示的说明性文本
返回的文本与进度条中央（或在某些样式中位于左侧）显示的文本相同。
文本中显示的进度可能小于最小值，这表示在设置任何进度之前，进度条处于“重置”状态。
在默认实现中，该文本要么包含一个表示当前进度的百分比值，要么因进度条处于重置状态而为空。
访问函数：
| virtual QString | text() const |
textDirection : Direction
此属性用于指定垂直进度条的text 的阅读方向
此属性对水平进度条没有影响。默认情况下，阅读方向为QProgressBar::TopToBottom 。
访问函数：
| QProgressBar::Direction | textDirection() const |
| void | setTextDirection(QProgressBar::Direction textDirection) |
另请参阅 orientation 和textVisible 。
textVisible : bool
该属性用于控制是否显示当前的完成百分比
该属性可能会被样式忽略（例如，QMacStyle 绝不会绘制该文本）。
访问函数：
| bool | isTextVisible() const |
| void | setTextVisible(bool visible) |
另请参阅 textDirection 。
value : int
该属性存储进度条的当前值
若尝试将当前值更改为超出最小值-最大值范围的数值，则对当前值不会产生任何影响。
访问函数：
| int | value() const |
| void | setValue(int value) |
通知信号：
| void | valueChanged(int value) |
成员函数文档
[explicit] QProgressBar::QProgressBar(QWidget *parent = nullptr)
根据给定的parent 创建一个进度条。
默认情况下，最小步长设置为 0，最大步长设置为 100。
另请参阅 setRange()。
[virtual noexcept] QProgressBar::~QProgressBar()
析构函数。
[override virtual protected] bool QProgressBar::event(QEvent *e)
重写了：QWidget::event(QEvent *event)。
[virtual protected] void QProgressBar::initStyleOption(QStyleOptionProgressBar *option) const
使用QProgressBar 中的值初始化option 。当子类需要QStyleOptionProgressBar 时，但又不想自己填写所有信息，此方法非常有用。
另请参阅 QStyleOption::initFrom()。
[override virtual] QSize QProgressBar::minimumSizeHint() const
重新实现了属性QWidget::minimumSizeHint 的访问函数。
[override virtual protected] void QProgressBar::paintEvent(QPaintEvent *)
重写了：QWidget::paintEvent(QPaintEvent *event)。
[slot] void QProgressBar::reset()
重置进度条。进度条将“回溯”至起始位置，且不显示任何进度。
[slot] void QProgressBar::setRange(int minimum, int maximum)
将进度条的最小值和最大值分别设置为minimum 和maximum 。
如果maximum 小于minimum ，则minimum 将成为唯一的有效值。
如果当前值超出新范围，则使用reset() 重置进度条。
可通过 setRange(0, 0) 将QProgressBar 设置为未确定状态。
[override virtual] QSize QProgressBar::sizeHint() const
重新实现了属性QWidget::sizeHint 的访问函数。
[signal] void QProgressBar::valueChanged(int value)
当进度条显示的值发生变化时，会触发此信号。value 是进度条显示的新值。
注意： 这是属性 `value`的通知 信号。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
