Class Widgets：课程管理与桌面美化的一站式解决方案

核心功能解析

Class Widgets是一款专注于课程表管理的桌面组件应用，通过模块化设计实现了多维度信息聚合（Multidimensional Information Aggregation）与轻量化交互（Lightweight Interaction）。从开发者视角看，系统采用"核心控制-功能模块-界面渲染"的三层架构，各模块间通过事件总线实现松耦合通信。

功能模块关系网络

[main.py] → 核心控制模块
   ↑↓
┌────────────┬────────────┬────────────┬────────────┐
│ [cses_mgr] │ [weather]  │ [plugin]   │ [ui]       │
│ 课程管理   │ 天气服务   │ 插件系统   │ 界面渲染   │
└────────────┴────────────┴────────────┴────────────┘
   ↑↓           ↑↓           ↑↓           ↑↓
┌───────────────────────────────────────────────────┐
│                [utils.py] 工具模块                │
└───────────────────────────────────────────────────┘

核心模块详解

1. 课程管理模块 cses_mgr.py

功能定位：作为应用的数据核心，负责课程表的CRUD操作与时间逻辑判断
使用场景：从Excel导入课程数据、设置课程提醒、查看今日课表
扩展建议：可开发学期切换功能，通过data/subject.json扩展课程类型

2. 界面渲染模块 ui/

功能定位：控制桌面组件的视觉呈现，支持多主题切换
使用场景：在浅色/深色模式间切换、调整组件透明度
扩展建议：通过ui/default/theme.json添加自定义主题配色

3. 天气服务模块 weather.py

功能定位：整合多源天气API，提供环境信息展示
使用场景：显示实时温度、天气预警提醒
扩展建议：修改data/weather_api.json添加更多气象数据源

环境准备

系统要求

• 操作系统：Linux/macOS/Windows 10+
• Python版本：3.8以上
• 依赖项：ffmpeg（用于音频播放）、PyQt5（界面渲染）

安装步骤

1. 获取项目代码

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

2. 创建虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

3. 安装依赖

pip install -r requirements.txt

💡 依赖安装提示：如果出现PyQt5安装失败，可尝试使用系统包管理器安装：sudo apt install python3-pyqt5（Linux）或 brew install pyqt5（macOS）

实战操作

基础启动

# 常规启动
python main.py

# 调试模式（显示详细日志）
python main.py --debug

# 指定配置文件路径
python main.py --config ./data/default_config.json

参数说明：

• --debug：启用调试模式，日志会输出到./logs/app.log
• --config：自定义配置文件路径，默认使用./data/default_config.json
• --theme：启动时指定主题，如--theme dark直接使用深色模式

核心功能操作

1. 添加课程表

1. 打开主菜单（右键点击桌面组件）
2. 选择"课程管理" → "导入课程"
3. 选择Excel文件（支持.xlsx格式）
4. 映射表格列与课程属性（课程名、时间、地点等）

2. 切换主题

1. 打开设置界面（右键菜单 → "外观设置"）
2. 在主题选择器中选择"default"、"hoshino"或"minimize"
3. 实时预览效果后点击"应用"

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

图2：深色主题下的组件显示效果

个性化配置

课程提醒设置

配置文件：data/default_config.json

"notifications": {
  "class_reminder": 5,  // 课前5分钟提醒
  "sound_enabled": true, // 启用声音提醒
  "volume": 70,          // 提醒音量（0-100）
  "audio_file": "./audio/prepare_class.wav"  // 提醒音效
}

推荐配置：

• 学生用户：class_reminder: 10（提前10分钟准备）
• 教师用户：class_reminder: 30（提前30分钟备课）
• 图书馆场景：sound_enabled: false（静音模式）

界面自定义

通过修改ui/default/theme.json调整视觉效果：

"widget": {
  "opacity": 0.85,       // 组件透明度（0.1-1.0）
  "border_radius": 12,   // 圆角半径（像素）
  "font_size": 14,       // 字体大小
  "position": "top_right" // 屏幕位置（top_left/top_right/bottom_left/bottom_right）
}

💡 高级技巧：将opacity设为0.95并配合半透明壁纸，可实现"融入桌面"的视觉效果

新手常见误区

1. 配置文件格式错误

症状：启动时报JSONDecodeError
解决：使用JSON在线验证工具检查语法，重点关注：

• 引号必须为双引号"
• 键名必须用引号包裹
• 数组和对象结尾不能有逗号

2. 课程表不显示

排查步骤：

1. 检查data/subject.json是否存在有效数据
2. 确认系统时间是否正确（课程表基于当前时间显示）
3. 查看日志文件./logs/app.log寻找错误信息

3. 天气信息无法加载

解决方法：

1. 检查网络连接状态
2. 在data/weather_api.json中切换天气数据源
3. 验证API密钥是否有效（部分天气服务需要注册）

扩展与进阶

开发自定义主题

1. 在ui/目录下创建新主题文件夹（如my_theme）
2. 复制ui/default/下的文件结构
3. 修改theme.json和UI文件实现自定义样式
4. 在设置界面选择新主题

编写插件

通过plugin.py提供的接口开发功能扩展：

from plugin import BasePlugin

class TimerPlugin(BasePlugin):
    def __init__(self):
        super().__init__("timer", "计时器插件")
        
    def on_init(self):
        # 插件初始化逻辑
        pass
        
    def on_update(self):
        # 定时更新逻辑
        current_time = self.utils.get_current_time()
        self.update_widget(f"当前时间: {current_time}")

将插件文件放入plugins/目录，在设置界面启用即可生效。

---

通过本文指南，您已掌握Class Widgets的核心功能与配置方法。无论是日常课程管理还是桌面个性化，这款工具都能提供简洁而强大的支持。更多高级功能与扩展技巧，请参考项目内置文档或参与社区讨论。