2026 世界杯比分挂件

一个 Windows 桌面悬浮挂件，用于展示 2026 FIFA 世界杯实时比分与近期赛程。挂件使用纯 Qt 透明无边框窗口实现，支持原生置顶、鼠标事件穿透，并带有系统托盘入口。

✨ 特性

• 实时数据：从 ESPN 公开接口获取真实赛程和实时比分（无需 API Key）。
• 动态 UI：展示直播比分卡、近期赛程列表，以及有进球时的动态横幅浮层通知。
• 下一场提示：在非比赛时间，清晰展示“下一场”对阵球队与时间，提供多行居中优雅排版。
• 系统级置顶：结合了 Qt 的 WindowStaysOnTopHint 与 Win32 API 的 HWND_TOPMOST，保证绝大多数情况下的最前端置顶效果。
• 鼠标穿透与锁定：锁定位置后，挂件主体自动对鼠标事件“隐身”（鼠标穿透到底层应用），提供独立的绿色悬浮安全锁图标用于解除锁定。
• 静默后台：后台线程定时刷新数据，Qt 信号推送到原生窗口；无赛程时自动降低刷新频率以节省系统资源。

⚙️ 环境要求

• 操作系统：仅限 Windows 系统 (底层依赖 user32.dll)
• Python：3.11 或更高版本

📦 安装与运行

# 1. 安装依赖
pip install -r requirements.txt

# 2. 运行挂件
python main.py

首次运行会自动使用默认窗口配置。运行后生成的 config.json 属于本机配置，自动保存当前窗口位置及状态，该文件已被加入 .gitignore。

💡 窗口控制说明

窗口右上角悬浮显示了控制按钮：

按钮	说明
📌 顶	开启或关闭始终置顶状态（高亮表示生效中）
🔒 锁	锁定位置并开启鼠标穿透；再次点击独立的绿色悬浮锁，或者使用系统托盘右键菜单解除
❌ 关	退出当前程序

关于锁定功能的补充： 一旦点击“锁定”，主挂件的鼠标事件将会穿透（将 WA_TransparentForMouseEvents 结合 WS_EX_TRANSPARENT 应用到全局）。此时主体窗口不再阻挡您鼠标点击背后的网页或代码，只有旁边独立的悬浮按钮可以被点击，用以恢复正常状态。

🔨 打包部署

项目包含现成的 PyInstaller 配置文件，可以直接打包为单文件免安装的可执行程序（EXE）：

python -m PyInstaller worldcup_widget.spec

打包产物会生成在 dist/worldcup-widget.exe，直接双击运行即可，不依赖本地 Python 环境。

📂 核心架构

文件	职责说明
main.py	程序主入口，负责 PySide6 界面构建、UI 组件绘制、托盘维护及多线程渲染调度
data_engine.py	ESPN 赛事数据拉取、JSON 数据清洗重构、状态监控及进球检测引擎
window_manager.py	Win32 底层系统能力封装（置顶状态强刷新与原生窗口全局穿透配置）
worldcup_widget.spec	PyInstaller 资源与环境依赖打包配置
icon.ico	应用程序与系统托盘所使用的应用图标

⚠️ 注意事项

由于该项目在 window_manager.py 中直接调用了 Windows API 函数来实现鼠标穿透等特殊无边框窗口行为，因此无法在 macOS 或 Linux 上运行。