PyQt QtWaitingSpinner详解-为你的 Qt 程序带来丝滑等待动画

PyQt QtWaitingSpinner详解-为你的 Qt 程序带来丝滑等待动画

• [一、PyQt QtWaitingSpinner详解](#一、PyQt QtWaitingSpinner详解)
• • 1、核心特性
  • 2、基础使用示例
  • 3、高级用法
  • 4、安装方式
  • 5、注意事项
• 二、使用方法
• • 1、安装库
  • 2、测试源码
  • 3、效果展示

一、PyQt QtWaitingSpinner详解

QtWaitingSpinner 是一个用于显示加载状态的第三方动画控件，常用于异步操作等待场景。它不是 PyQt 官方组件，但被广泛集成到项目中。

1、核心特性

1. 动画效果

   实现旋转式加载动画，支持自定义：

   • 旋转速度（转速）
   • 线条数量
   • 线条长度/宽度
   • 颜色透明度渐变

2. 主要属性

   spinner = QtWaitingSpinner(parent)
   spinner.setRoundness(70.0)          # 圆度系数 [0.0, 100.0]
   spinner.setMinimumTrailOpacity(15.0) # 最小透明度
   spinner.setTrailFadePercentage(70.0) # 渐变百分比
   spinner.setNumberOfLines(12)        # 旋转线条数
   spinner.setLineLength(10)           # 线条长度(像素)
   spinner.setLineWidth(5)             # 线条宽度(像素)
   spinner.setInnerRadius(10)          # 内圆半径
   spinner.setRevolutionsPerSecond(1)  # 每秒转数
   spinner.setColor(QColor(61, 174, 233)) # 主色调

2、基础使用示例

from PyQt5.QtWidgets import QApplication, QMainWindow
from waitingspinner import QtWaitingSpinner  # 需单独导入

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        
        # 创建等待动画
        self.spinner = QtWaitingSpinner(self)
        self.spinner.setInnerRadius(15)
        self.spinner.setLineWidth(3)
        self.spinner.setNumberOfLines(8)
        self.spinner.resize(100, 100)
        self.spinner.move(150, 150)
        
        # 控制方法
        self.spinner.start()  # 开始旋转
        # self.spinner.stop()  # 停止旋转
        # self.spinner.isSpinning()  # 检查状态

if __name__ == "__main__":
    app = QApplication([])
    window = MainWindow()
    window.show()
    app.exec_()

3、高级用法

1. 集成到布局中

   layout = QVBoxLayout()
   layout.addWidget(QtWaitingSpinner())

2. 动态控制

   # 启动任务时显示
   def start_task(self):
       self.spinner.start()
       QTimer.singleShot(3000, self.complete_task)  # 模拟耗时操作
   
   # 任务完成时隐藏
   def complete_task(self):
       self.spinner.stop()

3. 样式定制

   spinner.setColor(QColor("#FF5733"))  # 自定义颜色
   spinner.setRevolutionsPerSecond(2)   # 加速旋转

4、安装方式

1. 下载 waitingspinner.py 文件（GitHub 开源项目）

2. 复制到项目目录

3. 导入使用：

   from waitingspinner import QtWaitingSpinner

5、注意事项

1. 确保在 GUI 主线程中控制启动/停止
2. 动画开启时会持续占用少量 CPU 资源
3. 推荐在以下场景使用：
   • 网络请求等待
   • 文件加载过程
   • 复杂计算等待期

该组件遵循 MIT 许可证，源码地址：
https://github.com/z3ntu/QtWaitingSpinner

二、使用方法

1、安装库

pip install pyqtwaitingspinner    # 通用版本

2、测试源码

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QMessageBox, QToolBar
from PyQt6.QtGui import QAction, QKeySequence, QColor
from PyQt6.QtCore import Qt
from pyqtwaitingspinner import SpinnerParameters, SpinDirection, WaitingSpinner


class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.resize(800,600)
        # 配置 SpinnerParameters
        params = SpinnerParameters(
            roundness=100.0,
            number_of_lines=8,
            line_length=40,
            line_width=40,
            inner_radius=60,
            revolutions_per_second=1.0,
            color=QColor(0, 170, 0),
            minimum_trail_opacity=1.0,
            trail_fade_percentage=67.0,
            spin_direction=SpinDirection.COUNTERCLOCKWISE,
            center_on_parent=True,
            disable_parent_when_spinning=False,
        )

        spinner = WaitingSpinner(self, params)
        spinner.start()



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

3、效果展示