Skip to content
BigThxBrigdePublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Win11 风格计时器应用

基于 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

本项目遵循严格的 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.txt

运行

python run.py

测试

# 全部测试(61 tests)
python -m unittest discover -s tests -v

# 仅 ViewModel 单元测试(无 UI 依赖)
python -m unittest tests.test_viewmodels -v

打包为 exe

# 前置:安装 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。


📜 License

本项目基于 MIT 许可证开源,详情请参阅 LICENSE 文件。

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages