亓翎_Re-Tikara Lv5
  2026-03-12 21:21:48 2026-03-12 21:21:48 创建   2026-02-07 02:01:49 2026-02-07 02:01:49 更新    2.3k 字  8 分钟  

DesktopTimer | 桌面计时器

Contributors Forks Stars Issues License

Logo

DesktopTimer | 桌面计时器

基于 PyQt6 的轻量级桌面计时器，支持正计时/倒计时/时钟模式，系统托盘、快捷键、音效与闪烁提醒、多语言（中/英）以及丰富的外观自定义；

下载最新版本 • 查看源码 • 报告 Bug • 提出新特性

本 README 同时面向“用户”和“开发者”，上来就想用的看“快速开始”，想参与开发的看“开发者指南”。

🚀 快速开始（用户）

  • 支持系统：Windows 10/11（x64）
  • 推荐环境：Python 3.13（仅源码运行需用到），普通用户可直接使用安装包或便携版
  1. 安装程序（建议）
  • 前往 Releases 下载 DesktopTimer-Setup.exe
  • 双击安装，按向导完成；从开始菜单或桌面快捷方式启动
  1. 便携版
  • 下载 DesktopTimer.zip → 解压 → 直接运行 DesktopTimer.exe
  1. 从源码运行（开发者）
  • 克隆仓库并安装依赖后运行 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（与项目运行依赖无关）。

源码运行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 克隆与进入目录
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

打包为可执行文件

1
2
3
# 打包需要安装开发依赖
uv sync --dev
uv run python -m PyInstaller DesktopTimer.spec --noconfirm

打包完成后生成 dist/DesktopTimer.exe。请将 img/、lang/、sounds/ 一并放入 dist/ 目录。

也可直接使用内置脚本一键完成清理、打包、复制资源与压缩：

1
tools\pyinstaller.bat

文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
DesktopTimer/
├── 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）

❓ 常见问题（FAQ）

  1. 打包后没有声音/语言不生效？

    • 请确认已将 img/、lang/、sounds/ 整个目录复制到 dist/。

  2. 托盘图标不显示/找不到？

    • 检查系统托盘的“隐藏的图标”区域；确保 Explorer 正常；程序最小化到托盘时可通过 Ctrl+H 显示/隐藏。

  3. 锁定后无法操作窗口怎么办？

    • 使用快捷键 Ctrl+L 解锁，或通过系统托盘菜单解锁。

  4. 源码运行报依赖错误？

    • 重新执行 uv sync，确保网络正常。
    • 若提示 Python 版本不匹配，请确认项目使用 Python 3.13。

  5. 打包后资源路径异常？

    • 本项目已兼容 sys.frozen 场景；若自定义了运行目录，请保持资源与可执行文件同级。

  6. DesktopTimer.egg-info/ 是什么？

    • 这是 setuptools 构建产生的元数据目录，可在发布包或清理时忽略/删除。

  7. 切换语言后界面没变化？

    • 语言下拉框一旦切换就会立即应用到主窗口与托盘；若仍看到旧语言，可确认设置文件是否可写或查看日志输出。

🧭 开发路线图

✅ 已完成功能

  • 正计时/倒计时/时钟三种模式
  • 系统托盘常驻与快捷操作
  • 多种提醒方式（音效/闪烁/通知）
  • 中英文双语支持
  • 外观完全自定义
  • 快捷键支持
  • 番茄钟快捷预设
  • 窗口锁定功能（位置固定 + 点击穿透）
  • 快捷键自定义
  • 托盘模式切换与即席自定义倒计时
  • 预设支持中英文双描述，可在创建时同步填写

📌 计划中的功能

  • 结束提醒增强：音量、循环次数、渐入渐出；播放列表/多音频轮播
  • Windows 原生通知按钮（如“再来 5 分钟”“停止”）
  • 托盘与主题：暗/亮主题托盘图标，自定义图标包
  • 设置管理：设置导出/导入备份，一键恢复默认
  • 自动更新：检查 Releases 新版本并提示下载
  • 开机自启动（用户可选）
  • 多语言扩展：支持更多语言（日文、韩文等）
  • 可视化窗口滑块：为字体/窗口大小提供滑块+“恢复默认”按钮，并显示实时数值
  • 全屏专用主题：进入全屏时可使用独立的背景/文字/透明度样式
  • 自定义快捷预设：允许用户在设置中增删 Pomodoro 预设并同步到托盘/右键菜单
  • 配置导入/导出：一键备份或应用 settings/*.json，方便在不同设备间迁移
  • 预设导入/导出能力（JSON 备份/恢复）
  • 预设列表排序、搜索或分组功能
  • 语言切换提示（关闭设置前提醒“需点击应用/确定”）
  • 设置中添加调试日志开关（无需依赖环境变量）
  • 更易用的预设多语言编辑视图（统一列表，可批量维护）
  • 替换 win10toast 或移除其中的 pkg_resources 依赖以适配未来环境

🧩 使用到的技术栈

  • PyQt6 - GUI 框架
  • PyQt6-Fluent-Widgets - Fluent 风格组件库（设置页 UI）
  • PyInstaller - 打包工具
  • win10toast - Windows 通知（可选）
  • Inno Setup - 安装程序制作

🤝 贡献指南

欢迎通过 Issues 或 Pull Requests 参与贡献！

如何参与开源项目

  1. Fork 本仓库
  2. 新建分支：git checkout -b feature/your-feature
  3. 提交改动：git commit -m "feat: your message"
  4. 推送分支：git push origin feature/your-feature
  5. 发起 Pull Request

🔖 版本控制

项目使用 Git 管理版本；发布版本在 Releases/Tags 标注。

👤 作者

TikaRa
📧 邮箱：[email protected]
🌐 个人网站：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 - 文档托管
  • 标题:
  • 作者: 亓翎_Re-Tikara
  • 创建于 : 2026-03-12 21:21:48
  • 更新于 : 2026-02-07 02:01:49
  • 链接: https://re-tikara.fun/Blog/posts/0/
  • 版权声明: 本文章采用 CC BY-NC-SA 4.0 进行许可。
目录
  1. DesktopTimer | 桌面计时器
    1. DesktopTimer | 桌面计时器
    2. 🚀 快速开始（用户）
    3. ✨ 功能一览
    4. 🧭 使用说明（核心操作）
      1. ⌨️ 快捷键
    5. 🛠️ 开发者指南
      1. 开发环境要求
      2. 源码运行
      3. 打包为可执行文件
      4. 文件结构
      5. 架构与实现要点
    6. 📦 打包与发布
    7. ❓ 常见问题（FAQ）
    8. 🧭 开发路线图
      1. ✅ 已完成功能
      2. 📌 计划中的功能
    9. 🧩 使用到的技术栈
    10. 🤝 贡献指南
      1. 如何参与开源项目
    11. 🔖 版本控制
    12. 👤 作者
    13. 📄 版权说明
    14. 🙏 鸣谢