基于 PyQt6 的轻量级桌面计时器，支持正计时/倒计时/时钟模式，系统托盘、快捷键、音效与闪烁提醒、多语言（中/英）以及丰富的外观自定义；
下载最新版本 • 查看源码 • 报告 Bug • 提出新特性
本 README 同时面向“用户”和“开发者”，上来就想用的看“快速开始”，想参与开发的看“开发者指南”。
- 支持系统：Windows 10/11（x64）
- 推荐环境：Python 3.13（仅源码运行需用到），普通用户可直接使用安装包或便携版
- 安装程序（建议）
- 前往 Releases 下载 DesktopTimer-Setup.exe
- 双击安装，按向导完成；从开始菜单或桌面快捷方式启动
- 便携版
- 下载 DesktopTimer.zip → 解压 → 直接运行 DesktopTimer.exe
- 从源码运行（开发者）
- 克隆仓库并安装依赖后运行
main.py（见下文“开发者指南”）
- ⏰ 三种计时：正计时、倒计时、时钟（12/24 小时制、可选“秒/日期”）
- 🔔 提醒方式：自定义音效（可调音量）、系统 Beep、窗口闪烁、托盘气泡、Windows 通知（可开关）
- 🌐 双语言：中文 / English 一键切换
- 🎯 预设管理：设置页支持自定义/排序/搜索/多选删除倒计时预设，排序方式可记忆，可为中/英文界面分别命名并同步托盘快捷菜单
- 🎨 外观：字体/字号、颜色、圆角、透明度、夜读模式、窗口尺寸、主题（浅/深/跟随系统）
- 🧰 系统托盘：暂停/继续、重置、模式切换、倒计时预设（含自定义单次输入）、显示/隐藏、锁定/解锁、打开设置、退出
- 🔒 窗口锁定：固定位置并可启用“点击穿透”
- ⌨️ 快捷键：常用操作一键直达
- 🖥️ 全屏模式：F11 一键切换，简拍/展示更方便
- 设置倒计时：在设置页输入小时/分钟/秒，或托盘菜单选择预设/自定义单次倒计时
- 开始/暂停/继续：托盘菜单或快捷键 Ctrl+Space；也可在设置中启用“启动自动开始”
- 重置计时：托盘菜单或快捷键 Ctrl+R
- 窗口锁定：托盘菜单或 Ctrl+L（锁定后支持点击穿透）
- 切换模式：设置页或托盘“模式切换”菜单
- 显示/隐藏：托盘菜单或 Ctrl+H
- 配置保存：所有设置自动保存至
settings/timer_settings.json
| 快捷键 | 功能 |
|---|---|
| Ctrl+Space | 暂停/继续 |
| Ctrl+R | 重置 |
| Ctrl+H | 显示/隐藏窗口 |
| Ctrl+L | 锁定/解锁窗口 |
| Ctrl+, | 打开设置 |
| F11 | 全屏/退出全屏 |
- Python 3.13
- Windows 10/11
- 依赖管理：UV
注：如需 Qt Designer 等工具，可另行安装
pyqt6-tools（与项目运行依赖无关）。
# 克隆与进入目录
git clone https://github.com/RE-TikaRa/DesktopTimer.git
cd DesktopTimer
# 安装依赖
uv sync
# 运行
uv run python main.py
# 如需调试日志，可在运行前设置环境变量
# PowerShell
$env:DESKTOPTIMER_DEBUG=1
# CMD
set DESKTOPTIMER_DEBUG=1# 打包需要安装开发依赖
uv sync --dev
uv run python -m PyInstaller DesktopTimer.spec --noconfirm打包完成后生成 dist/DesktopTimer.exe。请将 img/、lang/、sounds/ 一并放入 dist/ 目录。
也可直接使用内置脚本一键完成清理、打包、复制资源与压缩：
tools\pyinstaller.batDesktopTimer/
├── main.py # 程序入口
├── /module/ # 拆分逻辑（app/窗口/配置等）
│ ├── __init__.py
│ ├── app.py
│ ├── constants.py
│ ├── localization.py
│ ├── paths.py
│ ├── settings_dialog.py
│ └── timer_window.py
├── DesktopTimer.spec # PyInstaller 配置
├── pyproject.toml # UV 项目配置
├── uv.lock # UV 锁文件
├── requirements.txt # Python 依赖（历史/兼容）
├── README.md # 项目说明
├── tools/ # 构建/打包脚本
├── /img/ # 图标资源
│ ├── timer_icon.ico
│ └── ALP_STUDIO-logo-full.svg
├── /lang/ # 语言包
│ ├── zh_CN.json
│ └── en_US.json
├── /sounds/ # 提醒音
├── /settings/ # 用户运行时配置
│ └── timer_settings.json
├── /build/ # 临时构建文件
└── /dist/ # 打包输出
- i18n：多语言加载（lang/*.json）
- SettingsDialog：设置对话框（外观/模式/预设/通用/关于）
- TimerWindow：主窗口/计时/托盘/提醒/快捷键（含模式切换菜单、倒计时预设与自定义单次输入）
- 路径管理：自动识别开发/打包环境，动态定位资源
- 配置管理：JSON 持久化，包含版本兼容处理
要点：使用 sys.frozen 识别打包环境；相对路径存储确保可移植；QTimer/QMediaPlayer/QSystemTrayIcon 组合
- 使用
DesktopTimer.spec进行 onefile 打包，输出dist/DesktopTimer.exe - 将
img/、lang/、sounds/复制到dist/下，确保资源可用 - 可使用 Inno Setup 生成安装程序（参考
setup/setup.iss）
-
打包后没有声音/语言不生效？
- 请确认已将
img/、lang/、sounds/整个目录复制到dist/。
- 请确认已将
-
托盘图标不显示/找不到？
- 检查系统托盘的“隐藏的图标”区域；确保 Explorer 正常；程序最小化到托盘时可通过 Ctrl+H 显示/隐藏。
-
锁定后无法操作窗口怎么办？
- 使用快捷键 Ctrl+L 解锁，或通过系统托盘菜单解锁。
-
源码运行报依赖错误？
- 重新执行
uv sync，确保网络正常。 - 若提示 Python 版本不匹配，请确认项目使用 Python 3.13。
- 重新执行
-
打包后资源路径异常？
- 本项目已兼容
sys.frozen场景；若自定义了运行目录，请保持资源与可执行文件同级。
- 本项目已兼容
-
DesktopTimer.egg-info/是什么？- 这是 setuptools 构建产生的元数据目录，可在发布包或清理时忽略/删除。
-
切换语言后界面没变化？
- 语言下拉框一旦切换就会立即应用到主窗口与托盘；若仍看到旧语言，可确认设置文件是否可写或查看日志输出。
- 正计时/倒计时/时钟三种模式
- 系统托盘常驻与快捷操作
- 多种提醒方式（音效/闪烁/通知）
- 中英文双语支持
- 外观完全自定义
- 快捷键支持
- 番茄钟快捷预设
- 窗口锁定功能（位置固定 + 点击穿透）
- 快捷键自定义
- 托盘模式切换与即席自定义倒计时
- 预设支持中英文双描述，可在创建时同步填写
- 结束提醒增强：音量、循环次数、渐入渐出；播放列表/多音频轮播
- Windows 原生通知按钮（如“再来 5 分钟”“停止”）
- 托盘与主题：暗/亮主题托盘图标，自定义图标包
- 设置管理：设置导出/导入备份，一键恢复默认
- 自动更新：检查 Releases 新版本并提示下载
- 开机自启动（用户可选）
- 多语言扩展：支持更多语言（日文、韩文等）
- 可视化窗口滑块：为字体/窗口大小提供滑块+“恢复默认”按钮，并显示实时数值
- 全屏专用主题：进入全屏时可使用独立的背景/文字/透明度样式
- 自定义快捷预设：允许用户在设置中增删 Pomodoro 预设并同步到托盘/右键菜单
- 配置导入/导出：一键备份或应用
settings/*.json，方便在不同设备间迁移 - 预设导入/导出能力（JSON 备份/恢复）
- 预设列表排序、搜索或分组功能
- 语言切换提示（关闭设置前提醒“需点击应用/确定”）
- 设置中添加调试日志开关（无需依赖环境变量）
- 更易用的预设多语言编辑视图（统一列表，可批量维护）
- 替换 win10toast 或移除其中的
pkg_resources依赖以适配未来环境
- 继续拆分
TimerWindow/SettingsDialog中的预设、通知、托盘菜单等重复逻辑，降低单文件复杂度
- PyQt6 - GUI 框架
- PyQt6-Fluent-Widgets - Fluent 风格组件库（设置页 UI）
- PyInstaller - 打包工具
- win10toast - Windows 通知（可选）
- Inno Setup - 安装程序制作
- ✅ 修复时钟模式下“暂停/继续”语义不一致的问题，时钟模式中的暂停项改为禁用
- 🔔 修复设置页对
sounds/相对路径铃声的显示与测试逻辑，避免已选文件显示为“未选择” - 📍 应用设置、语言预览和取消预览时尽量保留窗口位置，不再无条件重新居中
- 🧭 设置页模式切换判断改为基于模式索引/键值，减少对中英文文本匹配的依赖
- 📦
setup/setup.iss改为使用相对路径，去除本机绝对路径硬编码 - 🛠️ 修复
tools/Run.bat与tools/pyinstaller.bat的工作目录问题，避免从tools目录运行时找错入口文件
- 🧩 设置页全面改为 PyQt6-Fluent-Widgets 组件，并统一 Fluent 视觉风格
- 🎨 新增主题模式（浅/深/跟随系统），菜单样式同步主题
- 📚 预设管理支持搜索/多选/批量删除/排序模式记忆，并保留手动排序体验
- 🧰 托盘与右键菜单结构优化：模式切换、运行状态提示与“窗口”子菜单
- 🔊 提醒增强：音量控制与 Windows 通知开关
- 🗝️ 计时/动作设置键值改为语言无关形式，避免切换语言导致配置混乱
- ⚡ 主题/语言/预设调整后即时预览与同步更新托盘菜单
- ⚙️ 预设编辑器支持多语言独立名称，可添加/移除任意语言描述，并给出显式提示避免误填
- 🪵 日志体系切换至
logging，设置DESKTOPTIMER_DEBUG=1即可启用 DEBUG 日志 - 🌐 设置页语言切换支持即时预览但不会自动保存，FAQ 中新增说明
- 🔊 随机铃声、声音播放、托盘通知等异常统一纳入日志输出，取代零散的
print
- ⚡️ 窗口大小控件更加可视，滑块+“恢复默认”快速调整字号
- 🖥️ F11 一键全屏，锁定/拖动逻辑和透明度自适应
- 📐 托盘/右键“快捷预设”按模式分组，可快捷切换正计时/倒计时/时钟
- 🔧 README/安装脚本版本信息统一至 1.0.3
- ⌨️ 新增自定义快捷键功能，支持个性化按键映射
- ⏰ 优化时钟模式显示和交互体验
- ✨ 重新设计关于页面，添加专业的 UI 布局和 ALP STUDIO 标识
- 🔧 优化版本常量管理，统一版本信息展示
- 📝 完善项目文档和用户界面体验
- ✨ 新增时钟模式，支持 12/24 小时制、显示秒数、显示日期
- ✨ 新增窗口锁定功能，支持点击穿透和多种解锁方式
- 优化路径处理机制，改为相对路径存储
- 添加 v1.0.0 配置自动兼容转换
- 编译模式改为单文件 + 外部资源
- 安装程序保护用户自定义音效和设置
- 添加详细的升级指南文档（UPGRADE_GUIDE.md）
- ⏰ 基础倒计时功能
- ⏱️ 正计时模式
- 多种提醒音选择
- 中英文双语支持
- 窗口透明度和置顶功能
- 系统托盘支持
欢迎通过 Issues 或 Pull Requests 参与贡献！
- Fork 本仓库
- 新建分支：
git checkout -b feature/your-feature - 提交改动：
git commit -m "feat: your message" - 推送分支：
git push origin feature/your-feature - 发起 Pull Request
项目使用 Git 管理版本；发布版本在 Releases/Tags 标注。
TikaRa
📧 邮箱：163mail@re-TikaRa.fun
🌐 个人网站：https://re-tikara.fun
🐙 GitHub：https://github.com/RE-TikaRa/DesktopTimer
📺 B 站主页：https://space.bilibili.com/374412219
本项目采用 GNU GPL v3 或更高版本。
允许：自由使用、修改与再发布（包含商用），需保留版权与许可声明，并在发布衍生作品时继续采用 GPL v3 或更高版本。
要求：发布二进制时需同时提供对应源码；不得移除许可证文本。
完整条款参见仓库中的 LICENSE 文件。
- PyQt6 - 提供强大的 GUI 框架
- PyInstaller - Python 打包为可执行文件
- Qt - 跨平台 GUI 框架
- Inno Setup - Windows 安装程序制作工具
- Shields.io - 项目徽章
- GitHub Pages - 文档托管