Python PyQt6/PySide6获取主屏幕分辨率的代码示例

在基于 Python 构建桌面端图形界面（GUI）应用时，获取屏幕分辨率是处理窗口居中定位、自适应界面布局以及全屏显示等功能的基础操作。无论是使用 PyQt6 还是 PySide6，Qt 框架都通过 QScreen 类提供了统一且直接的接口。核心逻辑是先初始化 QApplication 实例，随后借助 QGuiApplication.primaryScreen() 获取主屏幕对象，并调用相应尺寸方法提取分辨率信息。

一、核心实现步骤与完整代码示例

获取主屏幕分辨率的操作流程可划分为三个标准步骤：第一步是初始化 Qt 应用全局上下文，第二步获取当前主显示器对应的 QScreen 对象，第三步调用几何信息方法读取具体宽高数值。

由于 PyQt6 与 PySide6 均遵循 Qt 6 的 API 规范，两者的代码除了导入包名不同外，类名与调用方法完全保持一致。下面分别提供独立的完整示例脚本。

1. PyQt6 获取主屏幕分辨率代码

import sys
from PyQt6.QtWidgets import QApplication
from PyQt6.QtGui import QGuiApplication

def get_screen_resolution_pyqt6():
    # 必须先实例化 QApplication，否则无法与系统窗口管理器交互
    app = QApplication(sys.argv)
    
    # 获取主屏幕对象
    screen = QGuiApplication.primaryScreen()
    if screen is None:
        print("未检测到有效的主屏幕")
        return

    # 1. 获取屏幕完整逻辑尺寸
    rect = screen.geometry()
    width = rect.width()
    height = rect.height()

    # 2. 获取去掉任务栏/菜单栏后的可用工作区尺寸
    avail_rect = screen.availableGeometry()
    avail_width = avail_rect.width()
    avail_height = avail_rect.height()

    # 3. 获取屏幕高分屏缩放比例与物理像素
    dpr = screen.devicePixelRatio()
    phys_width = int(width * dpr)
    phys_height = int(height * dpr)

    print(f"【PyQt6 屏幕参数获取结果】")
    print(f"屏幕名称: {screen.name()}")
    print(f"逻辑分辨率: {width} x {height}")
    print(f"工作区可用分辨率: {avail_width} x {avail_height}")
    print(f"缩放比例 (DPR): {dpr}")
    print(f"物理像素分辨率: {phys_width} x {phys_height}")

if __name__ == "__main__":
    get_screen_resolution_pyqt6()

2. PySide6 获取主屏幕分辨率代码

import sys
from PySide6.QtWidgets import QApplication
from PySide6.QtGui import QGuiApplication

def get_screen_resolution_pyside6():
    # 初始化应用实例
    app = QApplication(sys.argv)

    # 通过 QGuiApplication 访问主屏幕
    screen = QGuiApplication.primaryScreen()
    if screen is None:
        print("未检测到有效的主屏幕")
        return

    # 获取全屏尺寸与可用尺寸
    rect = screen.geometry()
    avail_rect = screen.availableGeometry()

    print(f"【PySide6 屏幕参数获取结果】")
    print(f"屏幕分辨率: {rect.width()} x {rect.height()}")
    print(f"可用工作区分辨率: {avail_rect.width()} x {avail_rect.height()}")

if __name__ == "__main__":
    get_screen_resolution_pyside6()

二、QGuiApplication 与 QScreen 的对象关系

理解 Qt 中屏幕对象的层级关系有助于在单显示器和多显示器环境中稳定获取所需分辨率。在 Qt 内部，屏幕管理由 QGuiApplication 统一调度，具体每一台显示设备抽象为独立的 QScreen 实体。

当系统接入多台显示器时，QGuiApplication.primaryScreen() 始终返回系统设置中指定的主显示器。如果需要遍历所有屏幕，可通过 QGuiApplication.screens() 获取列表，列表中第一项通常即为主屏幕。

三、关键概念差异：逻辑像素与物理像素

现代显示器普遍支持高分屏（如 2K、4K 屏幕或 Retina 屏幕），操作系统通常会启用缩放（如 125%、150% 或 200%）。这一机制导致了“逻辑像素”与“物理像素”的分离，这是开发中最容易产生混淆的概念。

在 PyQt6 与 PySide6 中：

• 逻辑分辨率：通过 screen.geometry() 或 screen.size() 返回的值属于逻辑坐标系。在给窗口、按钮或对话框设置宽高与位置（如 resize(800, 600)）时，使用的正是逻辑分辨率。
• 物理分辨率：代表面板实际的发光点阵列。如果需要将画面保存为与物理像素 1:1 对齐的图片，或者向底层图形缓冲提交渲染贴图，需要将逻辑分辨率乘以 screen.devicePixelRatio()。

四、实战应用：基于屏幕分辨率实现窗口精准居中

获取屏幕分辨率后，最常见的使用场景是将窗口精准定位在主屏幕正中央。需要特别注意的是，计算居中时应使用 availableGeometry() 而非 geometry()，以防窗口被底部的操作栏或任务栏遮挡。

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel
from PyQt6.QtCore import Qt

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("窗口自适应居中示例")
        self.resize(500, 320)

        # 在窗口中央展示当前居中坐标
        label = QLabel("窗口已精准居中于主工作区", self)
        label.setAlignment(Qt.AlignmentFlag.AlignCenter)
        self.setCentralWidget(label)

        # 执行居中定位
        self.center_on_primary_screen()

    def center_on_primary_screen(self):
        # 1. 获取主屏幕
        screen = QApplication.primaryScreen()
        if not screen:
            return

        # 2. 获取可用工作区几何矩形（排除任务栏和状态栏）
        available_geo = screen.availableGeometry()

        # 3. 计算居中坐标：(工作区起始位置 + (工作区可用尺寸 - 窗口尺寸) / 2)
        target_x = available_geo.x() + (available_geo.width() - self.width()) // 2
        target_y = available_geo.y() + (available_geo.height() - self.height()) // 2

        # 4. 移动窗口至目标位置
        self.move(target_x, target_y)

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

该示例通过获取 available_geo.x() 与 available_geo.y()，保证了在任务栏被放置在屏幕上方或左侧等非常规布局下，居中计算依然能够保持准确。

五、QScreen 常用获取方法对照与选型

为满足不同的业务场景，下表整理了 QScreen 提供的几组高频接口差异与适用范围：

六、常见注意事项与避坑指南

1. 避免在未初始化 QApplication 前获取屏幕：调用 QGuiApplication.primaryScreen() 的前置条件是应用上下文已经构建。如果在声明 app = QApplication(sys.argv) 之前尝试调用该方法，Qt 将返回 None，后续访问属性会触发 AttributeError。
2. 弃用旧版 QDesktopWidget：在早期的 PyQt5/PySide2 中，部分教程习惯使用 QApplication.desktop() 返回的 QDesktopWidget 来获取屏幕大小。该模块在 Qt 6 中已被彻底移除，请统一采用 QScreen 接口。
3. 监听屏幕分辨率动态变化：在笔记本外接显示器或用户手动修改分辨率时，若需要动态调整窗口尺寸，可以通过 screen.geometryChanged 信号绑定回调函数进行实时响应。