80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 课表日历生成器 (Class Schedule ICS Generator)
|
||
|
||
这是一个用于将学校提供的 **行政历 (Excel)** 和 **课表 (Excel)** 自动转换为通用日历文件 (`.ics`) 的 Python 脚本。
|
||
生成的日历文件可以直接导入到你的手机（iOS/Android）、Mac 日历、Outlook 或 Google Calendar 中。
|
||
|
||
## 功能特点
|
||
|
||
- **通用解析**：自动适配每学期新的日期，只需保证行政历中“周次”列和“课表”的星期列格式不变即可。
|
||
- **智能避开节假日**：行政历中带有“清明”、“劳动”、“端午”等汉字描述的日期，脚本会自动识别为节假日，并在生成当日日历时**自动跳过**，以免引发混乱。
|
||
- **完整的课程信息**：每节课自动包含：*课程名称* (标题)、*教室* (地点)、*代课班级/老师* (备注描述)。
|
||
|
||
---
|
||
|
||
## 依赖与安装 (首次使用)
|
||
|
||
本脚本依赖 Python 环境以及处理 Excel 文件的类库（主要是 `pandas` 和 `openpyxl`）。
|
||
|
||
为了避免污染全局 Python 环境或受到 macOS 系统限制，推荐使用 **虚拟环境 (venv)**。
|
||
|
||
### 1. 创建并激活虚拟环境
|
||
首次使用时，需要在项目根目录执行以下命令：
|
||
```bash
|
||
# 1. 创建虚拟环境 (名为 venv)
|
||
python3 -m venv venv
|
||
|
||
# 2. 激活虚拟环境 (每次运行脚本前都需要执行这一步)
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 2. 安装必要依赖库
|
||
在虚拟环境激活的状态下，安装解析表格所需的依赖：
|
||
```bash
|
||
pip install pandas openpyxl xlrd
|
||
```
|
||
|
||
---
|
||
|
||
## 使用说明 (每半年更新课表时)
|
||
|
||
当你拿到新学期的《课表.xlsx》和《行政历.xls》时，将它们放入该目录下，然后执行如下步骤：
|
||
|
||
### 1. 激活虚拟环境 (如果已在新终端)
|
||
```bash
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 2. 运行生成脚本
|
||
```bash
|
||
# 默认生成方式：
|
||
python generate_ics.py 课表.xlsx 行政历.xls
|
||
```
|
||
|
||
**可选参数**：
|
||
- `-o` 或 `--output`：指定输出的文件名（默认输出为 `schedule.ics`）
|
||
- `-w` 或 `--weeks`：指定生成多少周的课表（默认生成前 18 周）
|
||
|
||
**例如**：
|
||
```bash
|
||
python generate_ics.py 课表.xlsx 行政历.xls -o my_schedule.ics -w 16
|
||
```
|
||
|
||
### 3. 导入日历
|
||
运行成功后，目录中会多出一个 `.ics` 文件（如 `schedule.ics`）。
|
||
- **Mac/Windows**：直接双击使用自带的日历软件打开并导入即可。
|
||
- **手机**：将文件通过微信 / 隔空投送 (AirDrop) 传输到手机，再选择使用“日历”打开导入。
|
||
|
||
---
|
||
|
||
## 表格数据要求 (格式规范)
|
||
|
||
如果你未来发现脚本运行报错，请检查新的 Excel 文件是否满足以下基础格式要求：
|
||
1. **行政历**：
|
||
- 第一列必须为周次，包含大写中文数字 `"一"`，脚本依靠该行来定位第一周。
|
||
- 这行里必须至少有一列具有“带年份的完整日期”或被 Excel 识别为日期格式的内容，以供推算开学第一天的时间。
|
||
- 节假日放假只需在原本数字上加上中文名称（诸如“4清明”），脚本遇到汉字即认为是假期并自动调休跳过。
|
||
2. **课表**：
|
||
- 首列应包含完整的时间片段，如 `第1-2节 8:30~10:00`（必须包含 `8:30~10:00`）。
|
||
- 列标题需带有 `"星期一"` 至 `"星期五"` 等字样。
|
||
- 单元格内换行规则：第一行为课程名，中间为人群/班级描述，最后一行为地点教室（脚本通过换行符 `\n` 进行拆分）。
|