简介面向具备一定 Qt 基础、希望实现仿 QQ 截图工具的开发者这套代码演示了如何用 C 构建一个可后台运行、支持全局快捷键唤醒的屏幕捕捉程序解决主窗口最小化后无法快速截图的常见问题。资源共 27 个文件以 C 源文件与头文件为主辅以工程文件、项目配置、界面定义及说明文档配套的全局热键库完整覆盖 Windows、macOS、X11 三种平台整个压缩包仅 52KB结构相当紧凑。核心实现包括阴影小部件的绘制逻辑与主窗口交互入口从半透明预览区的绘制、屏幕抓取到快捷键的后台响应与截图保存流程完整即使窗口最小化程序也能持续监听按键这对理解全局热键与事件循环配合、无边框窗口阴影渲染以及屏幕捕获技术都很有帮助。目前已有 312 人学习代码量小但模块划分清晰适合按需移植到自己的 Qt 项目中。1. 截图工具看着简单后台截图才是门槛很多人以为 Qt 截图功能就是一个全屏窗口加鼠标拖拽做完才发现真正的难点是“后台截图”。我拆过好几个仿 QQ 截图的 Qt 项目最典型的翻车点在于——按下全局热键时截图程序的窗口必须先隐藏然后再抓取屏幕否则你截下来的图里永远带着自己软件的窗口。shadewidget.rar 这个资源包解决的就是这条完整链路全局热键触发、无痕后台运行、仿 QQ 截图交互、标注合成与保存。适合正在用 Qt/C 或 PySide 做工具类软件、需要给产品内置截图能力的开发者也适合想搞清楚“为什么我的截图黑屏/偏移/截到自己”的入门者。它不是一个只画框框的 Demo而是一个能直接接进业务的截图模块。2. 后台截图与全局热键先让软件“不动声色”2.1 截图方案选型QScreen 抓屏与窗口 grab 的差别后台截图的第一件事是选对抓屏 API。Qt 里有两个常用入口QWidget::grab()和QScreen::grabWindow()。前者是把某个控件树渲染成 QPixmap适合截取软件自己的界面后者是从屏幕上抓取原生像素适合全局截图。我用 PySide6 做演示底层逻辑和 C/Qt 的 QScreen::grabWindow 一致from PySide6.QtGui import QGuiApplication, QScreen from PySide6.QtCore import QRect def grab_full_screen(): app QGuiApplication.instance() screens app.screens() # 拿到所有屏幕的虚拟桌面几何区域 virtual_rect QRect() for screen in screens: virtual_rect virtual_rect.united(screen.geometry()) # 参数传虚拟桌面矩形注意用的是设备像素还是逻辑像素 pixmap screens[0].grabWindow(0, virtual_rect.x(), virtual_rect.y(), virtual_rect.width(), virtual_rect.height()) return pixmap这里有两个常见误区。误区一grabWindow(0)不传参数时只抓主屏幕。扩展屏内容不在结果里需要自己遍历 QGuiApplication.screens()把每块屏幕的几何区域 union 起来再作为矩形传给第一个屏幕去抓。误区二传矩形的宽高是逻辑像素但在高 DPI 屏幕上抓出来的 QPixmap 尺寸经常比逻辑尺寸大这是系统缩放策略造成的。后面会在避坑章节单独展开。选 QScreen 而不是直接用一个隐藏的全屏 QWidget 去渲染并截图原因是QWidget 方式依赖窗口系统合成器在远程桌面或禁用桌面合成时会得到黑屏而 QScreen 抓的是底层帧缓冲稳定性好得多。我在某跨平台系统里从 QWidget 方案切到 QScreen 方案后黑屏反馈基本清零。2.2 全局热键QShortcut 的局限与事件过滤器方案后台截图的“后台”二字意味着快捷键在软件没有焦点时也要生效。Qt 的 QShortcut 只能处理程序内部的按键一旦窗口最小化、失焦或隐藏它就失灵了。正确的做法是调用操作系统级别的热键注册接口然后通过 Qt 的事件过滤器接收回调。在 Windows 上做法是 RegisterHotKey 注册全局热键随后在 QAbstractNativeEventFilter 里拦截 WM_HOTKEY 消息。PySide6 里可以这样写一个过滤器类from PySide6.QtCore import QAbstractNativeEventFilter import ctypes MOD_NOREPEAT 0x4000 WM_HOTKEY 0x0312 class GlobalHotkeyFilter(QAbstractNativeEventFilter): def __init__(self, hotkey_id): super().__init__() self.hotkey_id hotkey_id self.activated False def nativeEventFilter(self, event_type, message): if event_type bwindows_generic_MSG: msg ctypes.wintypes.MSG.from_address(message.__int__()) if msg.message WM_HOTKEY and msg.wParam self.hotkey_id: self.activated True return False # 不拦截让 Qt 继续处理 return False注册的代码放在程序启动处user32 ctypes.windll.user32 hotkey_id 0x0001 # 0x31 是数字键 1 的虚拟键码MOD_NOREPEAT 防止按住时重复触发 user32.RegisterHotKey(None, hotkey_id, MOD_NOREPEAT, 0x31) filter GlobalHotkeyFilter(hotkey_id) app.installNativeEventFilter(filter)注意两个参数。虚拟键码 0x31 对应主键盘数字 1组合键没加 MOD_CONTROL 或 MOD_SHIFT所以只按数字 1 就能触发这适合快速唤起截图如果你担心误触可以改成 CtrlShiftA 的组合把修饰键参数换成 MOD_CONTROL | MOD_SHIFT0x0002 | 0x0004虚拟键码换成 0x41。注册成功后程序主循环里轮询filter.activated标志位一旦为 True 就启动截图流程然后复位标志。真实项目里不建议在事件过滤器里直接做截图因为截图涉及窗口创建和延时放主流程里更可控。2.3 窗口隐藏与延迟截屏的配合后台截图最容易翻车的点就在这里。热键触发后截图窗口要隐藏紧接着抓屏。但“隐藏”和“抓屏”之间有窗口系统延迟如果隐藏后立刻 grabWindow经常抓到残留的半透明窗口轮廓。我的习惯做法是分三步走。def start_capture(): # 第一步先记录所有需要隐藏的窗口句柄 windows [w for w in QGuiApplication.topLevelWindows() if w.isVisible()] for w in windows: w.hide() # 第二步强制处理事件循环让隐藏真正生效 app.processEvents() # 第三步短暂延时后抓屏 QTimer.singleShot(100, do_grab)为什么用 QTimer.singleShot 而不是 time.sleep因为阻塞睡眠会让 Qt 窗口系统无法完成隐藏后的重绘反而更容易导致残留。singleShot 回到事件循环再抓窗口系统有时间刷新桌面合成状态。延时设多少合适我实测结果是 80120ms 基本稳定太短残留太长用户会觉得响应慢。shadewidget.rar 里对这段的处理比较讲究它把“隐藏-延时-抓屏-恢复窗口”封装成一个状态机而不是线性执行这样即使抓屏失败也能恢复窗口不至于让程序整个消失。从底层逻辑上看这个模块解决的是这个状态机里所有“时序”问题。3. 仿 QQ 截图交互全屏遮罩、选区与八方向拖拽3.1 全屏遮罩窗口的实现要点窗口隐藏与抓屏走通后下一步就是显示一层“遮罩层”让用户像 QQ 截图那样拖拽选区。这个遮罩窗口自身不能出现在任务栏、不能抢焦点到桌面、必须覆盖所有屏幕。创建遮罩窗口的关键在 Qt.WindowType 的组合from PySide6.QtWidgets import QWidget from PySide6.QtCore import Qt, QRect, QPoint class MaskWindow(QWidget): def __init__(self, rect: QRect): super().__init__(None) # WindowStaysOnTopHint 保证置顶FramelessWindowHint 去掉边框 # BypassWindowManagerHint 避免窗口管理器干预 self.setWindowFlags( Qt.WindowType.FramelessWindowHint | Qt.WindowType.WindowStaysOnTopHint | Qt.WindowType.BypassWindowManagerHint ) self.setGeometry(rect) self.setMouseTracking(True) # 必须开启否则鼠标移动不触发 mouseMoveEvent注意setMouseTracking(True)。Qt 默认只有按住按钮移动才触发 mouseMoveEvent不开启的话鼠标在遮罩层上悬停移动时无法更新十字坐标显示。还有一个细节遮罩窗口的覆盖区域要传虚拟桌面的总几何区域。单屏时就是全屏矩形多屏时要遍历所有 screen 的 geometry() 并取合集。我见过不少实现只写setGeometry(QGuiApplication.primaryScreen().geometry())在扩展屏上另一半屏幕是黑的无法选区。遮罩窗口上面不直接画选区而是维护一个“选区矩形”状态。鼠标按下时记录起点拖动时更新终点然后触发 paintEvent 重绘。整个交互是一个简单的状态机IDLE、DRAG、ADJUST、DONE。3.2 选区矩形计算与八方向拖拽实现仿 QQ 截图除了新拖拽选区还有“调整选区边缘”的能力也就是选区四周出现八个控制点。实现上不需要八个独立的子控件一个矩形加鼠标位置判断就够了。class RectSelector: def __init__(self): self.start QPoint() self.end QPoint() self.current QPoint() self.state IDLE # IDLE / DRAG / ADJUST_LEFT / ADJUST_RIGHT / ADJUST_TOP / ADJUST_BOTTOM def normalized_rect(self): x1 min(self.start.x(), self.end.x()) y1 min(self.start.y(), self.end.y()) x2 max(self.start.x(), self.end.x()) y2 max(self.start.y(), self.end.y()) return QRect(x1, y1, x2 - x1, y2 - y1) def hit_test(self, pos: QPoint, rect: QRect): # 返回命中的控制点类型例如 LEFT / RIGHT / TOP / BOTTOM threshold 6 if abs(pos.x() - rect.left()) threshold: return ADJUST_LEFT if abs(pos.x() - rect.right()) threshold: return ADJUST_RIGHT if abs(pos.y() - rect.top()) threshold: return ADJUST_TOP if abs(pos.y() - rect.bottom()) threshold: return ADJUST_BOTTOM return DRAG这段代码的价值在于用状态字符串代替复杂的布尔判断调整边缘时只需要根据状态修改 start.x/start.y/end.x/end.y 中的对应项。例如状态是 ADJUST_LEFT就在 mouseMoveEvent 里更新 start 的 x 坐标同时让 y 值不变保证左右两条边平行。实际使用中还要加一个限制最小选区尺寸不能小于 10×10 像素否则后面的标注工具按钮会挤成一团。我在模拟项目X 里遇到过用户疯狂缩小选区到 2×2 像素标注箭头根本画不进去后来加了最小尺寸限制才解决。3.3 十字坐标条与鼠标信息绘制仿 QQ 截图在鼠标旁边显示选区尺寸宽×高这是个容易被忽略但用户感知很强的功能。绘制不在子控件里做直接在遮罩窗口的 paintEvent 里因为需要跟随鼠标实时刷新。def paintEvent(self, event): painter QPainter(self) # 先画半透明遮罩默认常规做法是用 0 到 120 之间的透明度 # 透明度太低看不清选区边界太高又盖住屏幕内容 painter.fillRect(self.rect(), QColor(0, 0, 0, 100)) if self.selector.state ! IDLE: rect self.selector.normalized_rect() # 把选区内的高亮区域画出来 painter.setCompositionMode(QPainter.CompositionMode_Clear) painter.fillRect(rect, Qt.TransparentMode) painter.setCompositionMode(QPainter.CompositionMode_SourceOver) # 画选区边框QQ 风格是有一定宽度的实线 painter.setPen(QPen(QColor(0, 174, 255), 1)) painter.drawRect(rect) # 画尺寸标签位置在矩形右下角外侧防止被选区本身遮住 label f{rect.width()} x {rect.height()} painter.setPen(QColor(255, 255, 255)) painter.drawText(rect.right() 8, rect.bottom() 16, label)这段代码有一个容易被误会的地方清除选区内部的阴影不是用 QPainter::eraseRect而是把 CompositionMode 改成 Clear。Common 模式下Qt 会自动做像素混合导致选区内并不是“完全还原屏幕”而是一种被减淡的残影。第一次实现时不知道这个细节截出来的选区总有淡淡的一层灰色后面换成 Clear 模式才正常。尺寸标签的位置也要处理边界情况。如果选区已经接近屏幕右侧标签画在 rect.right() 8 处就会超出屏幕裁掉。稳妥做法是先判断标签文本宽度超出右边界时改画在 rect.left() - 8 - labelWidth 处。shadewidget.rar 里对标签翻转逻辑的处理比较完整直接复用可以少踩这个坑。4. 标注工具栏与图像合成让截图画上重点4.1 工具栏布局与模式切换状态机选区确定后QQ 截图会在选区下方弹出一个横向工具栏包含矩形、椭圆、箭头、画笔、文字、马赛克等工具。实现上不需要复杂的布局系统一个 QWidget 工具栏 QHBoxLayout 一组 QPushButton 就够用。工具栏的核心不在 UI而在“当前标注模式”的状态管理。我习惯用枚举值加一个读取函数来封装from enum import Enum class MarkMode(Enum): NONE 0 RECT 1 ELLIPSE 2 ARROW 3 BRUSH 4 TEXT 5 current_mode MarkMode.NONE def set_mode(self, mode: MarkMode): global current_mode current_mode mode # 切换模式时更新鼠标光标形状 if mode in (MarkMode.RECT, MarkMode.ELLIPSE): self.setCursor(Qt.CrossCursor) elif mode MarkMode.ARROW: self.setCursor(Qt.PointingHandCursor) else: self.setCursor(Qt.ArrowCursor) def get_mode(self): return current_mode为什么要把模式设计成全局状态因为鼠标事件 paintEvent 都要根据当前模式决定行为。如果模式通过信号槽或事件参数传递代码会被拆得到处都是排障时非常头痛。全局枚举配合 cursor 变化是最省事的方案。工具栏的位置在选区矩形下方但如果选区底部贴近屏幕边缘工具栏就要翻到选区上方。这个翻转逻辑往往被人忽略实际体验差很大。判断条件是rect.bottom() toolbar.height() screen_height为 True 时把工具栏 y 坐标改到rect.top() - toolbar.height() - 4。这个逻辑别写死在工具栏类里放在遮罩窗口的 adjustToolbarPosition 方法中更合理。4.2 QPainter 绘制标注矩形、椭圆与箭头的算法工具栏就绪后标注行为的核心是鼠标按下、拖动、松开三个事件里分别做“记录起点”“更新预览”“固化标注”。预览与最终绘制共用同一个绘图方法只是预览时画在一个临时 QPixmap 上松开鼠标后才画到底图上。以箭头为例需要计算起点到终点的连线以及箭头头部三角形import math def draw_arrow(painter, p1, p2, arrow_len12, arrow_angle30): painter.drawLine(p1, p2) # 计算主方向角度 angle math.atan2(p2.y() - p1.y(), p2.x() - p1.x()) # 三角形左右两个顶点相对与 p2 的偏转角 left_angle angle math.radians(arrow_angle) right_angle angle - math.radians(arrow_angle) left QPoint( p2.x() - int(arrow_len * math.cos(left_angle)), p2.y() - int(arrow_len * math.sin(left_angle)) ) right QPoint( p2.x() - int(arrow_len * math.cos(right_angle)), p2.y() - int(arrow_len * math.sin(right_angle)) ) painter.drawPolygon([p2, left, right])三角函数计算时注意三点。一是 math.atan2 返回弧度math.sin/cos 接受的也是弧度不要混用角度制二是箭头长度和角度直接定义成常量即可不需要做成配置项除非用户有特殊偏好三是 p1 到 p2 距离太短时比如只有几个像素画出来的箭头会变成一个奇怪的三角形因此要在 mouseReleaseEvent 里判断距离小于 5 就不画箭头。矩形和椭圆参数相对简单核心是保证鼠标正向拖拽和反向拖拽都能得到正确的矩形。用 normalized_rect 把 start 和 end 的坐标取 min/max 就能处理反向拖拽。画笔工具稍微复杂一些它要求记录一连串点而不是两点一线。我建议用一个QListQPoint保存轨迹mouseMoveEvent 里追加坐标并重绘paintEvent 里用 drawPolyline 把轨迹连起来。轨迹点太密集会导致性能问题——我实测过鼠标快速划过时一秒钟会产生上百个点drawPolyline 全部绘制没有太大压力但如果你用 drawLine 逐段画会明显卡顿。4.3 标注层与底图的合成逻辑最后一步是把标注内容合成到底图上保存。不要在遮罩窗口的 QPainter 上直接保存因为遮罩窗口还有半透明阴影层。我的做法是维护两个 QPixmapself.base_pixmap QPixmap(rect.size()) # 截屏原图 self.mark_pixmap QPixmap(rect.size()) # 标注层默认全透明 def paint_on_mark(self, painter_func): p QPainter(self.mark_pixmap) painter_func(p) p.end() self.update() def compose_and_save(self, path): result QPixmap(self.base_pixmap.size()) p QPainter(result) p.drawPixmap(0, 0, self.base_pixmap) p.drawPixmap(0, 0, self.mark_pixmap) p.end() result.save(path)为什么标注不直接画在 base_pixmap 上因为我们需要“撤销”功能。撤销最简单的实现是保存一份 initial_mark_pixmap 作为快照每执行一步标注操作就覆盖一次撤销就是把 mark_pixmap 恢复到上一个快照。如果标注直接合进 base_pixmap撤销就得重新裁剪原始截屏代价高且容易出错。合成保存时有一个细节保存格式选择 PNG 可以无损但文件较大如果工具使用场景是发到聊天窗口改成 JPG 质量 85 是一个比较平衡的选择。shadewidget.rar 里还做了偏移裁剪因为截屏时如果选择了非零起点多屏场景选区的坐标要减去虚拟桌面的左上角偏移否则保存出来的图会是黑底加一小块内容。这一块逻辑比较绕建议源码下来后重点读screenshot_area相关的那段。5. 截图模块落地避坑高 DPI、多屏与第二次黑屏排查5.1 高 DPI 下截屏尺寸偏移现象程序在 150% 缩放的 Windows 屏幕上运行截出来的图比实际屏幕小或者选区右下角偏移鼠标坐标和图像坐标对不上。原因Qt 默认启用高 DPI 缩放QScreen 的 geometry() 返回的是逻辑像素而 grabWindow 需要的是设备像素两者之间的换算系数是 devicePixelRatio。解决截屏前手动设置环境变量禁用 Qt 的缩放或者对所有坐标统一乘上 devicePixelRatio。我建议尽量别禁用全局缩放因为程序里其他 UI 会全乱正确做法是在 grabWindow 时用比值换算并在遮罩窗口内用self.devicePixelRatioF()动态获取当前窗口对应的缩放因子。5.2 扩展屏与主屏 DPI 不一致现象主屏缩放 100%、副屏缩放 150% 时副屏选区的矩形在保存后与预期位置错位。原因Qt 对不同屏幕的 DPI 是逐屏管理的虚拟桌面的坐标系统里各屏尺寸不同。解决不要拿统一的 devicePixelRatio 去换算所有屏幕。遍历每个屏幕时先screen.devicePixelRatio()取得该屏自己的比率再用对应的比率转换该屏的截屏参数。如果用的是 PySide6 的screen.grabWindow(0, ...)不需要手动计算grabWindow内部会按该屏的 DPR 返回正确尺寸但当你手动把多屏拼到一张图里时拼接逻辑就要按每个屏的 DPR 分别处理。5.3 第二次截屏发黑或发白现象第一次截屏一切正常第二次、第三次截出的图全黑或全白。原因第一次创建的遮罩窗口没有销毁而是只hide()了第二次创建新遮罩窗口时旧的抓屏状态残留或者 QPixmap 被系统合成器缓存。解决截屏流程结束后显式 deleteLater 遮罩窗口并调用QGuiApplication.processEvents()清理不要把hide()当成最后的拆分手段。这一步属于最容易被忽略的内存管理陷阱。5.4 全局热键无法注册现象运行程序后热键按了没反应其他软件快捷键正常。原因要么热键 ID 冲突要么当前系统已经有其他程序占用了同样的组合键。解决程序启动时调RegisterHotKey后检查返回值失败时打印日志并自动换一组组合键。如果你不想让用户去改配置更好的做法是把第一组键设为 CtrlAltA第二组设为 CtrlAltS第三组设为 CtrlAltD逐个尝试注册直到其中一个成功。shadewidget.rar 里有对应的回退逻辑可以直接参考这层实现。5.5 标注模式切换后鼠标形状滞后现象从“画笔”切回“矩形”后鼠标已经变成十字但画出来还是之前的画笔轨迹。原因事件响应里没有判断当前模式就直接执行了绘制或者模式切换的 setCursor 发生在按钮点击回调里但 paintEvent 内的绘制分支用的是旧状态值。解决所有标注绘制分支统一在入口处mode self.get_mode()获取一次当前模式随后用 if-elif 执行对应逻辑避免逻辑间共享临时变量。这个坑带来的排查耗时往往比前四个加起来都多因为它不报错只是行为错乱。6. 验证与进阶用调试叠加层验收截图精度截图模块做完后你可能觉得自己已经搞定了但实际换个屏幕、换个分辨率就露馅。我的习惯是给截图模块加一个调试叠加层专门用于验证坐标转换是否正确。做法是在遮罩窗口上绘制一个网格并把网格线交叉点的物理坐标标出来。截图保存后放大对比如果网格交叉点位置和桌面上的真实图标边缘对齐说明坐标换算没被 DPI 干扰如果偏差超过 1 个像素那就要检查 devicePixelRatio 换算是否有问题。def paint_debug_grid(self, painter): if not self.debug_mode: return grid_size 32 rect self.rect() x rect.left() while x rect.right(): painter.drawLine(x, rect.top(), x, rect.bottom()) x grid_size y rect.top() while y rect.bottom(): painter.drawLine(rect.left(), y, rect.right(), y) y grid_size调试模式建议用环境变量或配置文件开关不要用界面按钮防止误触发给用户。验证流程除了网格对齐还要做一次“完整热键链路测试”启动程序、最小化到托盘按热键截取当前活动窗口然后立刻截图保存。连续执行 30 次检查有没有因窗口切换导致黑屏或错位。自动化可以实现为每 500ms 自动触发一次热键运行一小时统计失败率。我某次做某跨平台系统的截图模块时就是靠这组测试发现虚拟桌面坐标在 Windows 11 的某些版本上有 2 像素偏差——不是 DPI 问题而是系统更新后窗口边框阴影导致的坐标偏移。从那以后我每次接手新的截图模块都会先跑一遍调试叠加层和 30 次热键循环确认两个指标坐标偏差为 0、失败率为 0然后才交给使用者。希望帮到你。本文还有配套的精品资源点击获取
简介面向具备一定 Qt 基础、希望实现仿 QQ 截图工具的开发者这套代码演示了如何用 C 构建一个可后台运行、支持全局快捷键唤醒的屏幕捕捉程序解决主窗口最小化后无法快速截图的常见问题。资源共 27 个文件以 C 源文件与头文件为主辅以工程文件、项目配置、界面定义及说明文档配套的全局热键库完整覆盖 Windows、macOS、X11 三种平台整个压缩包仅 52KB结构相当紧凑。核心实现包括阴影小部件的绘制逻辑与主窗口交互入口从半透明预览区的绘制、屏幕抓取到快捷键的后台响应与截图保存流程完整即使窗口最小化程序也能持续监听按键这对理解全局热键与事件循环配合、无边框窗口阴影渲染以及屏幕捕获技术都很有帮助。目前已有 312 人学习代码量小但模块划分清晰适合按需移植到自己的 Qt 项目中。1. 截图工具看着简单后台截图才是门槛很多人以为 Qt 截图功能就是一个全屏窗口加鼠标拖拽做完才发现真正的难点是“后台截图”。我拆过好几个仿 QQ 截图的 Qt 项目最典型的翻车点在于——按下全局热键时截图程序的窗口必须先隐藏然后再抓取屏幕否则你截下来的图里永远带着自己软件的窗口。shadewidget.rar 这个资源包解决的就是这条完整链路全局热键触发、无痕后台运行、仿 QQ 截图交互、标注合成与保存。适合正在用 Qt/C 或 PySide 做工具类软件、需要给产品内置截图能力的开发者也适合想搞清楚“为什么我的截图黑屏/偏移/截到自己”的入门者。它不是一个只画框框的 Demo而是一个能直接接进业务的截图模块。2. 后台截图与全局热键先让软件“不动声色”2.1 截图方案选型QScreen 抓屏与窗口 grab 的差别后台截图的第一件事是选对抓屏 API。Qt 里有两个常用入口QWidget::grab()和QScreen::grabWindow()。前者是把某个控件树渲染成 QPixmap适合截取软件自己的界面后者是从屏幕上抓取原生像素适合全局截图。我用 PySide6 做演示底层逻辑和 C/Qt 的 QScreen::grabWindow 一致from PySide6.QtGui import QGuiApplication, QScreen from PySide6.QtCore import QRect def grab_full_screen(): app QGuiApplication.instance() screens app.screens() # 拿到所有屏幕的虚拟桌面几何区域 virtual_rect QRect() for screen in screens: virtual_rect virtual_rect.united(screen.geometry()) # 参数传虚拟桌面矩形注意用的是设备像素还是逻辑像素 pixmap screens[0].grabWindow(0, virtual_rect.x(), virtual_rect.y(), virtual_rect.width(), virtual_rect.height()) return pixmap这里有两个常见误区。误区一grabWindow(0)不传参数时只抓主屏幕。扩展屏内容不在结果里需要自己遍历 QGuiApplication.screens()把每块屏幕的几何区域 union 起来再作为矩形传给第一个屏幕去抓。误区二传矩形的宽高是逻辑像素但在高 DPI 屏幕上抓出来的 QPixmap 尺寸经常比逻辑尺寸大这是系统缩放策略造成的。后面会在避坑章节单独展开。选 QScreen 而不是直接用一个隐藏的全屏 QWidget 去渲染并截图原因是QWidget 方式依赖窗口系统合成器在远程桌面或禁用桌面合成时会得到黑屏而 QScreen 抓的是底层帧缓冲稳定性好得多。我在某跨平台系统里从 QWidget 方案切到 QScreen 方案后黑屏反馈基本清零。2.2 全局热键QShortcut 的局限与事件过滤器方案后台截图的“后台”二字意味着快捷键在软件没有焦点时也要生效。Qt 的 QShortcut 只能处理程序内部的按键一旦窗口最小化、失焦或隐藏它就失灵了。正确的做法是调用操作系统级别的热键注册接口然后通过 Qt 的事件过滤器接收回调。在 Windows 上做法是 RegisterHotKey 注册全局热键随后在 QAbstractNativeEventFilter 里拦截 WM_HOTKEY 消息。PySide6 里可以这样写一个过滤器类from PySide6.QtCore import QAbstractNativeEventFilter import ctypes MOD_NOREPEAT 0x4000 WM_HOTKEY 0x0312 class GlobalHotkeyFilter(QAbstractNativeEventFilter): def __init__(self, hotkey_id): super().__init__() self.hotkey_id hotkey_id self.activated False def nativeEventFilter(self, event_type, message): if event_type bwindows_generic_MSG: msg ctypes.wintypes.MSG.from_address(message.__int__()) if msg.message WM_HOTKEY and msg.wParam self.hotkey_id: self.activated True return False # 不拦截让 Qt 继续处理 return False注册的代码放在程序启动处user32 ctypes.windll.user32 hotkey_id 0x0001 # 0x31 是数字键 1 的虚拟键码MOD_NOREPEAT 防止按住时重复触发 user32.RegisterHotKey(None, hotkey_id, MOD_NOREPEAT, 0x31) filter GlobalHotkeyFilter(hotkey_id) app.installNativeEventFilter(filter)注意两个参数。虚拟键码 0x31 对应主键盘数字 1组合键没加 MOD_CONTROL 或 MOD_SHIFT所以只按数字 1 就能触发这适合快速唤起截图如果你担心误触可以改成 CtrlShiftA 的组合把修饰键参数换成 MOD_CONTROL | MOD_SHIFT0x0002 | 0x0004虚拟键码换成 0x41。注册成功后程序主循环里轮询filter.activated标志位一旦为 True 就启动截图流程然后复位标志。真实项目里不建议在事件过滤器里直接做截图因为截图涉及窗口创建和延时放主流程里更可控。2.3 窗口隐藏与延迟截屏的配合后台截图最容易翻车的点就在这里。热键触发后截图窗口要隐藏紧接着抓屏。但“隐藏”和“抓屏”之间有窗口系统延迟如果隐藏后立刻 grabWindow经常抓到残留的半透明窗口轮廓。我的习惯做法是分三步走。def start_capture(): # 第一步先记录所有需要隐藏的窗口句柄 windows [w for w in QGuiApplication.topLevelWindows() if w.isVisible()] for w in windows: w.hide() # 第二步强制处理事件循环让隐藏真正生效 app.processEvents() # 第三步短暂延时后抓屏 QTimer.singleShot(100, do_grab)为什么用 QTimer.singleShot 而不是 time.sleep因为阻塞睡眠会让 Qt 窗口系统无法完成隐藏后的重绘反而更容易导致残留。singleShot 回到事件循环再抓窗口系统有时间刷新桌面合成状态。延时设多少合适我实测结果是 80120ms 基本稳定太短残留太长用户会觉得响应慢。shadewidget.rar 里对这段的处理比较讲究它把“隐藏-延时-抓屏-恢复窗口”封装成一个状态机而不是线性执行这样即使抓屏失败也能恢复窗口不至于让程序整个消失。从底层逻辑上看这个模块解决的是这个状态机里所有“时序”问题。3. 仿 QQ 截图交互全屏遮罩、选区与八方向拖拽3.1 全屏遮罩窗口的实现要点窗口隐藏与抓屏走通后下一步就是显示一层“遮罩层”让用户像 QQ 截图那样拖拽选区。这个遮罩窗口自身不能出现在任务栏、不能抢焦点到桌面、必须覆盖所有屏幕。创建遮罩窗口的关键在 Qt.WindowType 的组合from PySide6.QtWidgets import QWidget from PySide6.QtCore import Qt, QRect, QPoint class MaskWindow(QWidget): def __init__(self, rect: QRect): super().__init__(None) # WindowStaysOnTopHint 保证置顶FramelessWindowHint 去掉边框 # BypassWindowManagerHint 避免窗口管理器干预 self.setWindowFlags( Qt.WindowType.FramelessWindowHint | Qt.WindowType.WindowStaysOnTopHint | Qt.WindowType.BypassWindowManagerHint ) self.setGeometry(rect) self.setMouseTracking(True) # 必须开启否则鼠标移动不触发 mouseMoveEvent注意setMouseTracking(True)。Qt 默认只有按住按钮移动才触发 mouseMoveEvent不开启的话鼠标在遮罩层上悬停移动时无法更新十字坐标显示。还有一个细节遮罩窗口的覆盖区域要传虚拟桌面的总几何区域。单屏时就是全屏矩形多屏时要遍历所有 screen 的 geometry() 并取合集。我见过不少实现只写setGeometry(QGuiApplication.primaryScreen().geometry())在扩展屏上另一半屏幕是黑的无法选区。遮罩窗口上面不直接画选区而是维护一个“选区矩形”状态。鼠标按下时记录起点拖动时更新终点然后触发 paintEvent 重绘。整个交互是一个简单的状态机IDLE、DRAG、ADJUST、DONE。3.2 选区矩形计算与八方向拖拽实现仿 QQ 截图除了新拖拽选区还有“调整选区边缘”的能力也就是选区四周出现八个控制点。实现上不需要八个独立的子控件一个矩形加鼠标位置判断就够了。class RectSelector: def __init__(self): self.start QPoint() self.end QPoint() self.current QPoint() self.state IDLE # IDLE / DRAG / ADJUST_LEFT / ADJUST_RIGHT / ADJUST_TOP / ADJUST_BOTTOM def normalized_rect(self): x1 min(self.start.x(), self.end.x()) y1 min(self.start.y(), self.end.y()) x2 max(self.start.x(), self.end.x()) y2 max(self.start.y(), self.end.y()) return QRect(x1, y1, x2 - x1, y2 - y1) def hit_test(self, pos: QPoint, rect: QRect): # 返回命中的控制点类型例如 LEFT / RIGHT / TOP / BOTTOM threshold 6 if abs(pos.x() - rect.left()) threshold: return ADJUST_LEFT if abs(pos.x() - rect.right()) threshold: return ADJUST_RIGHT if abs(pos.y() - rect.top()) threshold: return ADJUST_TOP if abs(pos.y() - rect.bottom()) threshold: return ADJUST_BOTTOM return DRAG这段代码的价值在于用状态字符串代替复杂的布尔判断调整边缘时只需要根据状态修改 start.x/start.y/end.x/end.y 中的对应项。例如状态是 ADJUST_LEFT就在 mouseMoveEvent 里更新 start 的 x 坐标同时让 y 值不变保证左右两条边平行。实际使用中还要加一个限制最小选区尺寸不能小于 10×10 像素否则后面的标注工具按钮会挤成一团。我在模拟项目X 里遇到过用户疯狂缩小选区到 2×2 像素标注箭头根本画不进去后来加了最小尺寸限制才解决。3.3 十字坐标条与鼠标信息绘制仿 QQ 截图在鼠标旁边显示选区尺寸宽×高这是个容易被忽略但用户感知很强的功能。绘制不在子控件里做直接在遮罩窗口的 paintEvent 里因为需要跟随鼠标实时刷新。def paintEvent(self, event): painter QPainter(self) # 先画半透明遮罩默认常规做法是用 0 到 120 之间的透明度 # 透明度太低看不清选区边界太高又盖住屏幕内容 painter.fillRect(self.rect(), QColor(0, 0, 0, 100)) if self.selector.state ! IDLE: rect self.selector.normalized_rect() # 把选区内的高亮区域画出来 painter.setCompositionMode(QPainter.CompositionMode_Clear) painter.fillRect(rect, Qt.TransparentMode) painter.setCompositionMode(QPainter.CompositionMode_SourceOver) # 画选区边框QQ 风格是有一定宽度的实线 painter.setPen(QPen(QColor(0, 174, 255), 1)) painter.drawRect(rect) # 画尺寸标签位置在矩形右下角外侧防止被选区本身遮住 label f{rect.width()} x {rect.height()} painter.setPen(QColor(255, 255, 255)) painter.drawText(rect.right() 8, rect.bottom() 16, label)这段代码有一个容易被误会的地方清除选区内部的阴影不是用 QPainter::eraseRect而是把 CompositionMode 改成 Clear。Common 模式下Qt 会自动做像素混合导致选区内并不是“完全还原屏幕”而是一种被减淡的残影。第一次实现时不知道这个细节截出来的选区总有淡淡的一层灰色后面换成 Clear 模式才正常。尺寸标签的位置也要处理边界情况。如果选区已经接近屏幕右侧标签画在 rect.right() 8 处就会超出屏幕裁掉。稳妥做法是先判断标签文本宽度超出右边界时改画在 rect.left() - 8 - labelWidth 处。shadewidget.rar 里对标签翻转逻辑的处理比较完整直接复用可以少踩这个坑。4. 标注工具栏与图像合成让截图画上重点4.1 工具栏布局与模式切换状态机选区确定后QQ 截图会在选区下方弹出一个横向工具栏包含矩形、椭圆、箭头、画笔、文字、马赛克等工具。实现上不需要复杂的布局系统一个 QWidget 工具栏 QHBoxLayout 一组 QPushButton 就够用。工具栏的核心不在 UI而在“当前标注模式”的状态管理。我习惯用枚举值加一个读取函数来封装from enum import Enum class MarkMode(Enum): NONE 0 RECT 1 ELLIPSE 2 ARROW 3 BRUSH 4 TEXT 5 current_mode MarkMode.NONE def set_mode(self, mode: MarkMode): global current_mode current_mode mode # 切换模式时更新鼠标光标形状 if mode in (MarkMode.RECT, MarkMode.ELLIPSE): self.setCursor(Qt.CrossCursor) elif mode MarkMode.ARROW: self.setCursor(Qt.PointingHandCursor) else: self.setCursor(Qt.ArrowCursor) def get_mode(self): return current_mode为什么要把模式设计成全局状态因为鼠标事件 paintEvent 都要根据当前模式决定行为。如果模式通过信号槽或事件参数传递代码会被拆得到处都是排障时非常头痛。全局枚举配合 cursor 变化是最省事的方案。工具栏的位置在选区矩形下方但如果选区底部贴近屏幕边缘工具栏就要翻到选区上方。这个翻转逻辑往往被人忽略实际体验差很大。判断条件是rect.bottom() toolbar.height() screen_height为 True 时把工具栏 y 坐标改到rect.top() - toolbar.height() - 4。这个逻辑别写死在工具栏类里放在遮罩窗口的 adjustToolbarPosition 方法中更合理。4.2 QPainter 绘制标注矩形、椭圆与箭头的算法工具栏就绪后标注行为的核心是鼠标按下、拖动、松开三个事件里分别做“记录起点”“更新预览”“固化标注”。预览与最终绘制共用同一个绘图方法只是预览时画在一个临时 QPixmap 上松开鼠标后才画到底图上。以箭头为例需要计算起点到终点的连线以及箭头头部三角形import math def draw_arrow(painter, p1, p2, arrow_len12, arrow_angle30): painter.drawLine(p1, p2) # 计算主方向角度 angle math.atan2(p2.y() - p1.y(), p2.x() - p1.x()) # 三角形左右两个顶点相对与 p2 的偏转角 left_angle angle math.radians(arrow_angle) right_angle angle - math.radians(arrow_angle) left QPoint( p2.x() - int(arrow_len * math.cos(left_angle)), p2.y() - int(arrow_len * math.sin(left_angle)) ) right QPoint( p2.x() - int(arrow_len * math.cos(right_angle)), p2.y() - int(arrow_len * math.sin(right_angle)) ) painter.drawPolygon([p2, left, right])三角函数计算时注意三点。一是 math.atan2 返回弧度math.sin/cos 接受的也是弧度不要混用角度制二是箭头长度和角度直接定义成常量即可不需要做成配置项除非用户有特殊偏好三是 p1 到 p2 距离太短时比如只有几个像素画出来的箭头会变成一个奇怪的三角形因此要在 mouseReleaseEvent 里判断距离小于 5 就不画箭头。矩形和椭圆参数相对简单核心是保证鼠标正向拖拽和反向拖拽都能得到正确的矩形。用 normalized_rect 把 start 和 end 的坐标取 min/max 就能处理反向拖拽。画笔工具稍微复杂一些它要求记录一连串点而不是两点一线。我建议用一个QListQPoint保存轨迹mouseMoveEvent 里追加坐标并重绘paintEvent 里用 drawPolyline 把轨迹连起来。轨迹点太密集会导致性能问题——我实测过鼠标快速划过时一秒钟会产生上百个点drawPolyline 全部绘制没有太大压力但如果你用 drawLine 逐段画会明显卡顿。4.3 标注层与底图的合成逻辑最后一步是把标注内容合成到底图上保存。不要在遮罩窗口的 QPainter 上直接保存因为遮罩窗口还有半透明阴影层。我的做法是维护两个 QPixmapself.base_pixmap QPixmap(rect.size()) # 截屏原图 self.mark_pixmap QPixmap(rect.size()) # 标注层默认全透明 def paint_on_mark(self, painter_func): p QPainter(self.mark_pixmap) painter_func(p) p.end() self.update() def compose_and_save(self, path): result QPixmap(self.base_pixmap.size()) p QPainter(result) p.drawPixmap(0, 0, self.base_pixmap) p.drawPixmap(0, 0, self.mark_pixmap) p.end() result.save(path)为什么标注不直接画在 base_pixmap 上因为我们需要“撤销”功能。撤销最简单的实现是保存一份 initial_mark_pixmap 作为快照每执行一步标注操作就覆盖一次撤销就是把 mark_pixmap 恢复到上一个快照。如果标注直接合进 base_pixmap撤销就得重新裁剪原始截屏代价高且容易出错。合成保存时有一个细节保存格式选择 PNG 可以无损但文件较大如果工具使用场景是发到聊天窗口改成 JPG 质量 85 是一个比较平衡的选择。shadewidget.rar 里还做了偏移裁剪因为截屏时如果选择了非零起点多屏场景选区的坐标要减去虚拟桌面的左上角偏移否则保存出来的图会是黑底加一小块内容。这一块逻辑比较绕建议源码下来后重点读screenshot_area相关的那段。5. 截图模块落地避坑高 DPI、多屏与第二次黑屏排查5.1 高 DPI 下截屏尺寸偏移现象程序在 150% 缩放的 Windows 屏幕上运行截出来的图比实际屏幕小或者选区右下角偏移鼠标坐标和图像坐标对不上。原因Qt 默认启用高 DPI 缩放QScreen 的 geometry() 返回的是逻辑像素而 grabWindow 需要的是设备像素两者之间的换算系数是 devicePixelRatio。解决截屏前手动设置环境变量禁用 Qt 的缩放或者对所有坐标统一乘上 devicePixelRatio。我建议尽量别禁用全局缩放因为程序里其他 UI 会全乱正确做法是在 grabWindow 时用比值换算并在遮罩窗口内用self.devicePixelRatioF()动态获取当前窗口对应的缩放因子。5.2 扩展屏与主屏 DPI 不一致现象主屏缩放 100%、副屏缩放 150% 时副屏选区的矩形在保存后与预期位置错位。原因Qt 对不同屏幕的 DPI 是逐屏管理的虚拟桌面的坐标系统里各屏尺寸不同。解决不要拿统一的 devicePixelRatio 去换算所有屏幕。遍历每个屏幕时先screen.devicePixelRatio()取得该屏自己的比率再用对应的比率转换该屏的截屏参数。如果用的是 PySide6 的screen.grabWindow(0, ...)不需要手动计算grabWindow内部会按该屏的 DPR 返回正确尺寸但当你手动把多屏拼到一张图里时拼接逻辑就要按每个屏的 DPR 分别处理。5.3 第二次截屏发黑或发白现象第一次截屏一切正常第二次、第三次截出的图全黑或全白。原因第一次创建的遮罩窗口没有销毁而是只hide()了第二次创建新遮罩窗口时旧的抓屏状态残留或者 QPixmap 被系统合成器缓存。解决截屏流程结束后显式 deleteLater 遮罩窗口并调用QGuiApplication.processEvents()清理不要把hide()当成最后的拆分手段。这一步属于最容易被忽略的内存管理陷阱。5.4 全局热键无法注册现象运行程序后热键按了没反应其他软件快捷键正常。原因要么热键 ID 冲突要么当前系统已经有其他程序占用了同样的组合键。解决程序启动时调RegisterHotKey后检查返回值失败时打印日志并自动换一组组合键。如果你不想让用户去改配置更好的做法是把第一组键设为 CtrlAltA第二组设为 CtrlAltS第三组设为 CtrlAltD逐个尝试注册直到其中一个成功。shadewidget.rar 里有对应的回退逻辑可以直接参考这层实现。5.5 标注模式切换后鼠标形状滞后现象从“画笔”切回“矩形”后鼠标已经变成十字但画出来还是之前的画笔轨迹。原因事件响应里没有判断当前模式就直接执行了绘制或者模式切换的 setCursor 发生在按钮点击回调里但 paintEvent 内的绘制分支用的是旧状态值。解决所有标注绘制分支统一在入口处mode self.get_mode()获取一次当前模式随后用 if-elif 执行对应逻辑避免逻辑间共享临时变量。这个坑带来的排查耗时往往比前四个加起来都多因为它不报错只是行为错乱。6. 验证与进阶用调试叠加层验收截图精度截图模块做完后你可能觉得自己已经搞定了但实际换个屏幕、换个分辨率就露馅。我的习惯是给截图模块加一个调试叠加层专门用于验证坐标转换是否正确。做法是在遮罩窗口上绘制一个网格并把网格线交叉点的物理坐标标出来。截图保存后放大对比如果网格交叉点位置和桌面上的真实图标边缘对齐说明坐标换算没被 DPI 干扰如果偏差超过 1 个像素那就要检查 devicePixelRatio 换算是否有问题。def paint_debug_grid(self, painter): if not self.debug_mode: return grid_size 32 rect self.rect() x rect.left() while x rect.right(): painter.drawLine(x, rect.top(), x, rect.bottom()) x grid_size y rect.top() while y rect.bottom(): painter.drawLine(rect.left(), y, rect.right(), y) y grid_size调试模式建议用环境变量或配置文件开关不要用界面按钮防止误触发给用户。验证流程除了网格对齐还要做一次“完整热键链路测试”启动程序、最小化到托盘按热键截取当前活动窗口然后立刻截图保存。连续执行 30 次检查有没有因窗口切换导致黑屏或错位。自动化可以实现为每 500ms 自动触发一次热键运行一小时统计失败率。我某次做某跨平台系统的截图模块时就是靠这组测试发现虚拟桌面坐标在 Windows 11 的某些版本上有 2 像素偏差——不是 DPI 问题而是系统更新后窗口边框阴影导致的坐标偏移。从那以后我每次接手新的截图模块都会先跑一遍调试叠加层和 30 次热键循环确认两个指标坐标偏差为 0、失败率为 0然后才交给使用者。希望帮到你。本文还有配套的精品资源点击获取
