Class Widgets 开源工具高效上手与个性化配置指南

Class Widgets 是一款采用模块化设计的开源桌面组件应用，专注于课程表管理与桌面信息展示。通过灵活的配置系统和可扩展的插件架构，用户能轻松打造个性化的学习辅助工具。本指南将帮助你从项目认知到功能定制，快速掌握这款工具的核心用法。

一、项目认知：模块化架构解析

1.1 核心功能模块

项目采用"功能内聚"设计原则，将核心能力拆解为三大模块：

Class-Widgets/
├── cses_mgr.py       # 课程表管理核心
├── weather.py        # 天气服务集成
└── plugin_plaza.py   # 插件生态支持

💡 为什么这样设计？ 单一模块负责单一功能，既方便维护又便于扩展新特性。

cses_mgr.py作为课程表管理中枢，处理课程数据的CRUD操作；weather.py整合多种天气API服务，提供环境感知能力；plugin_plaza.py则构建了插件市场框架，支持功能无限扩展。

1.2 资源支持体系

应用运行依赖三类关键资源：

Class-Widgets/
├── audio/            # 事件提示音效
├── font/             # 界面字体资源
└── ui/               # 主题与布局文件

⚠️ 注意：这些资源目录需保持完整结构，随意修改可能导致界面异常。其中ui/目录包含4套主题（default/hoshino/minimize/shiroko），通过切换主题可实现界面风格的一键转换。

二、核心功能解析：从启动到日常使用

2.1 应用唤醒流程

启动应用有两种方式，基础版适合普通用户：

python main.py

进阶用户可添加参数启动：

python main.py --theme dark --debug  # 深色主题+调试模式

启动后系统会依次完成配置加载→界面渲染→数据同步的初始化流程。主程序入口main.py就像乐队指挥，协调各个模块有序工作。

2.2 核心功能体验

应用主界面包含三大信息区块：

• 天气模块：左上角显示实时天气与温度
• 课程倒计时：中央区域展示下节课开始时间
• 课程安排：右侧显示当前与后续课程信息

💡 小技巧：点击课程卡片可快速进入编辑模式，按住拖拽可调整组件位置。

对比深色主题效果：

通过主题切换，可在明亮/暗黑模式间无缝切换，适应不同使用场景。

三、个性化配置：打造专属学习助手

3.1 基础配置入门

核心配置文件位于data/default_config.json，就像应用的"控制面板"，主要配置项：

{
  "ui": {
    "theme": "default",      // 主题选择：default/hoshino/minimize/shiroko
    "transparency": 0.8      // 窗口透明度：0.0(完全透明)-1.0(完全不透明)
  },
  "notifications": {
    "class_alert": 5,        // 课前提醒分钟数
    "sound_effect": true     // 是否启用提示音效
  }
}

修改后需重启应用生效。建议初次配置时先备份原始文件。

3.2 高级优化技巧

进阶用户可通过扩展字段实现更多定制：

{
  "advanced": {
    "custom_css": "./my_style.css",  // 自定义样式表路径
    "refresh_interval": 300,         // 数据刷新间隔(秒)
    "widget_positions": {            // 组件位置坐标
      "weather": {"x": 100, "y": 50},
      "timetable": {"x": 300, "y": 50}
    }
  }
}

💡 为什么这样设计？ 扩展字段既保持了配置文件的简洁，又为高级用户提供了定制空间。

3.3 常见问题解决

Q: 天气模块显示"数据加载失败"？
A: 检查data/weather_api.json中的API密钥是否有效，或尝试切换不同的天气数据源。

Q: 课程表数据丢失怎么办？
A: 系统自动备份位于data/backup/目录，可通过"设置→恢复数据"功能找回最近备份。

Q: 如何添加自定义铃声？
A: 将音频文件放入audio/目录，在配置文件中设置"sound_custom_path"字段指向该文件。

通过以上配置，Class Widgets将成为你学习生活的得力助手，既美观又实用。这款开源工具的模块化设计确保了它能随着你的需求不断进化，期待你在使用过程中发现更多可能性！