# windows_tools

**Repository Path**: lunars/windows_tools

## Basic Information

- **Project Name**: windows_tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BeijingTimeWidget —— 北京时间桌面悬浮工具

一个运行于 Windows 的桌面悬浮时钟：**无论你正在使用什么应用，都可以始终看到北京时间。**

无边框、始终置顶、鼠标穿透、NTP 校准、多显示器、高 DPI、系统状态监控。

---

## 项目介绍

BeijingTimeWidget 是一个 Windows 桌面悬浮工具。启动后在桌面显示一个无边框、可移动、可配置的北京时间悬浮窗口，可悬浮于 Chrome、Edge、Word、Excel、VS Code、微信、Teams 等普通应用之上。

时间标准：`Asia/Shanghai`（内部统一使用 `zoneinfo`，不依赖本机时区设置）。

## 功能介绍

| 功能 | 说明 |
|------|------|
| 北京时间显示 | 时/分/秒、日期、星期、"北京时间"标签，5 种显示模式 + 自定义格式 |
| 始终置顶 | 普通 / 始终置顶 / 超级置顶（尽可能保持最前）三档 |
| 悬浮窗口 | 无边框、无标题栏、无任务栏按钮、不抢焦点 |
| 自由拖动 | 左键拖动，坐标自动持久化 |
| 鼠标穿透 | 窗口不拦截鼠标，可经托盘/快捷键恢复 |
| 外观 | 字体 / 字号 / 粗细 / 颜色、背景（无/半透明黑/白/自定义）、透明度、圆角、文字阴影 |
| 多显示器 | 主显示器 / 指定显示器 / 所有显示器；热插拔自动重布局 |
| 高 DPI | 100% ~ 200% 缩放自适应 |
| 系统托盘 | 显示/隐藏、显示模式、置顶模式、显示器切换等完整菜单 |
| NTP 校准 | 后台线程、多服务器容错、失败自动降级本机时间 |
| 系统状态监控 | 独立悬浮面板显示 CPU / 内存 / GPU 利用率（迷你阈值进度条）；可选明细：内存已用/总量(GB)、CPU 频率；刷新间隔可调 |
| 快捷键 | 全局 `Ctrl+Alt+B` 显示/隐藏、`Ctrl+Alt+T` 切换置顶 |
| 开机启动 | HKCU 注册表，无需管理员权限 |
| 单实例 | 重复启动自动激活已有窗口 |
| 配置持久化 | JSON 配置，损坏自动备份并恢复默认 |
| 日志 | 滚动日志，位于 `%APPDATA%\BeijingTimeWidget\logs\` |

## 运行环境

- **操作系统**：Windows 10 / Windows 11（64 位）
- **权限**：无需管理员权限
- **网络**：可选（仅 NTP 校时使用；无网络时程序完全正常工作，显示本机时间）

## Python 版本

- **Python ≥ 3.12**（开发验证环境：Python 3.14.7）

## 开发环境搭建

```bash
# 1. 创建虚拟环境
python -m venv .venv

# 2. 安装依赖（开发含 pytest 与 pyinstaller）
.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
```

## 依赖安装

运行依赖（`requirements.txt`）：

```text
PyQt6>=6.7        # GUI
pywin32>=306      # Windows API
ntplib>=0.4.0     # NTP
psutil>=7.0       # 系统状态采集（CPU / 内存）
tzdata>=2024.1    # Windows 平台 zoneinfo 时区数据（必需）
```

开发依赖（`requirements-dev.txt`）额外包含：`pytest>=8.0`、`pyinstaller>=6.16`。

## 如何运行

```bash
.venv\Scripts\python.exe main.py
```

启动后右上角出现时钟悬浮窗，托盘出现图标。双击时钟打开设置；右键时钟/托盘打开菜单。

## 如何测试

```bash
.venv\Scripts\python.exe -m pytest tests -q
```

测试覆盖：TimeService（北京时间/UTC/格式/星期/NTP偏移）、SettingsService（默认/保存/加载/损坏恢复）、NtpService（成功/超时/失败切换，全部 mock 零网络）、快捷键解析、SystemMonitorService（psutil/PDH 采集组装与降级、面板阈值配色）。全部无头运行。

## 如何打包（生成 EXE）

```bash
# 方式一：脚本
powershell -ExecutionPolicy Bypass -File scripts\build.ps1

# 方式二：手动
.venv\Scripts\python.exe -m PyInstaller --noconfirm --clean --onefile --windowed ^
    --name BeijingTimeWidget --icon resources\icons\app.ico ^
    --add-data "resources;resources" --collect-all tzdata main.py
```

产物：`dist\BeijingTimeWidget.exe`（单文件、无控制台窗口）。

## 如何生成安装程序

先安装 Inno Setup 6：

```bash
winget install JRSoftware.InnoSetup
```

然后：

```bash
powershell -ExecutionPolicy Bypass -File scripts\package.ps1
```

产物：`release\BeijingTimeWidget-Setup.exe`。

安装包特性：按用户安装（无 UAC）、桌面/开始菜单快捷方式、可选开机启动、卸载时询问是否删除用户配置。

## 配置文件说明

配置文件：`%APPDATA%\BeijingTimeWidget\settings.json`（首次启动自动生成）。

| 段 | 字段 | 说明 |
|----|------|------|
| display | mode | `full`/`date_time`/`time`/`minimal`/`custom` |
| display | show_seconds / show_milliseconds / show_label | 秒 / 毫秒 / "北京时间"标签 |
| display | custom_format | 自定义格式串（Qt 格式，如 `yyyy-MM-dd HH:mm:ss`） |
| appearance | font_family / font_size / font_weight / font_color | 字体外观 |
| appearance | background_style | `none`/`black`/`white`/`custom` |
| appearance | background_color / opacity / corner_radius / text_shadow | 背景色 / 透明度(0.1–1.0) / 圆角(0–30) / 阴影 |
| window | topmost_mode | `normal`/`always_on_top`/`super_topmost` |
| window | mouse_through | 鼠标穿透 |
| window | monitor | `primary` / `all` / 具体显示器名 |
| window | position | 9 宫格预设或 `custom`（拖动保存 custom_x/custom_y） |
| window | offset_x / offset_y | 预设位置偏移（px） |
| time | timezone / ntp_enabled / ntp_servers / sync_interval_minutes | 时区与 NTP |
| startup | auto_start | 开机启动 |
| hotkeys | toggle_visible / toggle_topmost | 全局快捷键 |
| system | enabled | 系统状态面板开关（默认关，启用后每 2 秒采样） |
| system | show_cpu / show_memory / show_gpu | 显示项（CPU / 内存 / GPU 利用率） |
| system | show_details | 明细：内存已用/总量(GB) · CPU 频率 |
| system | refresh_seconds | 刷新间隔（1–60 秒） |
| system | panel_position | 面板位置（9 宫格或 `custom`，拖动保存 panel_custom_x/y） |
| system | panel_offset_x / panel_offset_y | 面板预设位置偏移（px） |

配置文件损坏时：自动备份为 `settings.json.bak` → 恢复默认配置 → 程序继续运行。

## 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+Alt+B` | 显示 / 隐藏时钟 |
| `Ctrl+Alt+T` | 切换置顶（普通 → 始终置顶 → 超级置顶 循环） |

可在设置窗口「快捷键」页修改。与系统或其他程序冲突时注册会失败并提示。

## 常见问题

**Q: 时钟不显示？**
A: 可能被隐藏。按 `Ctrl+Alt+B` 或单击托盘图标恢复；检查显示器设置是否指向已拔出的屏幕（会自动回退主屏）。

**Q: 鼠标穿透开启后无法操作时钟？**
A: 穿透模式下窗口不接收鼠标。请通过托盘菜单取消勾选"鼠标穿透"，或使用快捷键。

**Q: 时间不准？**
A: 托盘右键 → "重新校准时间"。NTP 服务器列表可在设置中修改。无网络或 UDP 123 被限制时使用本机时间。

**Q: "超级置顶"能覆盖所有窗口吗？**
A: 不能。超级置顶仅尽可能保持在普通应用之上，无法覆盖 UAC 安全桌面、Ctrl+Alt+Del、登录界面、独占全屏程序或部分游戏。

**Q: 配置出错想重置？**
A: 设置 → 高级 → 恢复默认设置；或删除 `%APPDATA%\BeijingTimeWidget\settings.json` 后重启。

**Q: 如何卸载？**
A: Windows 设置 → 应用 → 卸载，或开始菜单中的卸载项。卸载时会询问是否删除用户配置。

## 开发说明

- 目录结构按需求文档 §6 组织：`app/`（协调）、`models/`（数据模型）、`windows/`（窗口）、`services/`（服务）、`windows_api/`（Win32 封装）、`utils/`（工具）、`resources/`（图标/QSS）、`tests/`、`scripts/`、`installer/`、`config/`。
- 所有 Win32 API 集中封装于 `windows_api/`（窗口/鼠标/显示器/快捷键），不散落在 UI 代码中。
- UI 线程不做网络/阻塞操作：NTP 运行于后台 QThread；刷新定时器每秒一次（毫秒模式 50ms）。
- 异常策略：任何单模块失败（NTP/配置/快捷键/显示器）不导致程序退出，仅记录日志并降级。
- 图标为开发期脚本生成：`pip install pillow && python scripts/make_icons.py`。
- 开发按 13 个 Phase 增量实施，每个 Phase 独立可运行并有 git 提交记录。

## 数据安全

程序不上传任何用户数据、不收集个人信息；网络请求仅用于 NTP 校时。

---

**版本**：1.1.0 ｜ **时间标准**：Asia/Shanghai ｜ © 2026