winshot 1.0.1

Windows screenshot library using WinAPI - supports BitBlt, StretchBlt, PrintWindow methods

winshot

Windows 截图库 - 基于 WinAPI 实现的高性能截图工具

安装

pip install git+https://github.com/E5C8F/winshot.git

快速开始

from winshot import 全屏截图, 保存图片, 设置DPI感知

# 设置 DPI 感知（建议在程序启动时调用）
设置DPI感知()

# 全屏截图
图像数据 = 全屏截图()

# 保存为 BMP 文件
保存图片(图像数据, "screenshot.bmp")

功能特性

• ✅ 支持全屏截图
• ✅ 支持窗口截图（前台/后台）
• ✅ 支持 BitBlt、StretchBlt、PrintWindow 三种截图方式
• ✅ 支持截图缩放
• ✅ 返回原始 BGRA 数据，方便后续处理
• ✅ 纯 Python 实现，无需编译
• ✅ 提供中英文两套 API

API 文档

设置DPI感知 / set_process_dpi_awareness

设置进程 DPI 感知级别，建议在程序启动时调用。

参数：

• PROCESS_DPI_AWARENESS: 0=不感知, 1=系统 DPI 感知, 2=按监视器 DPI 感知（默认）

返回： 0 表示成功，负数表示失败

from winshot import 设置DPI感知
设置DPI感知()  # 使用默认值 2

全屏截图 / full_screenshot

获取全屏幕截图。

返回： BGRA 格式的图像数据（包含 width、height 属性的对象）

from winshot import 全屏截图
图像 = 全屏截图()
print(f"图像尺寸: {图像.width}x{图像.height}")

前台窗口截图 / foreground_window_screenshot

获取指定窗口的前台截图。

参数：

• hwnd: 窗口句柄，默认为桌面窗口

返回： BGRA 格式的图像数据

from winshot import 前台窗口截图
图像 = 前台窗口截图(hwnd)

BitBlt截图 / bitblt_screenshot

通过 BitBlt 方式进行后台截图。

参数：

• x1, y1: 源矩形左上角坐标（相对于窗口）
• cx, cy: 截图区域宽高
• hwnd: 窗口句柄，默认为桌面窗口

返回： BGRA 格式的图像数据

from winshot import BitBlt截图
图像 = BitBlt截图(0, 0, 800, 600, hwnd)

StretchBlt截图 / stretchblt_screenshot

通过 StretchBlt 方式进行后台截图并缩放。

参数：

• wDest, hDest: 目标宽高
• xSrc, ySrc: 源矩形左上角坐标
• wSrc, hSrc: 源矩形宽高
• hwnd: 窗口句柄

返回： BGRA 格式的图像数据

from winshot import StretchBlt截图
图像 = StretchBlt截图(400, 300, 0, 0, 800, 600, hwnd)

PrintWindow截图 / printwindow_screenshot

通过 PrintWindow 方式进行后台截图。

参数：

• w, h: 窗口宽高
• hwnd: 窗口句柄

返回： BGRA 格式的图像数据

from winshot import PrintWindow截图
图像 = PrintWindow截图(800, 600, hwnd)

获取窗口位置 / get_window_position

获取窗口的位置坐标。

参数：

• hwnd: 窗口句柄

返回： (left, top, right, bottom) 元组

from winshot import 获取窗口位置
left, top, right, bottom = 获取窗口位置(hwnd)

保存图片 / save_image

保存位图数据为 BMP 文件。

参数：

• 位图数据: BGRA 格式的图像数据
• 保存路径: 文件保存路径
• 宽度, 高度: 可选，通过本库获取的数据会自动获取

from winshot import 全屏截图, 保存图片
图像 = 全屏截图()
保存图片(图像, "output.bmp")

多语言 API

本库提供中英文两套 API，可按需选择。

中文命名空间

from winshot import zh

zh.设置DPI感知()
图像 = zh.全屏截图()
zh.保存图片(图像, "截图.bmp")

英文命名空间

from winshot import en

en.set_process_dpi_awareness()
image = en.full_screenshot()
en.save_image(image, "screenshot.bmp")

API 对照表

中文函数名	英文别名	命名空间别名
设置DPI感知	set_process_dpi_awareness	zh.设置DPI感知 / en.set_process_dpi_awareness
全屏截图	full_screenshot	zh.全屏截图 / en.full_screenshot
前台窗口截图	foreground_window_screenshot	zh.前台窗口截图 / en.foreground_window_screenshot
BitBlt截图	bitblt_screenshot	zh.BitBlt截图 / en.bitblt_screenshot
StretchBlt截图	stretchblt_screenshot	zh.StretchBlt截图 / en.stretchblt_screenshot
PrintWindow截图	printwindow_screenshot	zh.PrintWindow截图 / en.printwindow_screenshot
获取窗口位置	get_window_position	zh.获取窗口位置 / en.get_window_position
保存图片	save_image	zh.保存图片 / en.save_image

注意事项

1. DPI 感知：建议在程序启动时调用 设置DPI感知()，否则在高 DPI 显示器上可能出现截图尺寸不正确的问题。

2. 后台截图：使用 BitBlt截图 或 PrintWindow截图 进行后台截图时，可能出现全黑或全白的情况，建议根据实际场景选择合适的方法。

3. 图像格式：返回的数据为 BGRA 格式（4 字节/像素），可直接用于图像处理或保存为 BMP 文件。

4. 平台限制：本库仅支持 Windows 系统。

许可证

GNU General Public License v3.0

项目链接

• 主页：https://e5c8f.github.io/winshot
• GitHub：https://github.com/E5C8F/winshot
• 问题反馈：https://github.com/E5C8F/winshot/issues