PyQt5中QDockWidget双击标题栏无法重新停靠的问题排查与解决

1. 失效原因 #

在Qt 4（对应PyQt4）中，浮动状态的QDockWidget双击标题栏会触发停靠操作，同时触发topLevelChanged事件。但Qt 5（对应PyQt5）对QDockWidget的交互行为做了修改：浮动的QDockWidget双击标题栏默认触发窗口的最大化/还原操作，而非停靠，因此不会触发topLevelChanged事件，导致原有逻辑失效。

2. 修复方案 #

可以通过自定义QDockWidget，拦截标题栏的双击事件，手动触发停靠行为。以下是两种可行实现方式：

方式一：给标题栏安装事件过滤器 #

继承QDockWidget，找到内置的标题栏控件并安装事件过滤器，捕获双击事件后强制设置为非浮动状态：

from PyQt5.QtWidgets import QDockWidget, QWidget
from PyQt5.QtCore import QEvent

class DockWidgetWithDoubleClickDock(QDockWidget):
    def __init__(self, title, parent=None):
        super().__init__(title, parent)
        # 获取QDockWidget的内置标题栏（Qt内部对象名固定为qt_dockwidget_titlebar）
        self.title_bar = self.findChild(QWidget, "qt_dockwidget_titlebar")
        if self.title_bar:
            self.title_bar.installEventFilter(self)

    def eventFilter(self, obj, event):
        # 仅处理标题栏的双击事件
        if obj == self.title_bar and event.type() == QEvent.MouseButtonDblClick:
            if self.isFloating():
                # 设置为非浮动，触发停靠
                self.setFloating(False)
                return True  # 拦截原事件，避免触发最大化
        return super().eventFilter(obj, event)

方式二：重写鼠标双击事件 #

如果无法通过对象名找到标题栏，也可以重写mouseDoubleClickEvent，判断点击位置是否属于标题栏区域：

from PyQt5.QtWidgets import QDockWidget
from PyQt5.QtCore import Qt

class DockWidgetWithDoubleClickDock(QDockWidget):
    def __init__(self, title, parent=None):
        super().__init__(title, parent)

    def mouseDoubleClickEvent(self, event):
        # 判断点击位置是否在标题栏范围内（标题栏高度可通过样式或默认值估算，这里用25作为近似值）
        if event.y() <= 25 and event.button() == Qt.LeftButton and self.isFloating():
            self.setFloating(False)
            event.accept()
            return
        super().mouseDoubleClickEvent(event)

使用时直接替换原有的QDockWidget为自定义的类即可恢复双击停靠行为。

3. 文档说明位置 #

该行为变更记录在Qt 5迁移指南以及QDockWidget类的官方文档中：

• Qt 5迁移指南中明确提到，QDockWidget的标题栏交互逻辑在Qt 5中调整，浮动窗口的双击行为从停靠改为最大化/还原；
• QDockWidget类文档的isFloating()和setFloating()方法说明里，也间接提及了默认交互行为的变更，同时说明可通过自定义标题栏或事件拦截来修改默认行为。

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