Class Widgets：3步打造个性化课程表桌面组件

Class Widgets 是一款轻量级桌面组件应用，专注于课程表展示与时间管理。通过直观的界面设计和灵活的配置选项，帮助用户实时掌握课程安排、倒计时提醒和天气信息，让学习规划更高效。

一、核心功能概览：4大模块构建学习助手

Class Widgets 的核心架构围绕用户学习场景设计，主要包含以下功能模块：

1. 课程表管理模块（cses_mgr.py）

作为核心功能模块，负责课程数据的解析、存储和动态更新。支持自定义课程时间、教师信息和教室位置，通过与UI模块联动实现实时课程状态展示。

2. 桌面组件系统（ui/目录）

提供多样化的桌面小组件，包括当前课程卡片、下节课倒计时、天气信息面板等。支持主题切换（如默认主题、Hoshino主题），用户可根据桌面风格选择深色/浅色模式。

3. 音频提醒模块（play_audio.py）

通过audio/目录下的音频资源（如上课提醒、下课提示），结合系统通知机制，实现课程时间节点的声音提醒，帮助用户不错过重要课程。

4. 天气服务模块（weather.py）

整合多源天气数据（存储于data/目录的数据库文件），在桌面组件中实时显示温度、天气状况，提供个性化的出行建议。

二、3步快速上手：从安装到运行的完整指南

1. 环境准备与依赖检查

🔧 克隆项目仓库

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

🔧 环境检查清单

• Python 3.8+ 环境（通过python --version验证）
• 依赖安装：pip install -r requirements.txt
• 系统权限：确保应用有权限读取本地文件和显示桌面组件

⚠️ 常见问题：若出现"模块缺失"错误，检查requirements.txt是否完整，或尝试使用uv工具安装依赖（项目已提供uv.lock文件）。

2. 启动应用程序

🔧 运行主程序

python main.py

程序将自动初始化配置（读取data/default_config.json），加载默认课程表数据，并启动图形界面。首次运行时会显示欢迎引导窗口，帮助完成基础设置。

3. 界面熟悉与基础操作

启动后，桌面将显示课程组件面板，包含以下核心信息区域：

• 天气信息区：显示当前城市、温度和天气状况
• 倒计时区：显示距离下节课的剩余时间
• 课程状态区：展示当前课程名称和后续课程安排

通过右键点击组件可打开设置菜单，进行主题切换、课程编辑等操作。

三、深度配置指南：从基础到进阶的个性化方案

1. 基础配置（data/default_config.json）

核心配置项说明：

配置项	默认值	建议值	说明
ui.theme	"default"	"hoshino"	主题风格选择，可选default/hoshino/minimize
notifications.enable	true	true	是否启用课程提醒通知
speech.volume	50	70	语音提醒音量（0-100）

修改后需重启应用使配置生效。

2. 高级配置：自定义课程与主题

🔧 课程数据管理 课程信息存储于data/subject.json，可通过界面"课程编辑"功能添加/修改课程，或直接编辑JSON文件：

{
  "subjects": [
    {"name": "数学", "teacher": "张老师", "room": "302", "time": "08:30-10:00"}
  ]
}

🔧 主题定制 通过修改ui/[主题名]/theme.json调整组件样式，例如修改hoshino主题的背景透明度：

{
  "widget_bg_alpha": 0.85
}

修改后无需重启，在设置中切换主题即可预览效果。

扩展阅读

• 插件开发指南：项目支持通过plugins/目录扩展功能，详细开发文档位于docs/目录
• 数据备份与迁移：课程表数据可通过data/目录下的JSON文件导出，实现跨设备同步
• 高级主题开发：参考ui/shiroko/目录的主题实现，创建自定义桌面组件样式

通过以上配置，Class Widgets 可完全适配个人学习习惯，成为高效的学习时间管理助手。