ClassCharts API（JavaScript/TypeScript）

ClassCharts 是英国教育领域的课堂管理平台。本技能使用非官方的 classcharts-api JavaScript 库，获取家庭作业、行为记录、课表、留校处分、出勤情况、学校公告、徽章等数据。支持 家长 和 学生 两种身份认证方式。

重要提示：该 API 属于非官方接口。切勿在提示词、日志或已提交的代码中硬编码凭据。请使用环境变量或安全的密钥存储服务。

安装

npm install classcharts-api

运行要求：Node.js 20+ 或 Deno

认证方式

支持两类客户端，登录流程不同：

家长客户端

家长使用邮箱和密码登录，可访问所有已关联的学生档案。

import { ParentClient } from "classcharts-api";

const client = new ParentClient(
  process.env.CLASSCHARTS_EMAIL!,
  process.env.CLASSCHARTS_PASSWORD!,
);
await client.login();

// 默认操作第一个学生；如需切换，请调用 selectPupil
const pupils = client.pupils; // 或 await client.getPupils()
client.selectPupil(pupils[1].id); // 若有多个子女

学生客户端

学生使用 ClassCharts 学生代码及出生日期登录。

import { StudentClient } from "classcharts-api";

// 出生日期格式必须为 DD/MM/YYYY
const client = new StudentClient(
  process.env.CLASSCHARTS_CODE!, // 例如 "ABCD1234"
  "01/01/2010",
);
await client.login();

日期格式

通用方法（家长与学生均支持）

所有方法均需先执行 await client.login()。会话将在 3 分钟后自动续期。

仅家长可用的方法

仅学生可用的方法

快速示例

// 指定日期范围内的家庭作业
const homeworks = await client.getHomeworks({
  from: "2024-03-01",
  to: "2024-03-31",
  displayDate: "due_date",
});

// 今日课表
const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
const lessons = await client.getLessons({ date: today });

// 行为记录摘要
const behaviour = await client.getBehaviour({
  from: "2024-01-01",
  to: "2024-03-10",
});

// 学生端：列出奖励商店并完成购买
const rewards = await client.getRewards();
const purchase = await client.purchaseReward(rewards.data[0].id);

响应结构

所有响应均遵循 ClassChartsResponse 类型定义：

{
  success: 1,
  data: T,      // 根据接口不同，为数组或对象
  meta: M,      // 包含会话 ID、日期、计数等元信息
  error?: string
}

当 success === 0 时，将抛出错误。

适用场景

• 用户询问有关 ClassCharts、学校家庭作业、行为积分、课表、留校处分、出勤情况或奖励商店的问题。
• 用户希望对 ClassCharts 数据进行脚本化处理、系统集成或自动化操作。
• 用户在英国学校背景下提及家长门户或学生门户，并明确指向 ClassCharts。

相关链接

• 库文档
• 非官方 API 文档
• GitHub 仓库