@closedwhu/calendar

v0.3.3

Published

2 months ago

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![npm version](https://img.shields.io/npm/v/@closedwhu/calendar.svg)](https://www.npmjs.com/package/@closedwhu/calendar) [![pub.dev](https://img.s

0High
0Medium
0Low

hsukqilee

武汉大学 iCalendar 校历

武汉大学校历数据集合，支持导入各种日历应用，轻松管理学校日程。

项目简介

本项目提供武汉大学官方校历的 iCalendar 格式数据，目前包含从 2012 年到 2027 年（持续更新中）的完整校历信息。

本项目使用数据驱动架构，所有校历数据均存储在 data/*.json 中，通过 TypeScript、Dart、Go 三种语言原生导入，仓库内仅保留一份数据。

注意：本项目仅提供校历数据，不保证数据的绝对实时性。请以武汉大学官方发布的最新校历为准。

主要特性

官方数据源：基于武汉大学本科生院官方校历数据。
Sunday-Start 规范：所有教学周严格从周日开始，到周六结束，完美契合武大作息。
多语言支持：TypeScript/npm、Dart/Flutter、Go 三种语言原生导入，数据零重复。
自动更新：支持在线订阅，校历更新时自动同步。
网页预览：通过 calendar.whu.sb 动态加载并提供下载。

快速开始

在线使用

访问项目主页直接预览并下载所需的校历文件。

TypeScript / npm

npm install @closedwhu/calendar
# 或
pnpm add @closedwhu/calendar

import type { CalendarData } from '@closedwhu/calendar';

import allData from '@closedwhu/calendar/data';
import yearsList from '@closedwhu/calendar/years';
import ics2024 from '@closedwhu/calendar/ics/2024-2025.ics';

ESM / CDN（jsDelivr）

无需安装，直接在浏览器中导入。数据内联在 bundle 中，无运行时网络请求：

<script type="module">
  import { loadAllYears, getSemester, getSemesterForDate } from
    'https://cdn.jsdelivr.net/npm/@closedwhu/calendar@latest/dist/browser.js';

  console.log(loadAllYears().length, 'years');
  console.log(getSemester(2024, 1)?.name);          // "2024-2025第一学期"
  console.log(getSemesterForDate(new Date())?.name);  // 当前学期
</script>

Dart / Flutter (pub.dev)

dependencies:
  whu_calendar: ^0.3.2

import 'package:whu_calendar/whu_calendar.dart';

final repo = WhuCalendarRepository(rootBundle);
final years = await repo.loadAllYears();
final sem = await repo.getSemester(year: 2024, semester: 1);

Go

go get github.com/ClosedWHU/WHU-Calendar

import "github.com/ClosedWHU/WHU-Calendar"

years, _ := whucalendar.LoadAllYears()
sem, _ := whucalendar.GetSemester(2024, 1)

本地开发

克隆项目

git clone https://github.com/ClosedWHU/WHU-Calendar.git
cd WHU-Calendar

安装依赖

pnpm install

构建项目

pnpm run build

项目结构

whu-calendar/
├── data/                   # 结构化 JSON 校历数据（唯一数据源）
├── src/                    # TypeScript 引擎源文件
│   ├── types.ts            # CalendarData / CalendarEvent / Semester 类型定义
│   ├── browser.ts          # 浏览器 ESM 入口（查询 API + 数据内联）
│   ├── engine.ts           # 统一构建引擎（ICS 生成）
│   ├── check-alignment.ts  # 自动对齐校验工具
│   └── check-legacy-parity.ts # 溯源审计工具
├── dart/                   # Dart / Flutter 包
│   ├── pubspec.yaml
│   └── lib/
├── whucalendar.go          # Go 包（//go:embed data/*.json）
├── whucalendar_test.go
├── scripts/                # 构建脚本
│   ├── sync-data.sh        # 同步 data/ 到 dart/assets/data/
│   └── gen-browser-data.mjs # 生成 ESM bundle 数据
├── go.mod                  # module github.com/ClosedWHU/WHU-Calendar
├── functions/              # Cloudflare Worker API
├── dist/                   # 构建输出目录
│   ├── *.ics               # 生成的 ICS 文件
│   ├── browser.js          # 浏览器 ESM bundle（数据内联）
│   └── years.json          # 供前端使用的年份元数据
├── index.html              # 项目主页
└── README.md

数据说明

自 2026 年起，本项目弃用了 calendar_YYYY.ts 脚本方式，转而采用 JSON 数据驱动。

格式对比 (Legacy vs Modern)

| 特性 | Legacy (TS) | Modern (JSON) | | :----------- | :------------------------- | :------------------------- | | 存储方式 | 硬编码脚本 (legacy/*.ts) | 结构化数据 (data/*.json) | | 月份索引 | 0-indexed (0=Jan) | 1-indexed (1=Jan) | | 周起始日 | 视脚本而定 | 强制 Sunday (周日) | | 校验机制 | 无 | 自动化脚本审计 |

开发指南

添加新年度校历

在 data/ 目录下创建新的 YYYY-YYYY.json 文件（参考现有模板）。
日期规范：
- 月份使用真实数字（如 9 代表 9 月）。
- 每个学期的 start 日期必须固定为该周的星期天。
运行 pnpm run build 重新生成资源。
运行 npx tsx src/check-alignment.ts 进行审计。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme