学校教务系统适配

约 2722 字大约 9 分钟

2026-03-04

本应用支持用户通过自定义 JavaScript 脚本获取任何来源（如教务系统、API 接口等）的课程数据，并将其导入到应用中。您只需要使用我们提供的桥接 API，并将数据解析成我们定义好的结构即可。

建议开发流程

Alpha 阶段
- 使用浏览器插件测试工具开发你的第一个版本的适配代码
- 对插件导出的 json 数据进行检查，确认没有问题后就可以进入下一个阶段
Beta阶段
详细适配指南参阅 XingHeYuZhuan/shiguang_warehouse
- Fork 适配代码仓库并建立自己的分支，建议在 resources/GLOBAL_TOOLS/test.js 里放置适配测试代码，应用定义这个位置作为适配占位符，用于在不更新索引的情况下测试适配代码
  注
  - 本仓库带有 lighthouse 标签，已在开发者版 APP 中关闭检查逻辑，请开发者对使用的仓库链接负责。
  - 注意提交 PR 请不要把测试的 test.js 也提交上去！
- 在开发者版 APP（红色图标）我的-更多-更新教务适配仓库中选择自定义仓库/私有仓库，填写仓库 URL 和分支后点击更新等待完成，然后点击教务系统导入-通用工具-适配代码测试，输入网址并访问后点击执行导入来进行测试
  提示
  可通过 ADB 调试连接 Android 设备来测试：
  1. 在 Android 设备上打开开发者选项并启用 USB 调试/无线调试，然后连接设备
  2. 在电脑上访问：
    Chrome: chrome://inspect#devices
    Edge: edge://inspect/#devices
  3. 在应用内启用 DevTools 网页调试
- 在 index/root_index.yaml 文件中登记
- 在 resources 目录创建学校文件夹
- 创建 adapters.yaml 和适配脚本
- 完成 Beta 阶段适配验证，确认没有问题后提交 Pull Request 到适配代码仓库等待合并
  重要
  - 为避免代码出现问题，main 分支启用分支保护，需要先合并到 pending 分支等待分支同步

数据类型定义

整体定义

Requiredcourses[]

课程数组

RequiredtimeSlots[]

时间段数组

Requiredconfig

课表配置

课程表（courses）

Optionalstring

课程唯一标识，内部参数，由程序自动生成，插件输出时建议省略

Requiredstring

课程名称

Requiredstring

教师姓名

Requiredstring

上课地点

Requiredint

星期几（1-7，1 表示星期一）

Requiredint

开始节次

Requiredint

结束节次

Optionalint

课程格子颜色，由程序自动生成，且依赖软件内部颜色方案配置，插件输出时建议省略

Requiredlist<int>

上课周次数组

Optionalboolean

false

是否使用自定义时间。为 true 时，customStartTime 和 customEndTime 必填，startSection 和 endSection 可忽略；为 false 或未提供时，startSection 和 endSection 必填

Optionalstring

自定义开始时间

Optionalstring

自定义结束时间

时间表（timeSlots）

Requiredint

节次编号

Requiredstring

开始时间（格式：HH:MM）

Requiredstring

结束时间（格式：HH:MM）

配置（config）

Optionalstring

学期开始日期（格式：YYYY-MM-DD）

Optionalint

20

学期总周数

Optionalint

45

默认课程时长（单位：分钟）

Optionalint

10

默认课间休息时长（单位：分钟）

Optionalint

1

一周的第一天，1 代表星期一，7 代表星期日

提示

Android 桥接 API 详解

通过全局对象 window.AndroidBridgePromise（用于异步交互）和 AndroidBridge（用于同步操作）来提供 js 与原生功能的交互能力。

注意

所有涉及到用户界面交互或数据保存的调用都应该是异步的，使用 window.AndroidBridgePromise 并配合 await 关键字编写适配代码。

异步交互 API (`window.AndroidBridgePromise`)

这些方法会阻塞 JS 的执行，直到用户在原生 Compose UI 上完成操作或原生逻辑执行完毕，并返回一个 Promise。

显示公告弹窗：`showAlert(title, content, confirmText)`

用于向用户显示一个简单的通知，并等待用户确认。

参数:
- title (String): 弹窗标题。
- content (String): 弹窗内容。
- confirmText (String): 确认按钮的文本。
返回值 (Promise):
- true: 用户点击了确认按钮。
- false: 用户取消或关闭了弹窗。

示例：

async function promptUserToStart() {
    const confirmed = await window.AndroidBridgePromise.showAlert(
        "重要通知",
        "导入前请确保您已成功登录教务系统。",
        "好的，开始"
    );
    if (!confirmed) {
        AndroidBridge.showToast("用户取消了导入。");
        // 如果用户取消，必须立即停止后续流程
        return null;
    }
    return true;
}

显示输入框弹窗：`showPrompt(title, tip, defaultText, validatorJsFunction)`

用于获取用户的输入（例如学年、验证码等），并支持在 JS 侧进行输入验证。

参数:
- title (String): 弹窗标题。
- tip (String): 输入框的提示文本。
- defaultText (String): 输入框的默认文本。
- validatorJsFunction (String): 全局作用域中定义的验证函数名称。
返回值 (Promise):
- 用户输入的内容 (String)。
- null: 用户取消了输入。

验证函数要求 (validatorJsFunction): 该函数必须在 JS 全局作用域中定义，接受一个参数（用户输入 input），并根据结果返回：

false：表示验证通过。
错误信息 (String)：表示验证失败，原生 UI 会显示此错误信息。

示例：

// 全局验证函数示例
function validateYearInput(input) {
    if (/^[0-9]{4}$/.test(input)) {
        return false; // 验证通过
    } else {
        return "请输入四位数字的学年！"; // 验证失败
    }
}

async function getAcademicYear() {
    const yearSelection = await window.AndroidBridgePromise.showPrompt(
        "选择学年", 
        "请输入要导入课程的学年（如 2024）:",
        "2024", 
        "validateYearInput" // 传入全局函数名
    );
    // yearSelection 是用户输入的年份字符串或 null
    return yearSelection;
}

显示单选列表弹窗：`showSingleSelection(title, itemsJsonString, defaultSelectedIndex)`

用于让用户从预设的列表中选择一个选项（例如选择学期）。

参数:
- title (String): 弹窗标题。
- itemsJsonString (String): 选项列表的 JSON 字符串，例如 ["选项1", "选项2"]。
- defaultSelectedIndex (Int): 默认选中项的索引（从 0 开始），-1 表示不选中。
返回值 (Promise):
- 用户选择的选项索引 (Int, $\ge 0$ )。
- null: 用户取消了选择。

示例：

async function selectSemester() {
    const semesters = ["1（第一学期）", "2（第二学期）"];
    const semesterIndex = await window.AndroidBridgePromise.showSingleSelection(
        "选择学期", 
        JSON.stringify(semesters), // 必须是 JSON 字符串
        -1 // 默认不选中
    );
    // semesterIndex 是选中的索引或 null
    return semesterIndex;
}

提交课程数据：`saveImportedCourses(coursesJsonString)`

将解析完成的课程数据提交给应用保存。

参数:
- coursesJsonString (String): 包含所有课程数据的 JSON 字符串（需符合 1.1 节定义的结构）。
返回值 (Promise):
- true: 课程导入成功。
- 抛出 Error: 导入失败。

示例：

async function saveCourses(parsedCourses) {
    try {
        await window.AndroidBridgePromise.saveImportedCourses(JSON.stringify(parsedCourses));
        AndroidBridge.showToast(`成功导入 ${parsedCourses.length} 门课程！`);
        return true;
    } catch (error) {
        AndroidBridge.showToast(`保存失败: ${error.message}`);
        return false;
    }
}

提交时间段数据：`savePresetTimeSlots(timeSlotsJsonString)`

将解析完成的预设时间段数据提交给应用保存。

参数:
- timeSlotsJsonString (String): 包含所有时间段数据的 JSON 字符串（需符合 1.2 节定义的结构）。
返回值 (Promise):
- true: 时间段导入成功。
- 抛出 Error: 导入失败。

示例：

async function importPresetTimeSlots() {
    const presetTimeSlots = [/* ... TimeSlotJsonModel 数组 ... */];
    try {
        await window.AndroidBridgePromise.savePresetTimeSlots(JSON.stringify(presetTimeSlots));
        AndroidBridge.showToast("预设时间段导入成功！");
        return true; // 添加返回值
    } catch (error) {
        AndroidBridge.showToast("导入时间段失败: " + error.message);
        return false; // 添加返回值
    }
}

提交课表配置数据：`saveCourseConfig(configJsonString)`

将解析完成的课表配置数据（如学期开始日期、总周数等）提交给应用保存。

参数:
- configJsonString (String): 包含课表配置数据的 JSON 字符串（需符合 1.3 节定义的结构）。
返回值 (Promise):
- true: 配置导入成功。
- 抛出 Error: 导入失败。

示例：

async function saveConfig() {
    const configData = {
        semesterStartDate: "2024-09-01",
        semesterTotalWeeks: 18,
        // 假设教务系统返回的课间只有 5 分钟
        defaultBreakDuration: 5 
    };
    try {
        await window.AndroidBridgePromise.saveCourseConfig(JSON.stringify(configData));
        AndroidBridge.showToast("课表配置更新成功！");
        return true;
    } catch (error) {
        AndroidBridge.showToast("保存配置失败: " + error.message);
        return false;
    }
}

同步辅助 API (`AndroidBridge`)

这些方法是同步调用，不会阻塞 JS 流程，主要用于即时反馈或通知。

显示 Toast 消息：`AndroidBridge.showToast(message)`

在 Android 底部短暂显示一条提示信息。

参数: message (String)。

示例：

AndroidBridge.showToast("正在发送请求...");

通知任务完成：`AndroidBridge.notifyTaskCompletion()`

在整个导入流程逻辑成功完成后，调用此方法通知原生应用关闭 WebView 或执行收尾操作。这是一个生命周期结束信号。

参数: 无。

示例：

// 在 runImportFlow 函数的最后一步调用
AndroidBridge.notifyTaskCompletion();

适配脚本开发流程建议

适配脚本的核心在于使用 async/await 来按顺序编排用户交互、网络请求和数据保存。为了实现清晰、高可读性、高可维护性的代码，我们强烈推荐使用结构化编程的方式：将复杂的业务逻辑（如弹窗、网络请求）封装成独立的可调用函数。这样，runImportFlow 函数就如同一个流程控制树，它不再包含具体的业务代码，只负责以清晰的顺序调用这些函数，并在任何关键的取消或失败点，立即终止整个流程。

下面是一个采用这种推荐模式的伪代码示例，它清晰地展示了如何编排课程导入流程：

/**
 * 编排整个课程导入流程。
 * 在任何一步用户取消或发生错误时，都会立即退出，AndroidBridge.notifyTaskCompletion()应该只在成功后调用  
 */
async function runImportFlow() {
    AndroidBridge.showToast("课程导入流程即将开始...");

    // 1. 公告和前置检查。
    const alertConfirmed = await promptUserToStart();
    if (!alertConfirmed) {
        // 用户取消，直接退出
        return;
    }

    // 2. 获取用户输入参数。
    const academicYear = await getAcademicYear();
    if (academicYear === null) {
        AndroidBridge.showToast("导入已取消。");
        // 用户取消，直接退出
        return;
    }

    // 3. 获取学期。
    const semesterIndex = await selectSemester();
    if (semesterIndex === null) {
        AndroidBridge.showToast("导入已取消。");
        // 用户取消，直接退出
        return;
    }

    // 4. 网络请求和数据解析。
    const courses = await fetchAndParseCourses(academicYear, semesterIndex);
    if (courses === null) {
        // 请求失败或无数据，直接退出
        return;
    }

    // 5. [可选] 保存配置数据 (例如学期开始日期)
    const configSaveResult = await saveConfig(courses.config); // 假设 courses 对象中包含配置
    if (!configSaveResult) {
        // 保存配置失败，直接退出
        return;
    }

    // 6. 课程数据保存。
    const saveResult = await saveCourses(courses.courses);
    if (!saveResult) {
        // 保存课程数据失败，直接退出
        return;
    }

    // 7. [可选] 导入时间段。
    // 注意：即使时间段导入失败，通常也不阻止最终流程完成。
    await importPresetTimeSlots(); 

    // 8. 流程**完全成功**，发送结束信号。
    AndroidBridge.showToast("所有任务已完成！");
    AndroidBridge.notifyTaskCompletion();
}

// 启动导入流程
runImportFlow();

贡献者

Jursin

更新日志

2026/7/22 22:02

查看所有更新日志

7cd7e-更新教务适配开发文档于 2026/7/22
4e38e-更新预览图、更新日志于 2026/7/14
323c0-添加 DevTools 网页调试相关文档于 2026/3/19
15b59-docs: 完善适配脚本开发文档于 2026/3/16
20034-完成文档基本框架于 2026/3/4