Class Widgets从入门到精通：桌面课程表管理实战指南

2026-03-09 04:39:34作者：温玫谨Lighthearted

一、核心功能解析

Class Widgets是一款专注于课程表管理的桌面组件应用，提供直观的课程展示、时间提醒和个性化配置功能。其核心价值在于将复杂的课程安排转化为一目了然的桌面信息，帮助用户高效管理学习时间。

1.1 课程表展示系统

功能定位：核心显示模块，负责将课程信息以可视化方式呈现
使用场景：日常学习中快速查看当前及后续课程安排
操作示例：启动应用后自动显示当日课程，通过鼠标悬停可查看课程详情

该模块主要通过cses_mgr.py实现课程数据管理，结合ui/目录下的界面模板文件渲染课程信息。

1.2 时间提醒组件

功能定位：提供课程开始、结束及自定义事件的倒计时提醒
使用场景：需要提前准备上课或重要事项提醒时
操作示例：在设置中开启"课前提醒"，系统将在课程开始前5分钟播放提示音

提醒功能由play_audio.py模块处理音频播放，配置文件位于data/default_config.json。

1.3 天气信息集成

功能定位：在课程表组件中同步显示天气数据
使用场景：根据天气情况准备当日学习所需物品
操作示例：系统自动获取当地天气，在桌面组件右上角显示温度和天气状况

天气数据通过weather.py模块从多个数据源获取，相关配置可在data/weather_api.json中调整。

1.4 主题定制系统

功能定位：允许用户自定义界面风格和布局
使用场景：根据个人喜好或桌面背景调整组件外观
操作示例：通过"设置→主题"切换不同界面风格，如默认、hoshino、shiroko等主题

主题文件存储在ui/目录下，每个主题包含独立的UI布局和样式配置。

二、环境准备

2.1 系统要求

操作系统：Windows 10/11、Linux或macOS
Python版本：3.8及以上
必要依赖：Git、pip包管理器

2.2 安装步骤

获取项目代码

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

安装依赖包
```
pip install -r requirements.txt
```
验证安装
```
python -m unittest discover tests/
```

💡 提示：如果遇到依赖安装失败，建议创建虚拟环境后重试：

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -r requirements.txt

三、快速上手

3.1 启动应用

基本启动命令：

python main.py

常用启动参数：

--debug：启用调试模式，显示详细日志
--theme <theme_name>：指定启动主题，如--theme hoshino
--lang <language_code>：设置界面语言，如--lang en_US

示例：使用shiroko主题并启用调试模式

python main.py --theme shiroko --debug

3.2 初始配置流程

首次启动设置
- [ ] 选择界面语言
- [ ] 设置所在城市（用于天气服务）
- [ ] 导入或创建课程表
导入课程表
- 通过"文件→导入"选择课程表文件
- 支持CSV和JSON格式的课程数据
- 示例课程表文件位于data/subject.json
基本界面操作
- 左键拖动：移动组件位置
- 右键点击：打开操作菜单
- 滚轮缩放：调整组件大小

3.3 常见问题排查

问题现象	可能原因	解决方案
应用启动后无显示	组件被放置在屏幕外	删除`data/default_config.json`后重启
天气信息不更新	网络连接问题	检查网络设置或更换天气数据源
课程表无法导入	文件格式错误	参考`data/subject.json`调整格式
提示音不播放	音频文件缺失	检查`audio/`目录下是否有音频文件

四、深度配置

4.1 基础配置

基础配置文件位于data/default_config.json，主要配置项如下：

配置项	默认值	推荐设置	说明
ui.theme	"default"	根据喜好选择	界面主题，可选default/hoshino/minimize/shiroko
notifications.enable	true	true	是否启用通知提醒
notifications.volume	50	30-70	提醒音量（0-100）
weather.update_interval	30	60	天气更新间隔（分钟）
widget.position.x	100	根据屏幕调整	组件X轴位置
widget.position.y	100	根据屏幕调整	组件Y轴位置

修改配置后，需执行以下操作之一使配置生效：

重启应用
在设置界面点击"应用配置"按钮
执行命令python main.py --reload-config

4.2 高级自定义

4.2.1 自定义主题

复制现有主题目录：
```
cp -r ui/default ui/my_custom_theme
```
修改主题样式：
- 编辑ui/my_custom_theme/theme.json调整颜色和布局
- 替换ui/my_custom_theme/preview/下的预览图片
- 修改UI文件（.ui）调整组件布局
应用自定义主题：
```
python main.py --theme my_custom_theme
```

4.2.2 课程提醒个性化

通过编辑data/default_schedule.json自定义提醒规则：

{
  "reminders": [
    {
      "event_type": "class_start",
      "advance_time": 5,
      "sound": "prepare_class.wav",
      "message": "课程即将开始"
    },
    {
      "event_type": "class_end",
      "advance_time": 0,
      "sound": "finish_class.wav",
      "message": "课程已结束"
    }
  ]
}