本文介绍如何在不修改 Pyglet 源码的前提下，跨平台兼容性良好地程序化还原已最小化的 Pyglet 窗口，重点推荐基于 win32gui 的 Windows 解决方案，并说明其原理、使用方式与关键注意事项。
本文介绍如何在不修改 pyglet 源码的前提下，跨平台兼容性良好地程序化还原已最小化的 pyglet 窗口，重点推荐基于 `win32gui` 的 windows 解决方案，并说明其原理、使用方式与关键注意事项。
在 Pyglet 中，window.minimize() 可以轻松将窗口最小化，但官方 API 并未提供对应的 window.restore() 或 window.unminimize() 方法——这一设计缺口长期存在，且截至 Pyglet 2.0+ 版本（含 2.1），文档与源码中仍无内置恢复接口。因此，若需在运行时主动还原窗口（例如响应热键、定时器或 UI 事件），必须借助底层平台 API 实现。
对于 Windows 系统（Pyglet 默认后端），最稳定、无需侵入式修改库源码的方案是使用 pywin32 提供的 win32gui.ShowWindow() 函数，配合窗口句柄（window._hwnd）和 SW_RESTORE 标志：
import pyglet
import win32gui
import win32con
def restore_window(window: pyglet.window.Window) -> bool:
"""安全还原指定 Pyglet 窗口（仅限 Windows）"""
if not hasattr(window, '_hwnd') or not window._hwnd:
return False
try:
win32gui.ShowWindow(window._hwnd, win32con.SW_RESTORE)
return True
except Exception as e:
print(f"窗口还原失败：{e}")
return False
# 示例用法
window = pyglet.window.Window(800, 600, "Restore Demo")
@window.event
def on_key_press(symbol, modifiers):
if symbol == pyglet.window.key.R and modifiers & pyglet.window.key.MOD_CTRL:
restore_window(window) # Ctrl+R 还原窗口
pyglet.app.run()⚠️ 重要注意事项：
- ✅ 此方法仅适用于 Windows（因依赖 Win32 API）。Linux/macOS 需分别使用 X11（XMapWindow）或 Cocoa（NSWindow.orderFront:）机制，Pyglet 当前未封装跨平台还原逻辑；
- ✅ window._hwnd 是 Pyglet Windows 后端的私有属性，虽稳定可用，但属“约定俗成”的访问方式（非官方公开 API），升级 Pyglet 时建议验证其存在性；
- ❌ 不要直接修改 pyglet/window/win32/__init__.py 添加 restore() 方法——这会导致部署困难、版本冲突及维护成本飙升；
- ✅ 推荐将 restore_window() 封装为独立工具函数，并添加异常捕获与返回值判断，提升鲁棒性；
- ? SW_RESTORE（值为 9）会将窗口恢复到最小化前的大小与位置；若需强制激活并聚焦，可额外调用 win32gui.SetForegroundWindow(window._hwnd)。
综上，win32gui.ShowWindow(hwnd, SW_RESTORE) 是当前 Windows 下最实用、低侵入、高可控的 Pyglet 窗口还原方案。开发者应明确平台约束，在构建跨平台应用时，对非 Windows 环境预留降级逻辑（如忽略操作或提示用户手动恢复）。
