# LightweightToolbox

**Repository Path**: overwhat/lightweight-toolbox

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 工具箱

基于 **CustomTkinter** 构建的桌面工具箱应用，采用模块化架构，支持左侧导航菜单切换、路由驱动页面渲染和开发模式热重载。

---

## 1. 如何运行

### 环境准备

```bash
# 安装依赖
pip install -r requirements.txt
```

依赖清单：

| 依赖 | 版本要求 | 用途 |
|---|---|---|
| `customtkinter` | ≥ 5.2.0 | GUI 框架 |
| `Pillow` | ≥ 10.0.0 | 图像处理 |
| `watchdog` | ≥ 4.0.0 | 文件监控（开发模式热重载） |
| `pyinstaller` | ≥ 6.0.0 | 打包为可执行文件 |

### 生产模式

直接启动应用：

```bash
python main.py
```

### 开发模式（热重载）

监控 `.py` 文件变更，自动重启应用，适合开发调试：

```bash
python dev.py
```

> 按下 `Ctrl+C` 可退出开发模式。

### 打包为可执行文件

#### 安装打包工具

```bash
pip install pyinstaller
```

#### 打包命令

**方式一：运行打包脚本（推荐）**

由于 Windows cmd 对中文参数存在编码问题，推荐使用项目根目录下的打包脚本：

```bash
python build.py
```

或双击运行 `build.bat`。

**方式二：手动执行命令**

```bash
pyinstaller --onefile --windowed --name "工具箱" --add-data "assets;assets" --icon "assets/logo/app_icon.ico" --collect-submodules customtkinter main.py
```

> 若终端出现中文乱码，请改用方式一。

**参数说明：**

| 参数 | 作用 |
|---|---|
| `--onefile` | 打包为单个 exe 文件 |
| `--windowed` | 运行时不显示控制台窗口 |
| `--name "工具箱"` | 生成的 exe 文件名 |
| `--add-data "assets;assets"` | 将 assets 静态资源目录打包进去（Windows 使用 `;` 分隔） |
| `--icon "assets/logo/app_icon.ico"` | 设置 exe 文件的图标 |
| `--collect-submodules customtkinter` | 确保 customtkinter 主题文件被正确收集 |

#### 打包产物

打包完成后，可执行文件位于项目根目录下的 `dist/` 目录：

```
dist/
└── 工具箱.exe        # 双击即可运行，无需 Python 环境
```

> **注意：** 首次启动 exe 时，杀毒软件可能会误报，添加信任即可。

#### 打包后资源路径适配

打包为 exe 后，资源文件的实际路径会变为 PyInstaller 的临时解压目录（`sys._MEIPASS`）。项目入口 `main.py` 中需要加入以下兼容处理：

```python
import sys, os

if getattr(sys, 'frozen', False):
    # 打包后运行：资源在 _MEIPASS 临时目录中
    BASE_DIR = sys._MEIPASS
else:
    # 开发模式运行：资源在项目根目录
    BASE_DIR = os.path.dirname(os.path.abspath(__file__))
```

#### 常见问题

| 问题 | 解决方案 |
|---|---|
| 打包后启动报找不到主题文件 | 添加 `--collect-submodules customtkinter` 参数 |
| 图标 / Logo 不显示 | 确认 `--add-data "assets;assets"` 已包含在命令中 |
| 杀毒软件误报 | 将 exe 添加到杀毒软件信任列表 |

---

## 2. 项目结构

```
py_time_alculator/
├── assets/                  # 静态资源（图标、Logo 等）
│   ├── icon/
│   └── logo/
│       └── logo.png
├── config/                  # 配置层 —— 菜单与路由的声明式定义
│   ├── menus.py             #   菜单配置树：定义左侧导航栏的菜单结构
│   └── routes.py            #   路由注册表：建立路由名 → 页面类的映射
├── logic/                   # 逻辑层 —— 纯业务计算，与 UI 解耦
│   └── date_calculator.py   #   日期计算核心逻辑
├── ui/                      # 表现层 —— 界面构建与交互
│   ├── components/          #   公共 UI 组件
│   │   └── scroll_frame.py  #     自定义滚动容器组件
│   ├── pages/               #   页面模块（按功能模块分组，每个子目录对应一个功能领域）
│   │   ├── home/                  #     首页模块
│   │   │   └── home_page.py       #       首页页面
│   │   ├── time_tools/            #     时间工具模块
│   │   │   └── date_interval/     #       日期间隔计算子模块
│   │   │       └── date_interval_page.py  # 日期间隔计算页面
│   │   └── image_tools/           #     图像工具模块
│   │       └── qrcode/            #       二维码生成子模块
│   │           └── qrcode_page.py #         二维码生成页面
│   ├── app.py               #   应用主窗口（初始化 & 页面容器）
│   └── sidebar.py           #   左侧导航栏（读取菜单配置，触发路由切换）
├── main.py                  # 生产模式入口
├── dev.py                   # 开发模式入口（基于 watchdog 热重载）
└── requirements.txt         # Python 依赖清单
```

### 架构说明

- **config（配置层）**：采用声明式数据结构定义菜单结构和路由映射，新增功能只需在 `menus.py` 添加菜单项、在 `routes.py` 注册路由，无需修改其他文件。
- **logic（逻辑层）**：纯业务逻辑，不依赖任何 UI 框架，便于独立测试和复用。
- **ui（表现层）**：基于 CustomTkinter 构建，`app.py` 负责窗口管理，`sidebar.py` 负责导航渲染，`pages/` 按功能模块分组（如 `home/`、`time_tools/`、`image_tools/`），每个子模块下包含具体的功能页面文件。
- **组件复用**：`ui/components/` 存放跨页面通用的 UI 组件（如滚动容器），各页面按需引用。