Class Widgets 桌面课程组件使用指南

一、核心能力概览

Class Widgets 是一款轻量级桌面课程组件应用，能够实时显示当前课程信息并提供美观的桌面交互界面。其核心价值在于将课程表管理与桌面美化无缝融合，通过可定制的组件形式，让用户随时掌握学习进度与日程安排。

1.1 关键特性

• 实时课程展示：桌面悬浮组件动态显示当前及即将开始的课程
• 多主题切换：提供多种视觉风格，适配不同桌面环境
• 天气联动：集成天气信息显示，提供环境感知提醒
• 自定义配置：支持课程表、提醒方式、界面样式个性化调整

1.2 核心模块与资源分布

项目采用模块化架构设计，主要目录功能如下：

Class-Widgets/
├── audio/              # 音频资源：包含课程提醒音效
├── data/               # 数据存储：课程表与配置信息数据库
├── deb/                # 打包资源：Linux 系统安装包构建文件
├── font/               # 字体资源：确保跨平台显示一致性
├── i18n/               # 国际化支持：多语言翻译文件
├── img/                # 图像资源：界面元素与主题图片
├── ui/                 # 用户界面：主题与组件布局定义
├── view/               # 视图组件：交互界面与对话框
├── main.py             # 应用入口：程序启动与初始化
└── cses_mgr.py         # 课程管理：核心业务逻辑处理

图1：Class Widgets 桌面组件展示效果（浅色主题）

二、快速上手流程

2.1 环境准备

系统要求：

• Python 3.8+ 运行环境
• 支持 PyQt5 的图形界面环境
• 网络连接（用于天气数据获取）

获取项目：

git clone https://gitcode.com/gh_mirrors/cl/Class-Widgets
cd Class-Widgets

2.2 依赖安装

▶️ 使用 pip 安装依赖：

pip install -r requirements.txt

⚠️ 若安装失败：

1. 检查 Python 版本是否符合要求
2. 确保系统已安装相关依赖库（如 libqt5gui5）
3. 尝试使用虚拟环境隔离依赖

2.3 启动应用

▶️ 执行主程序：

python main.py

首次启动时，应用会自动创建默认配置文件并显示初始界面。成功启动后，桌面将出现课程组件窗口，默认显示系统时间与天气信息。

图2：Class Widgets 深色主题界面效果

三、深度配置指南

3.1 基础配置文件

应用核心配置文件为 data/default_config.json，修改后需重启应用生效。主要配置项说明：

配置项路径	默认值	说明
ui.theme	"default"	界面主题，可选值：default、hoshino、minimize、shiroko
ui.font_size	12	全局字体大小，建议范围 10-16
notifications.enable	true	是否启用课程提醒
notifications.volume	50	提醒音量（0-100）
weather.api_source	"amap"	天气数据源，支持 amap、open_meteo 等

3.2 课程表管理

课程数据存储在 data/subject.json 文件中，可通过两种方式管理：

1. 手动编辑：直接修改 JSON 文件，遵循以下格式：

{
  "monday": [
    {"name": "数学", "start": "08:00", "end": "08:45", "location": "教室A"}
  ]
}

2. 界面编辑：通过应用菜单中的「课程管理」进行可视化配置，支持拖拽调整顺序。

3.3 主题自定义

🔧 主题文件位于 ui/ 目录下，每个主题包含：

• theme.json：颜色与布局定义
• widget-*.ui：界面组件布局
• preview/：预览图片

自定义主题步骤：

1. 复制现有主题目录（如 ui/default/）
2. 修改样式文件与资源
3. 在配置文件中指定新主题名称

3.4 常见问题排查

问题现象	可能原因	解决方法
启动无界面	依赖缺失	重新安装 PyQt5：pip install PyQt5
天气不显示	API 密钥问题	检查 data/weather_api.json 配置
课程不更新	数据格式错误	验证 subject.json 语法正确性
组件无法移动	锁定状态	在设置中禁用「组件锁定」

四、高级功能拓展

4.1 插件系统

应用支持通过插件扩展功能，插件目录为 plugins/（需手动创建）。现有插件包括：

• 天气预警插件：提供极端天气提醒
• 倒计时插件：重要日期提醒功能

4.2 语音提醒

语音提醒功能由 generate_speech.py 模块实现，支持自定义提示语，配置项位于 data/default_config.json 的 speech 节点。

4.3 数据备份

建议定期备份以下文件以防止数据丢失：

• data/subject.json：课程表数据
• data/default_config.json：用户配置
• data/amap_weather.db：天气缓存数据库

通过以上配置与功能，Class Widgets 能够成为您学习生活的得力助手，提供直观的课程信息与个性化的桌面体验。如需进一步定制，可查阅项目 docs/ 目录下的高级配置指南。