QGIS3.22运行PyQGIS脚本时QMessageBox消息显示时序异常如何解决

问题背景 #

原有PyQGIS脚本在QGIS 2.18环境下编写，核心功能为打开包含约9个图层的QGIS项目，为了提示用户图层加载、渲染的等待过程，添加了QMessageBox弹窗和顶部消息栏状态提示，初始代码如下：

#start the script
from qgis.PyQt import QtWidgets
message = "Wait to open the airspace project..."
msg = QtWidgets.QMessageBox()
msg.setText(message)
msg.show()
qgis.utils.iface.messageBar().pushMessage("Wait", message)

for i in range(1000):
    print(i)
qgis.utils.iface.messageBar().pushMessage("Done", "The process is done")
msg.setText("The process is done")

不同版本运行表现 #

• QGIS 2.18：消息栏与QMessageBox优先展示等待提示，之后启动循环逻辑打印i值，流程执行完毕后二者同步展示完成提示，时序完全符合预期。
• QGIS 3.22.8-Białowieża：
  • 循环逻辑直接启动，等待提示未正常展示，QMessageBox弹出但无文本内容
  • 循环执行完成后，消息栏与弹窗才会显示完成提示
  • 完成提示很快从消息栏消失，反而切回最初的等待提示，无法为用户提供有效的流程状态反馈

问题根因 #

QGIS 3.x 基于Qt5重构了主线程事件调度逻辑，和QGIS 2.x的核心差异是：所有UI更新操作（包括弹窗文本渲染、消息栏内容刷新）都会先进入主线程事件队列排队，只有主线程空闲时才会依次执行。
现有代码在调用msg.show()、推送等待提示后，立刻启动了独占主线程的同步循环逻辑，主线程被循环完全占满，没有资源处理队列中的UI渲染请求，等待提示根本没机会绘制到界面上。等循环跑完主线程空闲时，队列中同时堆积了「显示等待提示」「显示完成提示」两个UI请求，就会出现提示时序错乱、完成提示被等待提示覆盖的异常。
QGIS 2.x 版本在UI组件调用后会主动触发一次事件队列处理，因此不会出现该阻塞问题。

修复方案 #

方案1：最小代码改动（适配原有逻辑） #

在展示完等待提示、启动耗时逻辑前，主动调用processEvents()强制Qt处理当前队列中堆积的UI事件，保证等待提示先渲染完成，再执行后续同步任务。修改后代码如下：

#start the script
from qgis.PyQt import QtWidgets, QtCore
message = "Wait to open the airspace project..."
msg = QtWidgets.QMessageBox()
msg.setText(message)
msg.show()
qgis.utils.iface.messageBar().pushMessage("Wait", message)
# 强制处理当前队列中的UI事件，确保等待提示优先渲染
QtWidgets.QApplication.processEvents(QtCore.QEventLoop.AllEvents, 100)

for i in range(1000):
    print(i)
    # 若单步循环耗时较长，可在循环内加这行避免UI假死
    # QtWidgets.QApplication.processEvents()

qgis.utils.iface.messageBar().popWidget() # 先清掉之前的等待提示
qgis.utils.iface.messageBar().pushMessage("Done", "The process is done", duration=5)
msg.setText("The process is done")
# 最后刷一次事件，确保完成提示正常显示
QtWidgets.QApplication.processEvents()

注意：如果实际业务中的图层加载是异步触发的，不要用同步循环等待加载完成，要监听QgsProject.instance().readProject或者图层加载完成的信号，再触发完成提示更新，避免时序不准。

方案2：规范实现（推荐长期使用） #

QGIS 3.x 不推荐在主线程执行长耗时同步任务，否则不仅会出现UI提示异常，还会导致整个QGIS窗口假死无响应。更合理的实现方式：

• 短时间等待：调用QtWidgets.QApplication.setOverrideCursor(QtCore.Qt.WaitCursor)将鼠标改为等待转圈样式，配合消息栏提示即可，任务完成后调用restoreOverrideCursor()恢复鼠标
• 长时间加载任务：使用QGIS内置的QgsTask类将图层加载逻辑封装为后台任务，通过任务的progressChanged、taskCompleted信号更新前台UI提示，完全不会阻塞主线程，从根源避免事件阻塞问题

踩坑提醒 #

• 禁止在QGIS主线程中调用time.sleep()做等待，该方法会完全阻塞事件循环，和同步循环的效果一致，都会导致UI卡死
• 消息栏推送新提示前，建议先调用popWidget()清理之前的同类型提示，避免旧提示超时后覆盖新提示的异常

内容的提问来源于stack exchange，提问作者Marian Tudorache