PySide6从0开始学习的笔记（十二） QProgressBar（进度条）

QProgressBar 是 PySide6 中用于显示任务进度的可视化组件，适用于文件下载、数据处理、任务执行等需要展示进度的场景。它支持确定性进度 （0-100%）和不确定性进度（未知耗时的任务），提供了丰富的样式和交互配置。

一、基本使用

1. 核心步骤

导入 QProgressBar 类
创建实例并设置基本属性（范围、初始值、文本显示等）
将组件添加到界面布局
通过 setValue() 更新进度

2. 最简示例

复制代码

import sys

from PySide6.QtWidgets import QApplication, QWidget, QVBoxLayout, QProgressBar, QPushButton

app = QApplication(sys.argv)

window = QWidget()
layout = QVBoxLayout()
window.setLayout(layout)

progress_bar = QProgressBar()
progress_bar.setRange(0, 100)
progress_bar.setValue(0)
progress_bar.setFormat("当前进度：%p%")

def forward_progress():
    current_value = progress_bar.value()
    current_value += 1
    if current_value >= 100:
        current_value = 100
    progress_bar.setValue(current_value)
btn_start = QPushButton("开始进度")
btn_start.clicked.connect(forward_progress)


layout.addWidget(progress_bar)
layout.addWidget(btn_start)
window.show()

sys.exit(app.exec())

二、核心属性与方法

1. 进度范围与值

方法 / 属性	说明
`setRange(min, max)`	设置进度范围（默认 0-100），如 `setRange(0, 500)` 表示总进度为 500 步
`minimum()`/`maximum()`	获取最小 / 最大值
`setValue(value)`	设置当前进度值（必须在 min-max 范围内）
`value()`	获取当前进度值
`reset()`	重置进度条到初始状态（值为 min，文本清空）

2. 文本显示控制

方法	说明
`setFormat(format_str)`	自定义进度文本格式：- `%p`：百分比（默认）- `%v`：当前值- `%m`：最大值- 示例：`setFormat("已完成 %v/%m")`
`setAlignment(alignment)`	设置文本对齐方式（如 `Qt.AlignCenter`）
`setTextVisible(bool)`	是否显示进度文本（默认 True）
`format()`	获取当前文本格式

3. 不确定性进度（转圈 / 脉动）

适用于无法预估耗时的任务（如下载未知大小的文件）：

python

运行

复制代码

# 设置为不确定模式
self.progress_bar.setRange(0, 0)  # 0-0 表示不确定

# 恢复确定模式
self.progress_bar.setRange(0, 100)

注：不确定模式下，进度条会显示一个来回移动的滑块（样式取决于系统）。

4. 样式定制（QSS）

通过 Qt 样式表自定义进度条外观，示例：

复制代码

self.progress_bar.setStyleSheet("""
    QProgressBar {
        border: 2px solid #ccc;  /* 边框 */
        border-radius: 5px;      /* 圆角 */
        text-align: center;      /* 文本居中 */
        height: 30px;            /* 高度 */
    }
    QProgressBar::chunk {
        background-color: #2196F3;  /* 进度条颜色 */
        border-radius: 5px;         /* 进度块圆角 */
        width: 10px;                /* 进度块宽度（步进） */
    }
    /* 不确定模式样式 */
    QProgressBar:indeterminate {
        background-color: #f0f0f0;
    }
    QProgressBar:indeterminate::chunk {
        background-color: #FF9800;
    }
""")

三、高级用法

1. 实时进度更新（多线程）

进度更新通常需要结合多线程（避免 UI 阻塞），示例：

复制代码

import sys
from PySide6.QtWidgets import (QApplication, QWidget, QProgressBar, 
                               QVBoxLayout, QPushButton)
from PySide6.QtCore import (QThread, Signal, Qt)

# 工作线程
class WorkerThread(QThread):
    progress_update = Signal(int)  # 进度更新信号
    finished = Signal()            # 完成信号

    def run(self):
        for i in range(101):
            self.progress_update.emit(i)
            self.msleep(50)  # 模拟耗时操作
        self.finished.emit()

# 主窗口
class ProgressBarThreadDemo(QWidget):
    def __init__(self):
        super().__init__()
        self.initUI()

    def initUI(self):
        self.setWindowTitle("QProgressBar 多线程示例")
        self.resize(400, 150)

        self.progress_bar = QProgressBar()
        self.progress_bar.setRange(0, 100)
        self.progress_bar.setValue(0)

        self.btn_start = QPushButton("开始任务")
        self.btn_start.clicked.connect(self.start_task)

        layout = QVBoxLayout()
        layout.addWidget(self.progress_bar)
        layout.addWidget(self.btn_start)
        self.setLayout(layout)

        # 创建线程
        self.worker = WorkerThread()
        self.worker.progress_update.connect(self.update_progress)
        self.worker.finished.connect(self.on_task_finished)

    def start_task(self):
        self.btn_start.setEnabled(False)
        self.worker.start()

    def update_progress(self, value):
        self.progress_bar.setValue(value)

    def on_task_finished(self):
        self.btn_start.setEnabled(True)
        self.progress_bar.setValue(100)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    demo = ProgressBarThreadDemo()
    demo.show()
    sys.exit(app.exec())

2. 进度条分段显示

通过自定义绘制实现分段进度（如不同阶段用不同颜色）：

复制代码

from PySide6.QtWidgets import QProgressBar
from PySide6.QtGui import QPainter, QColor

class SegmentedProgressBar(QProgressBar):
    def __init__(self, parent=None):
        super().__init__(parent)
        self.segments = [(0, 50, QColor(21, 150, 243)),  # 0-50% 蓝色
                         (50, 80, QColor(255, 152, 0)), # 50-80% 橙色
                         (80, 100, QColor(244, 67, 54))] # 80-100% 红色

    def paintEvent(self, event):
        painter = QPainter(self)
        painter.setRenderHint(QPainter.Antialiasing)

        # 绘制背景
        bg_rect = self.rect()
        painter.setPen(QColor("#ccc"))
        painter.setBrush(QColor("#f0f0f0"))
        painter.drawRoundedRect(bg_rect, 5, 5)

        # 绘制分段进度
        total_width = bg_rect.width() - 4
        current_value = self.value()
        max_value = self.maximum()

        for start, end, color in self.segments:
            if current_value < start:
                break
            # 计算分段宽度
            seg_end = min(end, current_value)
            seg_width = (seg_end - start) / max_value * total_width
            seg_rect = bg_rect.adjusted(2, 2, -2, -2)
            seg_rect.setWidth(seg_width)
            seg_rect.setX(2 + (start / max_value) * total_width)

            painter.setBrush(color)
            painter.setPen(Qt.NoPen)
            painter.drawRoundedRect(seg_rect, 3, 3)

        # 绘制文本
        painter.setPen(QColor("#333"))
        painter.drawText(bg_rect, Qt.AlignCenter, f"{current_value}%")

# 使用示例
if __name__ == "__main__":
    app = QApplication(sys.argv)
    bar = SegmentedProgressBar()
    bar.setRange(0, 100)
    bar.setValue(70)
    bar.resize(400, 40)
    bar.show()
    sys.exit(app.exec())

四、常见问题

UI 阻塞 ：直接在主线程更新进度（如循环 setValue）会导致界面卡死，需用 QThread 或 QTimer。
进度条不显示 ：检查 setRange 是否正确（默认 0-100，若设为 0-0 则为不确定模式），或布局是否正确添加组件。
文本不显示 ：确保 setTextVisible(True)，且样式表未覆盖文本（如 color: transparent）。
样式不生效 ：QSS 语法错误（如缺少 ::chunk 后缀），或系统样式覆盖自定义样式（可设置 setStyle(QStyleFactory.create("Fusion")) 强制使用 Fusion 样式）。

五、总结

QProgressBar 是 PySide6 中轻量且灵活的进度展示组件，核心能力包括：

支持确定 / 不确定进度模式
自定义文本格式和样式
结合多线程实现无阻塞进度更新
可通过自定义绘制实现复杂分段效果

实际开发中，需根据场景选择合适的进度更新方式（定时器 / 多线程），并通过 QSS 适配界面风格。