基于 Python + tkinter + pygubu 构建的跨平台 MDI（多文档界面）桌面应用框架，提供完整的桌面应用开发解决方案。
- 折叠侧边栏：支持多级菜单分组，可展开/折叠，只显示图标，拖动调整宽度
- Tab 多页面：支持打开多个功能窗口，带关闭按钮，首页不可关闭，支持滚动
- 工具栏：支持图标+文字显示，可实时切换文字显示和位置（右侧/下方）
- 状态栏：显示消息提示和版本信息，菜单悬停时显示功能说明
- 拖动调整：侧边栏宽度可拖动调整
- 全屏模式：支持全屏切换
- 窗口管理：支持窗口菜单，快速切换和关闭标签页
- 主题配色：通过
config.ini自定义主题颜色，支持实时预览 - 基类继承：提供
BaseWindow基类，快速创建功能窗口 - 热重载：开发模式下 UI 文件修改后自动重新加载，无需重启软件
- 打包发布：支持 PyInstaller 打包为独立 exe 文件
- 配置驱动：通过 JSON 配置文件无代码添加菜单和界面
- UI配置生成：支持 15+ 种组件，通过 JSON 配置生成界面
- 热重载配置：配置文件修改后自动重新加载，立即生效
- 图标管理：支持PNG图片图标，统一配置管理
-
学校信息管理：
- 学校信息的增删改查
- 使用ttk.Treeview表格显示和编辑
- 支持Excel和CSV导入导出
- 支持打印功能（支持对齐方式选择：左对齐/居中/右对齐）
- 支持数据筛选
- 支持排序功能
- 支持多选和统计
-
学生信息管理：
- 学生信息的增删改查
- 使用ttk.Treeview表格显示和编辑
- 性别下拉列表选择（男/女）
- 身高验证（1-249厘米）
- 学校下拉列表选择
- 考试科目复选框（语文、数学、外语、历史、物理）
- 参加考试科目数量自动计算
- 选择复选框（支持多选）
- 统计行显示（总数和已选数量）
- 支持列标题排序（升序/降序）
- 支持多条件筛选
- 支持Excel和CSV导入导出
- 支持打印功能（带预览、打印机选择、纸张类型、页边距设置、对齐方式选择）
- 未保存数据提示（关闭窗口或退出软件时）
-
摄像头操作：
- 自动检测可用摄像头
- 支持多摄像头切换
- 实时预览摄像头画面
- 摄像头参数设置（亮度、对比度、饱和度、清晰度、伽玛）
- 分辨率和帧率设置
-
图像识别：
- 支持摄像头截图识别
- 支持本地图片文件识别（JPG、JPEG、PNG、BMP、TIFF、WEBP）
- OCR文字识别（支持多种识别引擎）
- Tesseract-OCR（本地识别）
- 阿里云OCR（在线高精度识别）
- 二维码/条形码识别
- 识别结果实时显示
-
图像处理：
- 支持多种图像格式
- 实时预览效果
- 图像参数调整
- CLAHE自动提亮
┌─────────────────────────────────────────────────────────────┐
│ MDIApp（主框架） │
│ ┌──────────────┐ ┌─────────────────────────────────────┐ │
│ │ Sidebar │ │ Tab 内容区 │ │
│ │ 折叠菜单 │ │ ┌──┬──┬──┬──┐ ← TabHeader │ │
│ │ (可拖动) │ │ │首页│...│ │ │
│ │ │ │ └──┴──┴──┴──┘ │ │
│ │ 工作台 │ │ ┌─────────────────────────────┐ │ │
│ │ │ │ │ │ │ │
│ │ │ │ │ 当前窗口内容 │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ └─────────────────────────────┘ │ │
│ └──────────────┘ └─────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 工具栏 │ 首页 │ ... │ │
│ └─────────────────────────────────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 状态栏 │ 就绪 │ 版本: 1.0.0 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
mdi_app/
├── main.py # 程序入口
├── config.ini # 配置文件
├── pyproject.toml # 项目配置
├── mdi_app.spec # 打包配置
│
├── config/ # 配置文件目录
│ └── menus.json # 菜单配置文件
│
├── app/ # 核心框架模块
│ ├── __init__.py
│ ├── mdi_app.py # MDIApp 主类
│ ├── config_manager.py # 配置管理器
│ ├── window_config_manager.py # 窗口配置管理器
│ ├── ui_generator.py # UI配置生成器
│ ├── icon_manager.py # 图标管理器
│ ├── sidebar.py # 侧边栏组件
│ ├── tab_manager.py # 标签页组件
│ ├── platform_utils.py # 平台工具函数
│ ├── tooltip.py # 提示框组件
│ ├── pygubu_custom_widgets.py # 自定义控件
│ ├── models.py # 数据库模型定义
│ ├── database.py # 数据库管理类
│ ├── excel_manager.py # Excel导入导出管理
│ ├── print_manager.py # 打印管理
│ ├── filter_dialog.py # 筛选对话框
│ ├── path_utils.py # 路径工具函数
│ ├── ocr_manager.py # OCR识别管理
│ └── aliyun_ocr.py # 阿里云OCR接口
│
├── windows/ # 功能窗口模块
│ ├── __init__.py
│ ├── base_window.py # BaseWindow 基类
│ ├── home_window.py # 首页窗口
│ ├── school_management_window.py # 学校信息管理窗口
│ ├── student_management_window.py # 学生信息管理窗口
│ └── ocr_window.py # OCR识别窗口
│
├── ui/ # UI 文件目录（pygubu 设计器生成）
│ ├── school_management.ui # 学校信息管理UI
│ ├── school_edit.ui # 学校编辑UI
│ ├── student_management.ui # 学生信息管理UI
│ └── student_edit.ui # 学生编辑UI
│
├── icons/ # 图标文件目录
│ ├── toolbar/ # 工具栏图标
│ ├── sidebar/ # 侧边栏图标
│ └── home/ # 首页图标
│
├── README.md # 项目文档
└── 框架使用指南.md # 框架使用指南
# 克隆或下载项目
cd mdi_app
# 安装依赖
uv sync
# 或使用 pip
pip install pygubu Pillow pyinstaller ttkwidgets tksheet
# 如需使用OCR功能，还需安装以下依赖
pip install opencv-python pyzbar pytesseract requests
# 安装Tesseract-OCR引擎（Windows）
# 从 https://github.com/UB-Mannheim/tesseract/wiki 下载安装
# ARM架构支持（如树莓派等）
# 如果在ARM架构上运行，建议安装WeasyPrint以获得更好的兼容性
pip install weasyprint flask
# 或者使用可选依赖安装
pip install -e ".[arm]" # ARM架构支持
pip install -e ".[full]" # 完整功能（包含所有可选功能）# 运行应用
python main.py- 点击侧边栏菜单项打开功能窗口
- 使用工具栏快捷按钮
- 拖动侧边栏调整宽度
- 点击标签页切换窗口
- 使用状态栏查看提示信息
[app]
title = MDI 桌面软件框架
version = 1.0.0
width = 1707
height = 944
theme = light
[toolbar]
show_text = True
text_position = bottom
icon_size = 24
[sidebar]
width = 220
collapsed_width = 48
show = true
[colors]
# 主题颜色配置
toolbar_bg = #2c3e50
toolbar_fg = #ecf0f1
toolbar_active = #3498db
sidebar_bg = #34495e
sidebar_fg = #ecf0f1
sidebar_hover = #3d566e
sidebar_active = #2980b9
sidebar_header_bg = #2c3e50
tab_bg = #dde3ea
tab_active_bg = #3498db
tab_active_fg = #ffffff
tab_fg = #2c3e50
statusbar_bg = #2c3e50
statusbar_fg = #ecf0f1
content_bg = #f5f6fa
tooltip_bg = #fff9c4
tooltip_fg = #000000
[icons.toolbar]
# 工具栏图标配置
home = icons/toolbar/home.png
settings = icons/toolbar/settings.png
sidebar = icons/toolbar/sidebar.png
sidebar_expand = icons/toolbar/sidebar_expand.png
fullscreen = icons/toolbar/fullscreen.png
exit = icons/toolbar/exit.png
[icons.sidebar]
# 侧边栏图标配置
workstation = icons/sidebar/workstation.png
dashboard = icons/sidebar/home.png
overview = icons/sidebar/overview.png
reports = icons/sidebar/reports.png
daily_report = icons/sidebar/daily_report.png
monthly_report = icons/sidebar/monthly_report.png
yearly_report = icons/sidebar/yearly_report.png
system = icons/sidebar/system.png
user = icons/sidebar/users.png
settings = icons/sidebar/settings.png
password = icons/sidebar/password.png
lock = icons/sidebar/lock.png
interface_designer = icons/sidebar/interface_designer.png
student_management = icons/sidebar/student_management.png
[icons.interface_designer]
# 界面设计器图标配置
document = icons/interface_designer/document.png
chart = icons/interface_designer/chart.png
settings = icons/interface_designer/settings.png
tool = icons/interface_designer/tool.png
edit = icons/interface_designer/edit.png
target = icons/interface_designer/target.png
growth = icons/interface_designer/growth.png
business = icons/interface_designer/business.png
search = icons/interface_designer/search.png
star = icons/interface_designer/star.png
[icons.home]
# 首页图标配置
users = icons/home/users.png
data = icons/home/data.png
pending = icons/home/pending.png
status_ok = icons/home/status_ok.png
password = icons/home/password.png
settings = icons/home/settings.png
user_mgmt = icons/home/users.png
report = icons/home/report.png
password_action = icons/home/password.png
report_view = icons/home/data.png
add_user = icons/home/users.png
settings_action = icons/home/settings.png
export = icons/home/report.png修改 config.ini 后，重启应用即可生效。部分配置（如工具栏显示文字）支持实时切换。
| 模式 | 说明 | 适用场景 | 配置方式 |
|---|---|---|---|
| 代码模式 | 继承BaseWindow，纯Python代码实现 | 复杂业务逻辑、需要高度定制 | mode: "code" |
| 配置模式 | 使用JSON配置文件定义UI | 简单表单、快速原型 | mode: "config" |
| UI文件模式 | 使用pygubu .ui文件 | 可视化设计、传统方式 | UI_FILE: "path.ui" |
步骤 1：创建 UI 配置文件
创建 config/ui/my_window.json：
{
"type": "frame",
"bg": "#f5f6fa",
"layout": {
"type": "pack",
"fill": "both",
"expand": true
},
"children": [
{
"type": "label",
"text": "欢迎使用配置驱动的窗口！",
"bg": "#ffffff",
"fg": "#2c3e50",
"font": ["微软雅黑", 12, "bold"],
"layout": {
"type": "pack",
"pady": 20
}
},
{
"type": "button",
"text": "点击我",
"bg": "#3498db",
"fg": "#ffffff",
"action": "show_info:你好！",
"layout": {
"type": "pack",
"pady": 10
}
}
]
}步骤 2：修改菜单配置
编辑 config/menus.json，添加菜单项：
{
"group": "我的模块",
"icon": "icons/sidebar/my_module.png",
"items": [
{
"title": "我的功能",
"icon": "icons/sidebar/my_feature.png",
"window": {
"mode": "config",
"class": "config/ui/my_window.json"
}
}
]
}步骤 3：重启应用
完成！无需编写任何 Python 代码，界面已经可以使用了。
步骤 1：创建窗口类
新建 windows/my_feature_window.py：
from windows.base_window import BaseWindow
class MyFeatureWindow(BaseWindow):
UI_FILE = "" # 不使用UI文件，纯代码实现
MAIN_WIDGET = "main_frame"
def __init__(self, parent, colors, config=None):
super().__init__(parent, colors, config)
def _on_ui_loaded(self):
self._build_ui()
def _build_ui(self):
import tkinter as tk
frame = self._frame
frame.configure(bg=self.colors["content_bg"])
tk.Label(
frame, text="我的窗口",
bg=self.colors["content_bg"],
font=("微软雅黑", 14, "bold")
).pack(pady=20)步骤 2：修改菜单配置
编辑 config/menus.json，添加菜单项：
{
"group": "我的模块",
"icon": "icons/sidebar/my_module.png",
"items": [
{
"title": "我的功能",
"icon": "icons/sidebar/my_feature.png",
"window": {
"mode": "code",
"class": "my_feature_window.MyFeatureWindow"
}
}
]
}步骤 3：重启应用
完成！
# 获取控件
widget = self.get_widget("widget_id")
# 消息提示
self.show_info("提示信息")
self.show_warning("警告信息")
self.show_error("错误信息")
# 确认对话框
if self.ask_yes_no("确定要执行吗？"):
# 用户点击了"是"
pass
# 访问配置
title = self.config.get("app", "title")
width = self.config.getint("app", "width")
# 访问颜色
bg_color = self.colors["content_bg"]本文档详细介绍了如何在 MDI 框架中从零开始创建一个新的 UI 界面。
- 使用 pygubu-designer 设计界面 - 可视化设计器创建 UI
- 创建窗口类 - 继承 BaseWindow 并实现窗口逻辑
- 注册菜单项 - 在配置文件中添加菜单项
- 测试和调试 - 运行应用程序验证功能
# 在项目根目录运行
pygubu-designer在 pygubu-designer 中：
-
创建新项目
- File → New
- 选择保存位置（建议在项目根目录）
-
添加控件
- 从左侧工具栏拖拽控件到设计区域
- 常用控件：
- Frame - 容器
- Label - 标签
- Entry - 输入框
- Button - 按钮
- Combobox - 下拉框
- Checkbutton - 复选框
- Text - 文本框
-
设置控件属性
- 在右侧属性面板设置控件属性
- 重要属性：
id- 控件唯一标识符（必需）text- 显示文本background- 背景颜色foreground- 前景颜色font- 字体
-
设置布局
- 使用 pack 布局管理器
- 设置 packing 属性：
fill- 填充方式（x, y, both）expand- 是否扩展side- 位置（left, right, top, bottom）padx/pady- 外边距ipadx/ipady- 内边距
-
保存项目
- File → Save Project
- 保存为
.ui文件
-
文件位置
- 保存到
ui/目录 - 命名规范：
{window_name}.ui - 例如：
my_window.ui
- 保存到
-
重要注意事项
- 顶层控件的
id必须与窗口类的MAIN_WIDGET匹配 - 所有控件
id必须唯一 - 建议使用有意义的命名（如
name_entry,submit_button）
- 顶层控件的
在 windows/ 目录创建新的 Python 文件：
-
文件命名
- 命名规范：
{window_name}.py - 例如：
my_window.py
- 命名规范：
-
文件位置
- 必须在
windows/目录 - 与菜单配置中的类名匹配
- 必须在
"""
窗口描述文档
说明窗口的用途和功能
"""
from windows.base_window import BaseWindow
import tkinter as tk
from tkinter import messagebox
class MyWindow(BaseWindow):
"""窗口类描述"""
# UI 文件路径（相对于项目根目录）
UI_FILE = "ui/my_window.ui"
# UI 文件中的顶层控件 id
MAIN_WIDGET = "main_frame"
def __init__(self, parent: tk.Widget, colors: dict, config=None):
super().__init__(parent, colors, config)
def _on_ui_loaded(self):
"""UI 加载完成后调用，获取控件并绑定事件"""
# 获取控件
self.header_label = self.get_widget("header_label")
# 绑定事件
if self.header_label:
self.header_label.bind("<Button-1>", self.on_label_click)
def on_label_click(self, event):
"""标签点击事件"""
self.show_info("提示", "标签被点击了")__init__方法：初始化窗口，调用父类构造函数_on_ui_loaded方法：UI 加载完成后自动调用，获取 UI 中的控件，绑定事件处理器get_widget方法：从 UI 中获取控件，参数为控件的id- 常用方法（继承自 BaseWindow）：
show_info(title, message)- 显示信息对话框show_warning(message)- 显示警告对话框show_error(message)- 显示错误对话框show_question(title, message)- 显示确认对话框
编辑 config/menus.json 文件：
{
"version": "1.0.0",
"description": "MDI框架菜单配置文件",
"menus": [
{
"group": "我的模块",
"icon": "icons/sidebar/my_module.png",
"items": [
{
"title": "我的功能",
"icon": "icons/sidebar/my_feature.png",
"window": {
"mode": "code",
"class": "my_window.MyWindow"
}
}
]
}
]
}-
菜单组（Menu Group）：
group- 菜单组名称icon- 菜单组图标路径items- 菜单项列表
-
菜单项（Menu Item）：
title- 菜单项标题icon- 菜单项图标路径window- 窗口配置
-
窗口配置（Window Config）：
mode- 窗口模式"code"- 代码模式（使用窗口类）"config"- 配置模式（使用 JSON 配置）
class- 窗口类完整路径- 格式：
{module_name}.{ClassName} - 例如：
my_window.MyWindow
- 格式：
# 在项目根目录运行
python main.py-
打开窗口
- 在侧边栏找到对应的菜单项
- 点击菜单项打开窗口
-
测试功能
- 测试所有输入控件
- 测试按钮功能
- 测试事件处理
- 测试表单验证
-
检查布局
- 窗口是否正常显示
- 控件布局是否正确
- 颜色和字体是否正确
应用程序会将所有错误信息输出到控制台：
[BaseWindow] 加载 UI 失败：
UI 文件不存在：ui/my_window.ui
-
错误1：UI 文件不存在
[BaseWindow] UI 文件不存在：ui/my_window.ui解决方法：检查 UI_FILE 路径是否正确，确认文件存在于
ui/目录 -
错误2：找不到控件
[BaseWindow] UI 文件中找不到 id 为 'main_frame' 的控件解决方法：检查 MAIN_WIDGET 是否与 UI 文件中的 id 匹配，确认控件 id 拼写正确
-
错误3：导入错误
ModuleNotFoundError: No module named 'my_window'解决方法：检查窗口类文件是否在
windows/目录，确认文件名与菜单配置中的模块名匹配 -
错误4：属性错误
AttributeError: 'NoneType' object has no attribute 'configure'解决方法：使用
get_widget()时检查返回值，添加空值检查：if widget: widget.configure(...)
-
命名规范
- UI 文件：
{window_name}.ui - 窗口类：
{WindowName}Window - 控件 id：
{control_type}_{purpose}（如name_entry,submit_button）
- UI 文件：
-
代码组织
- 每个窗口一个文件
- 文件名与类名对应
- 添加文档字符串说明用途
-
错误处理
- 使用空值检查
- 添加异常处理
- 提供友好的错误提示
-
UI 设计
- 保持一致的配色方案
- 使用合适的字体大小
- 确保布局响应式
-
性能优化
- 避免重复创建控件
- 使用变量管理状态
- 及时释放资源
# 打包
pyinstaller mdi_app.spec
# 打包后的文件在 dist/mdi_app.exe# 单文件打包
pyinstaller --onefile --windowed --name mdi_app ^
--add-data "ui;ui" ^
--add-data "config.ini;." ^
--add-data "icons;icons" ^
--hidden-import pygubu ^
--hidden-import pygubu.builder ^
--hidden-import PIL ^
--hidden-import PIL._tkinter_finder ^
main.py
# 目录打包（推荐，启动更快）
pyinstaller --windowed --name mdi_app ^
--add-data "ui;ui" ^
--add-data "config.ini;." ^
--add-data "icons;icons" ^
--hidden-import pygubu ^
--hidden-import pygubu.builder ^
--hidden-import PIL ^
--hidden-import PIL._tkinter_finder ^
main.py# mdi_app.spec 关键配置
hiddenimports=[
# pygubu 核心模块
'pygubu',
'pygubu.builder',
'pygubu.i18n',
# pygubu 插件
'pygubu.plugins',
'pygubu.plugins.pygubu',
'pygubu.plugins.pygubu.simpletooltip_bo',
# PIL/Pillow 图像处理
'PIL',
'PIL._tkinter_finder',
# 核心框架模块
'app',
'app.mdi_app',
'app.config_manager',
'app.sidebar',
'app.tab_manager',
'app.pygubu_custom_widgets',
'app.icon_manager',
'app.platform_utils',
'app.tooltip',
'app.window_config_manager',
'app.ui_generator',
'app.path_utils',
# 基础窗口模块
'windows',
'windows.base_window',
'windows.home_window',
'windows.student_management_window',
'windows.school_management_window',
# 学生信息管理系统模块
'app.models',
'app.database',
'app.excel_manager',
'app.print_manager',
'app.filter_dialog',
# 第三方扩展控件
'ttkwidgets',
'tksheet',
]
# 数据文件
datas=[
('config.ini', '.'),
('config/menus.json', 'config'),
('ui/*.ui', 'ui'),
('icons/home/*.png', 'icons/home'),
('icons/sidebar/*.png', 'icons/sidebar'),
('icons/toolbar/*.png', 'icons/toolbar'),
]
# 控制台窗口（False=无控制台窗口）
console=False
### 打包后测试
```bash
# 进入 dist 目录
cd dist
# 运行打包后的程序
mdi_app.exe- 使用目录打包而非单文件打包：启动速度更快
- 排除不需要的模块：在 spec 文件中添加
excludes参数 - 使用 UPX 压缩：已在 spec 文件中启用
- 添加图标：在 spec 文件中设置
icon='path/to/icon.ico'
打包完成后，需要发布以下文件：
dist/
├── mdi_app.exe # 主程序
├── ui/ # UI 文件目录
├── config.ini # 配置文件
└── icons/ # 图标文件目录
| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.9+ | 编程语言 |
| tkinter | 内置 | GUI 框架 |
| pygubu | 0.40+ | UI 构建器 |
| Pillow | 10.0+ | 图像处理 |
| ttkwidgets | 0.13.0+ | 扩展控件 |
| tksheet | 7.6.0+ | 表格控件 |
| PyInstaller | 6.19.0+ | 打包工具 |
| SQLAlchemy | 2.0.49+ | ORM 框架 |
| openpyxl | 3.1.5+ | Excel 处理 |
| reportlab | 4.4.10+ | PDF 生成 |
| pymysql | 1.1.0+ | MySQL 驱动 |
| opencv-python | 4.8.0+ | 计算机视觉 |
| pyzbar | 0.1.9+ | 二维码/条形码识别 |
| pytesseract | 0.3.10+ | OCR 文字识别 |
编辑 config.ini 文件中的 [colors] 部分，修改对应的颜色值，然后重启应用。
编辑 config/menus.json 文件，在 menus 数组中添加新的菜单组或菜单项。
在窗口类中设置 HOT_RELOAD = False，或者在 base_window.py 中全局禁用。
- 检查
mdi_app.spec中的hiddenimports是否包含所有需要的模块 - 确保所有依赖文件（UI文件、配置文件、图标）都已正确打包
- 查看控制台输出，定位具体的错误信息
- 在
app/pygubu_custom_widgets.py中注册自定义控件 - 在 pygubu-designer 中使用自定义控件
- 确保打包时包含自定义控件的模块
可以使用以下方式：
- SQLite 数据库
- JSON 文件
- CSV 文件
- 其他数据库（如 MySQL、PostgreSQL）
- 创建语言配置文件
- 在窗口加载时根据用户选择加载对应的语言文件
- 使用字典或配置管理器管理多语言文本
框架提供了一个学校信息管理系统示例，展示了如何使用框架开发基础数据管理应用。
- 数据库管理：支持SQLite（单机版）和MySQL（网络版）
- 数据编辑：使用tksheet控件，支持直接在表格中编辑
- 数据验证：学校代码长度验证（5位）
- 导入导出：支持Excel批量导入导出
- 未保存提示：关闭窗口时提示未保存的修改
windows/
└── school_management_window.py # 学校信息管理窗口（使用UI文件）
ui/
└── school_management.ui # 学校信息管理UI文件
import tkinter as tk
from app.database import DatabaseManager
from windows.school_management_window import SchoolManagementWindow
# 创建数据库管理器
db = DatabaseManager('sqlite', db_path='data.db')
# 创建学校信息管理窗口
root = tk.Tk()
window = SchoolManagementWindow(root, colors, db_manager=db)
root.mainloop()# 运行应用
python main.py在侧边栏"基础数据"分组中可以找到学校信息管理的菜单项，点击即可打开学校信息管理窗口。
学校信息表 (t_xx)
| 字段 | 类型 | 说明 |
|---|---|---|
| xxdm | String(5) | 学校代码（主键） |
| xxmc | String(50) | 学校名称 |
框架提供了一个完整的学生信息管理系统示例，展示了如何使用框架开发复杂的数据管理应用。
- 数据库管理：支持SQLite（单机版）和MySQL（网络版）
- 数据编辑：使用tksheet控件，支持直接在表格中编辑
- 数据验证：身高范围验证（0-250厘米）
- 导入导出：支持Excel批量导入导出
- 打印功能：生成PDF格式的打印预览，支持打印机选择、纸张类型、页边距设置、对齐方式选择（左对齐/居中/右对齐）
- 筛选排序：多条件筛选、列标题排序
- 未保存提示：关闭窗口时提示未保存的修改
app/
├── models.py # 数据库模型定义
├── database.py # 数据库管理类
├── excel_manager.py # Excel导入导出管理
├── print_manager.py # 打印管理
└── filter_dialog.py # 筛选对话框
windows/
├── base_data_management_window.py # 数据管理窗口基类
├── school_management_window.py # 学校信息管理窗口（使用UI文件）
└── student_management_window.py # 学生信息管理窗口（使用UI文件）
ui/
├── school_management.ui # 学校信息管理UI文件
└── student_management.ui # 学生信息管理UI文件
import tkinter as tk
from app.database import DatabaseManager
from windows.student_management_window import StudentManagementWindow
# 创建数据库管理器
db = DatabaseManager('sqlite', db_path='data.db')
# 创建学生信息管理窗口
root = tk.Tk()
window = StudentManagementWindow(root, colors, db_manager=db)
root.mainloop()# 运行应用
python main.py在侧边栏中可以找到学生信息管理系统的菜单项，点击即可打开学生信息管理窗口。
1. DatabaseManager - 数据库管理类
from app.database import DatabaseManager
# 创建数据库管理器
db = DatabaseManager('sqlite', db_path='data.db')
# 查询学生
students = db.get_students()
# 添加学生
db.add_student({
'xsdm': '20240001',
'xm': '张三',
'xb': '1',
'sfzh': '110101200001011234',
'xxdm_id': '00001',
'sg': 175
})
# 批量操作
db.batch_add_students(students_list)
db.batch_update_students(updates_list)
db.batch_delete_students(xsdm_list)2. StudentManagementWindow - 学生信息管理窗口
from windows.student_management_window import StudentManagementWindow
# 创建窗口
window = StudentManagementWindow(parent, colors, db_manager=db)
# 检查未保存的修改
if window.check_unsaved_changes():
print("有未保存的修改")3. ExcelManager - Excel导入导出
from app.excel_manager import ExcelManager
excel_manager = ExcelManager()
# 导出数据
excel_manager.export_data(data, columns, 'output.xlsx', '学生信息一览表')
# 导入数据
imported_data = excel_manager.import_data('input.xlsx', columns)
# 导出模板
excel_manager.export_template(columns, 'template.xlsx', '学生信息导入模板')4. PrintManager - 打印管理
from app.print_manager import PrintManager
# 创建打印管理器
# 默认会自动检测环境，ARM架构会使用WeasyPrint
print_manager = PrintManager()
# 强制使用WeasyPrint（ARM架构推荐）
# print_manager = PrintManager(use_weasyprint=True)
# 强制使用ReportLab（传统方式）
# print_manager = PrintManager(use_weasyprint=False)
# 打印数据到PDF文件
print_manager.print_data_table(data, columns, 'output.pdf', '学生信息一览表')
# 打印预览窗口（推荐）
# - Windows/Intel架构：使用内置预览窗口
# - ARM架构：自动在浏览器中打开Web预览
print_manager.show_print_preview_window(parent, data, columns, '学生信息一览表')
# 直接打印到打印机
print_manager.print_to_printer(data, columns, '学生信息一览表', printer_name='打印机名称')
# 设置对齐方式
print_manager.table_alignment = 'LEFT' # 'LEFT', 'CENTER', 'RIGHT'
# 设置页边距（单位：厘米）
print_manager.margin_top = 1.5
print_manager.margin_bottom = 1.0
print_manager.margin_left = 1.0
print_manager.margin_right = 1.0
# 设置纸张大小和方向
print_manager.paper_size = 'A4' # 'A4', 'Letter', 'Legal'
print_manager.orientation = 'landscape' # 'landscape', 'portrait'打印引擎说明：
- ReportLab：传统PDF生成库，支持x86/x64架构，功能完整
- WeasyPrint：纯Python实现，ARM架构兼容性好，需要安装系统依赖
- Ubuntu/Debian:
sudo apt-get install libpango-1.0-0 libcairo2 - CentOS/RHEL:
sudo yum install pango cairo - macOS:
brew install pango cairo
- Ubuntu/Debian:
5. FilterDialog - 筛选对话框
from app.filter_dialog import FilterDialog
def apply_filter(filter_params):
# 应用筛选
filtered_data = db.get_students(filter_params)
# 更新显示
update_display(filtered_data)
# 显示筛选对话框
FilterDialog(parent, columns, apply_filter)学校信息表 (t_xx)
| 字段 | 类型 | 说明 |
|---|---|---|
| xxdm | String(5) | 学校代码（主键） |
| xxmc | String(50) | 学校名称 |
学生信息表 (t_xs)
| 字段 | 类型 | 说明 |
|---|---|---|
| xsdm | String(18) | 学生代码（主键） |
| xm | String(16) | 姓名 |
| xb | String(1) | 性别（1=男，2=女） |
| sfzh | String(18) | 身份证号 |
| xxdm_id | String(5) | 所属学校代码（外键） |
| sg | Integer | 身高（厘米） |
| cjks_yw | String(1) | 参加语文考试（1=参加，0=不参加） |
| cjks_sx | String(1) | 参加数学考试 |
| cjks_wy | String(1) | 参加外语考试 |
| cjks_ls | String(1) | 参加历史考试 |
| cjks_wl | String(1) | 参加物理考试 |
基于学生信息管理系统，可以快速开发其他数据管理窗口：
from windows.base_data_management_window import BaseDataManagementWindow
class MyDataManagementWindow(BaseDataManagementWindow):
def _init_managers(self):
super()._init_managers()
# 定义列配置
self.columns = [
{'key': 'id', 'title': 'ID', 'width': 80},
{'key': 'name', 'title': '名称', 'width': 150},
# 更多列...
]
def _setup_treeview(self, parent):
# 设置表格列
pass
def _load_data(self):
# 加载数据
pass
def _update_display(self):
# 更新显示
pass
def _get_item_key(self, item):
# 返回项目的唯一键
return item.get('id', '')框架提供了一个完整的OCR识别系统示例，展示了如何使用框架开发图像识别应用。
- 摄像头操作：自动检测、实时预览、参数设置
- 图像识别：OCR文字识别、二维码/条形码识别
- 图像处理：多种格式支持、实时预览、参数调整
- 纯代码模式：完全使用Python代码实现，无需UI文件
windows/
└── ocr_window.py # OCR识别窗口（纯代码模式）
import tkinter as tk
from windows.ocr_window import OCRWindow
# 创建OCR识别窗口
root = tk.Tk()
window = OCRWindow(root, colors)
root.mainloop()# 运行应用
python main.py在侧边栏"工作台"分组中可以找到OCR识别的菜单项，点击即可打开OCR识别窗口。
1. OCRWindow - OCR识别窗口
from windows.ocr_window import OCRWindow
# 创建窗口
window = OCRWindow(parent, colors)
# 开启摄像头预览
window._toggle_camera()
# 执行OCR识别
window._do_ocr()
# 选择图片识别
window._open_image()2. 摄像头参数设置
OCR识别窗口提供了完整的摄像头参数设置功能：
- 亮度：-127 到 127
- 对比度：0.5 到 3.0
- 饱和度：0.0 到 3.0
- 清晰度：0.0 到 5.0
- 伽玛：0.1 到 3.0
- 分辨率：320x240、640x480、1280x720、1920x1080
- 帧率：15、24、30、60 fps
3. 图像识别功能
# OCR文字识别
result = ocr.recognize_text(image)
# 二维码/条形码识别
result = ocr.recognize_barcode(image)Python依赖：
- opencv-python >= 4.8.0
- pyzbar >= 0.1.9
- pytesseract >= 0.3.10
Tesseract-OCR引擎：
- Windows: 从 UB Mannheim 下载安装
- Linux:
sudo apt-get install tesseract-ocr - macOS:
brew install tesseract
安装步骤：
# 1. 安装Python依赖
pip install opencv-python pyzbar pytesseract
# 2. 安装Tesseract-OCR引擎（Windows）
# 下载并运行安装程序：https://github.com/UB-Mannheim/tesseract/wiki
# 3. 配置Tesseract路径（如需要）
# 在代码中设置：pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'基于OCR识别系统，可以快速开发其他图像识别应用：
from windows.ocr_window import OCRWindow
class MyImageRecognitionWindow(OCRWindow):
def __init__(self, parent, colors, config=None):
super().__init__(parent, colors, config)
def _build_toolbar(self, parent):
# 自定义工具栏
super()._build_toolbar(parent)
# 添加自定义按钮...
def _do_ocr(self):
# 自定义OCR识别逻辑
pass
def _show_result(self, text: str, source: str = ""):
# 自定义结果显示
super()._show_result(text, source)
# 添加自定义处理...本项目采用 MIT 许可证。
欢迎提交 Issue 和 Pull Request！