Ubuntu 22.04下PySide6的QDockWidget无法拖拽浮动问题

问题描述 #

使用PySide6开发GUI时，在Ubuntu 22.04系统中遇到QDockWidget异常：停靠组件初始化正常，但无法拖拽为独立窗口，仅能通过标题栏移动到其他停靠区域。相同代码在Windows 11下可正常实现拖拽浮动功能。

环境信息 #

• 系统：Ubuntu Linux 22.04（Python 3.10.12，切换虚拟环境版本无效）
• PySide6版本：6.9.0

复现步骤 #

• 创建包含QDockWidget的QMainWindow实例
• 尝试拖拽停靠组件的标题栏

报错信息 #

拖拽操作触发时，控制台输出如下错误：

This plugin supports grabbing the mouse only for popup windows.

已尝试操作 #

手动调用setFeatures开启移动、浮动、关闭功能，问题未得到解决。

最小复现代码 #

import sys
from PySide6.QtWidgets import (QApplication, QMainWindow, QDockWidget, 
                              QTextEdit, QLabel, QVBoxLayout, QWidget)
from PySide6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("QDockWidget Test")
        self.resize(800, 600)
        
        # 中央组件
        central_widget = QWidget()
        central_layout = QVBoxLayout(central_widget)
        central_layout.addWidget(QLabel("Central Widget"))
        self.setCentralWidget(central_widget)
        
        # 创建停靠组件
        self.terminal_dock = QDockWidget("Terminal", self)
        self.terminal_dock.setObjectName("terminal_dock")
        self.terminal_dock.setAllowedAreas(Qt.AllDockWidgetAreas)
        terminal_content = QTextEdit()
        terminal_content.setReadOnly(True)
        terminal_content.setStyleSheet("background-color: black; color: white;")
        terminal_content.setText("$ Terminal (Placeholder)\n$ _")
        self.terminal_dock.setWidget(terminal_content)
        self.addDockWidget(Qt.BottomDockWidgetArea, self.terminal_dock)
        
        # 额外停靠组件
        self.info_dock = QDockWidget("Info Panel", self)
        self.info_dock.setObjectName("info_dock")
        self.info_dock.setAllowedAreas(Qt.AllDockWidgetAreas)
        info_content = QWidget()
        info_layout = QVBoxLayout(info_content)
        info_layout.addWidget(QLabel("Info Panel Content"))
        self.info_dock.setWidget(info_content)
        self.addDockWidget(Qt.RightDockWidgetArea, self.info_dock)

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

解决方案 #

该问题源于Ubuntu 22.04默认使用的Wayland显示服务器对Qt窗口抓取API的支持不完善，以下两种方法可解决：

方法1：强制使用X11后端启动程序 #

在运行脚本时通过环境变量指定Qt使用X11：

QT_QPA_PLATFORM=xcb python your_script_name.py

也可在代码开头（QApplication初始化前）设置环境变量：

import os
os.environ["QT_QPA_PLATFORM"] = "xcb"

方法2：系统层面切换到X11会话 #

1. 登录Ubuntu时，点击登录界面右下角的齿轮图标
2. 选择Ubuntu on Xorg选项完成登录
3. 重新运行程序即可正常拖拽QDockWidget为独立窗口

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