基于 tkfluent(Fluent Design for Tkinter)实现的 Win11 风格计时器/秒表/设置应用,采用 MVVM 架构,纯 Python 编写,跨平台运行。
- 支持同时运行多个命名计时器。
- 每个计时器带实时进度条和启动/暂停/重置/删除操作。
- 计时完成自动弹窗提醒 + 提示音。
- 支持新建自定义时长(时/分/秒)。
- 大字号实时显示(
Segoe UI 48)。 - **计次(Lap)**功能,自动标记最优/最差计次颜色。
- 重置、启动/暂停/继续。
- 主题切换:深色 / 浅色(一键切换,立即生效)。
- 提示音开关。
- 窗口置顶开关。
- 所有设置自动持久化(JSON)。
| 类别 | 技术 | 说明 |
|---|---|---|
| 语言 | Python ≥ 3.10 | |
| UI 框架 | tkfluent | Fluent Design for Tkinter |
| 架构模式 | MVVM | Model / ViewModel / View 三层分离 |
| 持久化 | JSON 文件 | 自动保存/恢复计时器与设置 |
| 测试 | unittest | 61 个单元测试 + GUI 冒烟测试 |
| 构建 | 无 | 纯解释型 Python,无需编译 |
time_app/
├── run.py # 入口:python run.py
├── requirements.txt # tkfluent>=0.1.6 + pywinstyles
├── README.md
├── LICENSE
│
├── timer_app/ # 源代码(MVVM 分层)
│ ├── __init__.py # 版本号 2.0.0
│ ├── models.py # Model 层:TimerModel / StopwatchModel
│ ├── settings.py # Model 层:JSON 持久化 SettingsStore
│ │
│ ├── viewmodel/ # ViewModel 层
│ │ ├── observable.py # Observable / Property / ObservableList / Command
│ │ ├── timer_view_model.py # TimerItemViewModel + TimerListViewModel
│ │ ├── stopwatch_view_model.py # StopwatchViewModel + LapViewModel
│ │ ├── settings_view_model.py # SettingsViewModel
│ │ └── app_view_model.py # AppViewModel(根 VM + tick 调度 + tab)
│ │
│ └── view/ # View 层(UI 绑定)
│ ├── theme.py # 深浅两套主题配色(普通 tk 控件)
│ ├── app_view.py # FluWindow + 自绘侧栏 + _tick 心跳
│ ├── timer_page.py # 计时器卡片列表 + ttk 进度条
│ ├── stopwatch_page.py # 秒表大字 + 计次列表
│ ├── settings_page.py # 主题/声音/置顶绑定
│ ├── timer_dialog.py # 新建对话框(自绘 _NumberSpinBox)
│ └── finished_dialog.py # 计时完成提醒对话框
│
└── tests/ # 单元测试 + 冒烟测试
├── test_models.py
├── test_settings.py
├── test_observable.py
├── test_viewmodels.py
└── test_app_smoke.py
本项目遵循严格的 MVVM (Model-View-ViewModel) 架构,实现了 UI 与逻辑的彻底解耦。
┌──────────────────┐ bind() ┌──────────────────┐ 依赖注入 ┌──────────────┐
│ View │◄──────────────►│ ViewModel │◄──────────────►│ Model │
│ (tkflu + tk) │ Property 通知 │ Observable 基类 │ │ 纯 Python │
│ 仅做绑定 + 调度 │ 不持有状态 │ 持有所有状态 │ │ 无 UI 依赖 │
└──────────────────┘ └──────────────────┘ └──────────────┘
- Model:纯领域逻辑,无 UI 依赖 —— 可单独测试、可被 ViewModel 复用。
- ViewModel:状态管理 + Command,通过
Observable/Property/Command与 View 解耦。 - View:仅导入
tkflu+ ViewModel,纯绑定;主题切换通过销毁重建窗口实现(VM 状态保留)。
每 50ms AppView._tick()
│
▼
AppViewModel.tick(now)
│ 调用 timers.tick(now)
│ TimerModel 检测到完成 → Property 更新 → 通知 View
│ 返回 [item_vm]
▼
AppView 遍历 finished items
│ 打开 FinishedDialog
│ 播放 beep 提示音
▼
TimerCard 自动刷新为「重新开始」按钮
pip install -r requirements.txtpython run.py# 全部测试(61 tests)
python -m unittest discover -s tests -v
# 仅 ViewModel 单元测试(无 UI 依赖)
python -m unittest tests.test_viewmodels -v# 前置:安装 PyInstaller
pip install pyinstaller
# 方式一:一键脚本(Windows)
build.bat
# 方式二:手动执行
pyinstaller --noconfirm --onefile --windowed --name time_app ^
--collect-all tkflu --collect-all tkdeft --collect-all easydict ^
--hidden-import numpy --exclude-module tkflu.demos ^
run.py
# 产物:dist/time_app.exe为什么需要 --collect-all:tkflu / tkdeft 内部依赖字体文件(segoeui.ttf、segoe_fluent_icons.ttf、segoe_font.ttf)和图标资源,PyInstaller 默认不收集非 .py 文件,必须显式指定 --collect-all tkflu tkdeft。
| 项 | 说明 |
|---|---|
| 主题切换 | 采用销毁重建窗口方案(tkflu 的 theme() 对子控件传播不可靠),VM 状态不受影响 |
| 侧栏导航 | 自绘实现,未用 FluButton(dark/standard 样式在深色侧栏上近乎透明) |
| 数字选择器 | 自绘 _NumberSpinBox(原生 tk.Spinbox 在 Windows 上布局歪斜) |
| FluEntry | 新建对话框用原生 tk.Entry 替代(tkflu 的 FluEntry 内部 Entry 未指定 master,跨 toplevel 崩溃) |
| FluToggleButton | 命令触发时 checked 已翻转,View 端需读取 attributes.checked 而非接收回调参数 |
详见 view/theme.py 和实现文档 .trae/documents/tkfluent-mvvm-rewrite.md。
本项目基于 MIT 许可证开源,详情请参阅 LICENSE 文件。